Improve docs for string join
#11506
Improve docs for string join
#11506
Conversation
doc_src/cmds/string-join.rst
Outdated
|
|
||
| ``string join0`` joins its *STRING* arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as ``sort -z``. Exit status: 0 if at least one join was performed, or 1 otherwise. | ||
| ``-n`` or ``--no-empty``: Exclude empty strings from consideration (e.g. ``string join -n + a b "" c`` would expand to ``a+b+c`` not ``a+b++c``). |
There was a problem hiding this comment.
I wonder if we have this "list" style anywhere else?
I know it's common in man pages but we probably use full-sentences everywhere.
But the added whitespace seems to make it easier to read, so this looks good.
There was a problem hiding this comment.
Yes, this style does not seem to be commonly used in the fish docs. I like this style because it makes it easier to find the description of a particular flag, which is reinforced by this style being so common in other man pages.
doc_src/cmds/string-join.rst
Outdated
| Because Unix uses NUL as the string terminator, passing the output of ``string join0`` as an *argument* to a command (via a :ref:`command substitution <expand-command-substitution>`) won't actually work. Fish will pass the correct bytes along, but the command won't be able to tell where the argument ends. This is a limitation of Unix' argument passing. | ||
| ``-q`` or ``--quiet``: Do not print the strings, only set the exit status as described above. | ||
|
|
||
| **WARNING**: If you omit the ``--`` before the strings to be joined, any strings starting with |
There was a problem hiding this comment.
I'm not sure if the first letter after a colon is usually capitalized in English.
Not sure what our convention is but lowercase "If" would be my preference.
Our commit log is inconsistent..
same applies elsewhere in this patch
There was a problem hiding this comment.
It seems that capitalization of a complete sentence following a colon is mostly a stylistic choice in English. I think it makes sense to capitalize complete sentences, but it's something that I consider not particularly relevant.
Another option would be to drop the semicolons and use some means of formatting to separate the flags from their description. Not sure how well that would work in rst.
There was a problem hiding this comment.
I switched to the format commonly found in man pages. The docs for the complete command do something similar. Instead of separating short and long options with or, I use a comma, as this seems to be the style used in most man pages. This also works better with certain man page viewers. E.g. the viewer built into nvim colors the options correctly when separated by commas, but not when using or instead.
| failing. | ||
| This is also true if you specify a variable which expands to such a string instead of a literal string. | ||
| If you don't need to append flag arguments at the end of the command, | ||
| just always use ``--`` to avoid unwelcome surprises. |
There was a problem hiding this comment.
this is a general problem but yeah, it's probably fine to include it here more prominently
3c7410c to
e2b69e2
Compare
e2b69e2 to
ec8fa74
Compare
Fixes issue #11478