Hi Branden, G. Branden Robinson wrote on Wed, Nov 14, 2018 at 03:26:14PM -0500: > At 2018-11-14T08:12:35+0100, Ingo Schwarze wrote: >> G. Branden Robinson wrote on Tue, Nov 13, 2018 at 09:59:20PM -0500:
>>> commit b447d738fb65168ef8ccda2a89555425ebe6aa4a >>> Author: G. Branden Robinson <g.branden.robin...@gmail.com> >>> Date: Tue Nov 13 11:36:13 2018 -0500 >> [...] >>> + Set "@g@nroff", "groff", "grotty", and "locale"(1) in >>> italics, not bold or roman. >> [...] >> > -.B @g@nroff >> > +.I @g@nroff >> >> I think these particular B -> I changes are wrong and ought to be >> reverted. >> >> The fundamental rule for syntax elements (somewhat simplified) is >> that bold is for syntax elements that have to be typed verbatim >> (like command line options, keywords, type specifiers, function >> names, ...) and italics/underlined is for placeholders for syntax >> elements that the user has to replace by something else (like >> function argument placeholders, command line argument placeholders, >> ...). > In a synopsis, yes. Assigning conflicting meanings to the same markup in the same manual page sounds like a really bad idea. >> In any case, command names are among the most typical cases >> of syntax elements absolutely requiring bold face. > This is widely overstated. >> That is not only very firmly established in manual pages > Incorrect. I direct your attention to: > * the more than 800 man pages in the X Window System The X manual pages are low quality in many respects, so using them as an example is quite meaningsless. Besides, they are inconsistent in this very respect: Xephyr(1) Xmark(1) Xnest(1) Xorg(1) bdftruncate(1) cwm(1) cxpm(1) fc-cache(1) gccmakedep(1) glxinfo(1) luit(1) makedepend(1) setxkbmap(1) ssh-askpass(1) startx(1) xcompmgr(1) xgamma(1) xidle(1) xinit(1) xlock(1) xtsscale(1) xvinfo(1) are some examples of pages that do correctly mark up commands in bold. > * the ~307 pages in Seventh Edition Unix distribution; and You have a point here; v7 did not know that convention yet, they indeed used conflicting markup in the SYNOPSIS and DESCRIPTION. > * the over 1100 pages in 4.3BSD. Yes, because up to about Reno, BSD manuals were more or less an extension of the AT&T manuals. However, the consistent scheme i described was established between 4.3 and 4.4 and has been used ever since - i.e. for the last 28 years, see e.g. https://man.openbsd.org/?query=Nd~.&apropos=1&sec=1&manpath=4.4BSD-Lite2 > The above corpora are in fact remarkably consistent about rendering the > topic of the page in italics, more so in fact than they are about > rendering placeholders in italics in the Synopsis section. > > If access to any of these is inconvenient for you, I'm happy to share > them. No, i have all of them readily installed, but thanks. >> but a widespread convention in printed books about programming as >> well. > That's a big field but I checked my copies of several classics from > heavyweights and here's what I found: > > * K&R, _The C Programming Language_, 1st Ed., 1978, uses > Courier, not bold, for function and command names. > * Kernighan & Plauger, _Software Tools, 1976, uses Helvetica, > not bold, for function and command names. > * Kernighan & Pike, _The UNIX[sic] Programming Environment_, > 1984, uses Courier, not bold, for function and command names. > It is the first of these books to use italics for much outside > of the C Reference Manual appendices of K&R 1 and 2. > * K&R, _The C Programming Language_, 2nd Ed., 1988, same as 1st. > * W. Richard Stevens, _Advanced Programming in the UNIX® > Environment_, 1st Ed., 1993, uses Courier, not bold, for > function and command names and literals in general. > > What respected source in the printed domain did you have in mind? I > admit that Brian Kernighan casts a long shadow over my selections. Hmm - i have to admit printed books are less consistent than is seemed to remember. There are some examples, e.g. Stevens, TCP/IP Illustrated uses bold face, Stroustrup, C++ uses a bold italic font - but you are right, books differ, so they provide less guidance than i thought. >> Even Michael Kerrisk agrees with that: >> https://man.openbsd.org/?query=Nd~.&apropos=1&sec=1&manpath=Linux-4.13 > Yes, and it's a point upon which I disagree. I agree that some of the recommendations in man-pages(7) are not good; but when recommendations from the BSD and Linux man pages worlds agree, we should probably not diverge. > Doing so puts too much > bold on the screen (or printed page) for visual comfort. Beauty sometimes is a valid argument when choosing markup - but it doesn't beat consistency and clarity. > (You may > appreciate this as a point against GNU long option practices.) Within a > synopsis, option tags, and perhaps some examples, it is valuable > nevertheless. > > But in running prose, it's too much loudness Actually, command names occur only occasionally in running text, typically significantly less than once per paragraph, on average. So even if you would prioritize beauty over consistency, that argument is weak. > and not necessary for clarity. > If you disagree, you must explain how people managed to learn > anything from the man pages of 7th Edition Unix or 4.3BSD. That's a straw man - you can understand a well-written manual page without any markup whatsoever. Consistent markup is merely one tool to make it easier. And yes, the Bell Labs manuals were very consistent, up to the point of consistently sticking to this inconsistency between SYNOPSIS and DESCRIPTION. >> Much less important: manual page cross references do not require >> any font changes at all. All parts of them can be set in the default >> roman font because the section number in parentheses already makes >> the word stand out. > Your memory did not fail you here--in 7th Ed. and 4.3BSD, man page cross > references, at least in See Also sections, were typically not marked up > at all. Yes, and also from 4.4BSD onwards ever since (speaking of physical markup, that is, of course they do carry semantic markup). > Nevertheless it is my preference to italicize the names of man page > topics because (1) they generally refer to works of software (if not > commercial products) in some sense, (2) I prefer to use _some_ kind > of markup on them because it gets the spell checker out of the writer's > way (they can either ignore the squiggles or highlights, or use that as > a reminder to add the term to their local dictionary), (3) it flags > the terms for potential "lifting" to semantic markup, that ever-receding > future goal, Whatever - i dislike font changes for cross references for the stated reasons, but it's not so important because even with markup, the section number in parentheses makes it quite clear what it is. > (4) the X11 corpus follows the practice. Again, please don't use X as an example. Besides, SEE ALSO appears to be vastly inconsitsent there. My impression is that a bit more than half of the pages use roman(roman), a bit less than half bold(roman), but italic(roman) seems rather rare. >> Some use boldface for such cross references >> anyway, which looks unnecessarily heavy to me, but which i don't >> care that strongly about. As opposed to abusing italics, at least >> that is not misleading. > I agree that boldface can be unnecessarily heavy, which is why I think > it wise to reduce gratuitous use of it. My above remark was specifically directed at cross references - because in contrast to command names, cross refences do tend to occur in clusters, and *then* it looks heavy. That was an argument for roman, not italic. > Italics are not semantic markup. They do not mean "replaceable text" > everywhere you see them. For syntax elements, when used well, they almost do; certainly in modern BSD manuals (that is, those aged 25 years or less). > Having consulted all the above, I'm in fact _more_ persuaded that I'm > on the right path. Hmpf. We two seem to have some talent to disagree on relatively simple, elementary questions. Yours, Ingo
