On Fri, Jun 10, 2022 at 12:51:41PM +0200, Alejandro Colomar wrote: > Reported-by: Peter Xu <peterx@xxxxxxxxxx> > Signed-off-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> > --- > man7/man-pages.7 | 5 +++++ > 1 file changed, 5 insertions(+) > > diff --git a/man7/man-pages.7 b/man7/man-pages.7 > index 547ed660a..4da2dfe5c 100644 > --- a/man7/man-pages.7 > +++ b/man7/man-pages.7 > @@ -578,6 +578,11 @@ project. > For details not covered below, the Chicago Manual of Style > is usually a good source; > try also grepping for preexisting usage in the project source tree. > +.PP > +.UR https://www.ualberta.ca/\:computing-science/\:media-library/\:docs/\:unix-beginners.pdf > +UNIX for Beginners [2nd ed., Brian W. Kernighan] > +.UE > +also contains an interesting section on "Hints for Preparing Documents". > .SS Use of gender-neutral language > As far as possible, use gender-neutral language in the text of man > pages. > -- Thanks for adding this! There's a little bit of a pity though on that the PDF version will IMHO loose one very important aspect of being an live example of how to do semantics newlines itself. Personally after I read the format I don't even need to read the groff man page because the example is the best to describe that this rule means. I meant the possibility to quote the thing behind generated PDF just as you did in the commit message: ---8<--- Brian W. Kernighan, 1974 [UNIX For Beginners]: [ Hints for Preparing Documents Most documents go through several versions (always more than you expected) before they are finally finished. Accordingly, you should do whatever possible to make the job of changing them easy. First, when you do the purely mechanical operations of typing, type so subsequent editing will be easy. Start each sentence on a new line. Make lines short, and break lines at natural places, such as after commas and semicolons, rather than randomly. Since most people change documents by rewriting phrases and adding, deleting and rearranging sentences, these precautions simplify any editing you have to do later. ] ---8<--- So I was wondering whether this section (along with its newline formats, which is IMHO even more helpful) can be quoted altogether, because both the content and format could help the reader in this case. Thanks, -- Peter Xu
