[Cc recipients: this message is only about typography and man(7) style] Hi Alex, At 2021-09-06T16:21:09+0200, Alejandro Colomar (man-pages) wrote: > > +.TH FILENAME 7 2021-09-06 "Linux" "Linux Programmer's Manual" > > +.SH NAME > > +.P > > I don't know the history of this (actually, I've always wondered why), > but .PP and .P are equivalent, AFAIK, and we use .PP. Yes, they are equivalent. I know of no man(7) implementation that distinguishes .LP, .PP, and .P semantically. groff_man(7)[1] briefly summarizes the historical growth of the man(7) macro, register, and string name repertoire. In the groff project, after years of being on the fence about the issue, as a style matter I settled on using and recommending simply ".P"[2]. I think it relieves the occasional man page author from having to retain a small amount of knowledge, the kind that has you wondering above. > > +.SH LEGAL FILENAMES > > See man-pages(7): > > Sections within a manual page > The list below shows conventional or suggested sections. > Most manual pages should include at least the highlighted > sections. Arrange a new manual page so that sections are > placed in the order shown in the list. > > NAME > SYNOPSIS > CONFIGURATION [Normally only in Section 4] > DESCRIPTION > OPTIONS [Normally only in Sections 1, 8] > EXIT STATUS [Normally only in Sections 1, 8] > RETURN VALUE [Normally only in Sections 2, 3] > ERRORS [Typically only in Sections 2, 3] > ENVIRONMENT > FILES > VERSIONS [Normally only in Sections 2, 3] > > ATTRIBUTES [Normally only in Sections 2, 3] > CONFORMING TO > NOTES > BUGS > EXAMPLES > AUTHORS [Discouraged] > REPORTING BUGS [Not used in man‐pages] > COPYRIGHT [Not used in man‐pages] > SEE ALSO > > Where a traditional heading would apply, please use it; > this kind of consistency can make the information easier to > understand. If you must, you can create your own headings > if they make things easier to understand (this can be espe‐ > cially useful for pages in Sections 4 and 5). However, be‐ > fore doing this, consider whether you could use the tradi‐ > tional headings, with some subsections (.SS) within those > sections. > > You could move sections into subsections of DESCRIPTION, and the > current subsections into tagged paragraphs (.TP). In the groff man page corpus, the rule above is honored in general but slightly relaxed for section 7 pages, due to that section's miscellaneous nature--it's hard to argue that section naming conventions for commands, library interfaces, device drivers, or file formats should apply to section 7 pages, because if they did, the page in question would be in one of those sections instead (or portions of it moved thence). > > +.P > > +A filename on a Linux system can consist of almost any sequence of UTF-8 > > See man-pages(7): > > Use semantic newlines > In the source of a manual page, new sentences should be > started on new lines, and long sentences should be split > into lines at clause breaks (commas, semicolons, colons, > and so on). This convention, sometimes known as "semantic > newlines", makes it easier to see the effect of patches, > which often operate at the level of individual sentences or > sentence clauses. > > > > +characters or, indeed, almost any sequence of bytes. > > +The exceptions are as follows. Maybe I've developed temporary blindness, but I don't see where Thaddeus didn't use semantic newlines in the adjacent quoted material. > Please, use a separate line and > .B \e0 > > We avoid \f. Yes! Thus does the moral arc of the universe bend toward justice! ...or at least readable man(7) source. > > +from\~\fB0\fR, the printable digit-zero character. > > Why did you use the non-breaking space here (and other places)? I > don't think it's necessary. It is a typographical best practice. It is often good typography to keep a line break from occurring between a preposition and its object, or between nouns where one is used as a determiner for the other. Thaddeus has supplied an example of the former above, and for the latter consider the following[3]. Integer overflow is guaranteed for large values .RI of\~ n . I know of no hard rule here, but I have inferred that such break prevention tends to be applied much more frequently adjacently to one- or two-character nouns, and seldom to never for longer ones. I believe the reason for the practice is to make reading more comfortable; it would be nice to only _ever_ break lines at phrase and clause boundaries, but applying a hard rule along these lines leads to worse esthetics (if the line is adjusted to both margins with large amounts of inter-word space) or ergonomics (if the line length varies dramatically within a paragraph). > > +Workarounds typically exist, chiefly via quotation, escape and the > > explicit +termination of options processing [see > > +.BR sh (1)]; > > I'd have used parentheses there. No? Was it, as in Mathematics, to > clearly differentiate the inner from the outer parentheses? If so, we > typically nest parentheses in the manual pages (as in here (see?)). > > However, I don't think it's wrong per se to use brackets... Is it > common in other places? Maybe the add some readability to the text, > and we hould use them. English style manuals tend to discourage the Lisp effect of nested parentheses[5]. The reference I've cited is consistent with other practices I've seen in the humanities, which is to turn to parentheses as a first resort and then adopt brackets only when already within a parenthesized context, whereas mathematical usage is to apply parentheses to the innermost level of nesting. Here, however, it would be jarring to change the man page citation style in a context-dependent manner, so Thaddeus inverted the ordering. This is a good practice. In technical writing, and arguably in _all_ writing, the demands of clarity must outweigh any syntactical or semantic rules. Our brains are more powerful parsing engines than any machine we have yet been able to contrive; it's okay to expect people to use them. :D That blank check having been written, a Hegelian synthesis applies: if your construction cannot simultaneously serve the demands of grammar, clarity, and good style...recast until it does! > Non-native English speakers may have trouble understanding "all but". > Maybe s/all but/not/? I think it's okay. From my limited knowledge of non-English languages, I expect it to calque in a way that will not startle the intuition. Personally, I acquired the construction when I was in primary school, but I admit that saying so invites a charge of being anecdotal. Or precocious. Or loquacious. > > +.SS Capitalization > > +.P > > +A loosely observed convention favors small letters in filenames where no > > +reason to use capitals exists. > > Most manual pages talking about capitalization typically use the term > 'case' (uppercase, lowercase, case sensitive, ...); probably because > of 'toupper()' and 'tolower()'. I think, for consistency, using the > same terminology would be better. This circle could be squared with the subsection heading "Letter case". > > +.P > > +Names of types and of certain other entities are sometimes capitalized in > > +programming languages like\~C++ and Python. > > Do you mean normal user conventions? I mean, the standard C++ library > (and the language) doesn't use uppercase, AFAIR. Not even in the > cases where C used it (e.g., _Bool) Stroustrup models first-letter capitalization of namespace, exception, class, and struct names in _The C++ Programming Language_ (3rd edition, 1997), so it's reasonably likely to show up in projects written in that language even if it's not in the standard library (which is much too huge for me to characterize in this respect). > > +.SH CONFORMING TO > > +.P > > +POSIX.1-2008, SUSv4. > The SUSv4 part of the standard is the same that is in POSIX.1-2008? > Or does it have any extensions regarding filenames that isn't in > POSIX? > > If both standards have the same exact contents about filenames, I'd > simplify this with POSIX.1-2008 only. Thaddeus is using a citation form modeled in standards(7), a Linux man-pages project page. Perhaps that page should offer some guidance for standards that appear in a comma-separated list in the paragraph tags. > > +.BR iswcntrl (3), > > +.BR iswgraph (3), > > +.BR mbrtowc (3), > > +.BR wcrtomb (3), I think it suffices to mention these functions only in passing in the body of the man page. Few readers are going to go straight from learning what a Unix filename is to multi-byte and wide character string encoding in C, and the few with that degree of ambition have already been steered in the right direction. In my opinion the "See also" section of a man page serves us best if there are two things it is _not_: (1) a recapitulation of all man page cross-references encountered in the page so far; and (2) a militantly strict subset of (1). In my view, "See also" is there to help two kinds of reader: (A) the kind who has not found the man page they were seeking, but might be in the right "neighborhood", and needs a hint to find the correct one (a wholly irrelevant page is best abandoned, and the output of "man -k" returned to); and (B) the kind who has found the page they are looking for but require greater depth on subsidiary, dependent, or closely-related topics. As with many things, identifying the members of such a set demands judgment, and judgment can be difficult, which is why some man page writers have a tendency to degenerate toward the more robotic interpretation that I discourage above. But if that roboticism is what is sought, we should design a robot to take care of it. One such automaton could be a man page cross-reference macro like mdoc(7) has (possibly with an optional argument to suppress inclusion for case (2) above), enabling the macro package to generate the "See also" section by itself. But I think that machine is something we _don't_ want[5]. We _want_ the "See also" section of a man page to be a curated product of judgment. Regards, Branden [1] https://man7.org/linux/man-pages/man7/groff_man.7.html [2] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=cf49e0fe7fdbaff94e21ebdcd3380c3559c2525d commit cf49e0fe7fdbaff94e21ebdcd3380c3559c2525d Author: G. Branden Robinson <g.branden.robinson@xxxxxxxxx> Date: Wed Jun 16 00:24:38 2021 +1000 [man]: Elevate "P" as canonical paragraph macro. Unfairly and capriciously elevate "P" as the preferred paragraphing macro for the man(7) language. This is slightly ahistorical; the original man macro package from 1979 in fact did not recognize the name "P" at all, but did support "LP" and "PP". However, "P" did show up in AT&T System III Unix (1980) and later in 4.3BSD (1986). I speculate that "LP" and "PP" were supported to accommodate the varying paragraphing preferences of those accustomed to the ms(7) macro package. However, anyone familiar with that package knows that these two macros mean different things, and have differing indentation behavior, which man(7) does not simulate. In that respect, "LP" and "PP" imply too much to ms veterans, and nothing useful at all to other man(7) users; the "L" and first "P" are superfluous. Further, ".P" is frequently typed, and per sound principles of Huffman coding, it should be short. Thus do I hope to buy the complaisance of grognards with the cheap bribe of "less typing", a preoccupation whose star has not dimmed among Unix geeks in 50 years. * tmac/an-old.tmac (P): Define this is as the "canonical" paragraphing macro. (LP, PP): Make these aliases of P. [3] You could also say the following. Integer overflow is guaranteed for large values of\~\c .IR n . But I discourage the use of \c except where necessary because it tends to confuse people (although in groff Git HEAD I've finally got this escape sequence described carefully enough that it no longer maddens me as it did when I first became a contributor[6]). In the above, if we omit the output line continuation escape sequence \c, then the line can break after "of" because that's what a newline in the *roff input stream _means_. [4] https://www.eliteediting.com.au/parentheses-within-parentheses/ [5] I do still want an "MR" man page cross referencing macro[7] (and mandoc(1) maintainer Ingo Schwarze is still trying to talk me out of it), but not so that "See also" can be autogenerated. [6] https://man7.org/linux/man-pages/man7/groff.7.html#Line_continuation [7] https://lists.gnu.org/archive/html/groff/2021-08/msg00000.html
Attachment:
signature.asc
Description: PGP signature