Details
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
Just a suggestion for the example of using a different separator...
| sed.1 | ||
|---|---|---|
| 597 ↗ | (On Diff #26143) | I think it would look nicer with commas: echo bar| sed 's,bar,baz,' |
I don't see much value in having trivial examples; arguably, e.g. giving a link to famous http://sed.sourceforge.net/sed1line.txt would be more useful (and a smaller change).
I disagree. The value of having a trivial example is that it shows the reader the bare minimum usage. We should have at least a trivial example, a more complex example, and preferably a usable real-world example. The mdconfig(8) example of mounting an ISO image is a good example of the last kind.
| sed.1 | ||
|---|---|---|
| 592 ↗ | (On Diff #26143) | I'd suggest piping in more text but still changing only the single word: echo "An alternate word, like bar, is sometimes used in examples." | sed 's/bar/baz' Also, .Ql can be used to quote the literals. I'd prefer a highlight that doesn't use quotes, but am not quite sure of the right one to use at the moment. Replace .Ql bar with .Ql baz in an input stream piped from another command: |
| 595 ↗ | (On Diff #26143) | Use a slash in the substitution to show why a different separator character is useful. For instance: echo "/etc" | sed 's#/etc#/usr/local/etc#' |
| 600 ↗ | (On Diff #26143) | spelling: s/occurances/occurrences/ More active wording: Replace all occurrences of .Ql foo with .Ql bar in the file .Pa test.txt without creating a backup of the file: |
| sed.1 | ||
|---|---|---|
| 597 ↗ | (On Diff #26143) | Yeah, I just like '#' better.. |
That's because when users refer to mdconfig(8) they most probably want to mount something (an image), so having examples of that action is natural and useful. sed(1) is, on the contrary, general-purpose tool who's manual page serves as its command syntax reference.
Don't get me wrong, I'm not against useful examples (like some of the one-liners from the above link), but I'm a bit worried that majority of manpages will grow this stub EXAMPLES sections... Anyway, I'd probably be losing this argument (as I can see, we did add examples even for ls(1)), so never mind.
| sed.1 | ||
|---|---|---|
| 601 ↗ | (On Diff #26177) | Example is actually misleading: s/da1/ada1/ or even better s/da1/a&/ would suffice just fine. To show how separator is actually handy when working with path, why not use actual paths in the example? Like s,/usr/bin,/usr/local/bin, or something like that. And yes, I also vote for commas rather than hashes as alternative separator, as hashes reduce readability (they are visually heavy, while commas clearly stand out from actual expression and substitution). |
| sed.1 | ||
|---|---|---|
| 601 ↗ | (On Diff #26177) | It occurs to me that we can make this a better example by showing it both ways. I don't care what the text is, except that it contains a slash. So: Using a different separator can make working with text that contains slash characters easier. When the separator is the default slash character, instances of that character in the pattern must be escaped with a backslash. This usually makes the pattern more difficult to read. Using an alternate separator character can simplify the pattern. These two examples are equivalent: .Bd -literal -offset indent echo "Add 1/4 cup of water." | sed 's/1\/4/one quarter/' echo "Add 1/4 cup of water." | sed 's#1/4#one quarter#' .Ed |