Follow-up Comment #1, bug #66103 (group groff): At 2024-08-18T13:53:13-0400, Helge Kreutzmann wrote: > Please note: I know you are not following traditional man rules any > more,
I dispute that. I think groff's man pages are as faithful to the format and conventions established in the Seventh Edition Unix Programmer's Manual as any other well-curated corpus of man pages. I am happy to discuss particulars with you. > so maybe some of the following issues are changes done on purpose, > Those where I do not see updates I will mark appropriately, so that > they are not reported in the future again. Understood. > Man page: groff.1 > Issue: I<roff> → B<roff>(7) Deliberate. As far as the font style is concerned, I have explored this matter at length. https://lists.gnu.org/archive/html/groff/2023-08/msg00005.html > "groff - front end to the GNU I<roff> document formatting system" > > "I<groff> is the primary front end to the GNU I<roff> document > formatting " "system." If the report is that "roff" and "groff" should be set in bold instead of italics, or in roman, I do not agree and that is not convention except in man pages authored with a poor grasp of tradition (or deliberate deviation). groff_man_style(7): Use italics for file and path names, for environment variables, for C data types, for enumeration or preprocessor constants in C, for variant (user‐ replaceable) portions of syntax synopses, for the first occurrence (only) of a technical concept being introduced, for names of journals and of literary works longer than an article, and anywhere a parameter requiring replacement by the user is encountered. An exception involves variant text in a context already typeset in italics, such as file or path names with replaceable components; in such cases, follow the convention of mathematical typography: set the file or path name in italics as usual but use roman for the variant part (see .IR and .RI below), and italics again in running roman text when referring to the variant material. > Man page: groff.1 > Issue: The variable strings here are different than in the description > below, e.g. ctext, fallback-encoding, i.e. > cs or ctest? > fallback-encoding or enc? > font-family or fam? > font-directory or dir? > inclusion-directory or dir? > input-encoding or enc? > spooler-argument or arg? > macro-package or name? > macro-directory or dir? > page-number or num? > page-list or list? > postprocessor-argument or arg? > output-device or dev? > warning-category or name? Yes. These are all deliberate. The idea is to have the synopsis synopsize, and to keep it in parallel with the command's usage message, which does describe each option in detail. You should perceive parity between Synopsis groff [-abcCeEgGijklNpRsStUVXzZ] [-d ctext] [-d string=text] [-D fallback‐encoding] [-f font‐family] [-F font‐directory] [-I inclusion‐directory] [-K input‐encoding] [-L spooler‐ argument] [-m macro‐package] [-M macro‐directory] [-n page‐ number] [-o page‐list] [-P postprocessor‐argument] [-r cnumeric‐expression] [-r register=numeric‐expression] [-T output‐device] [-w warning‐category] [-W warning‐ category] [file ...] groff -h groff --help groff -v [option ...] [file ...] groff --version [option ...] [file ...] and $ groff --help usage: groff [-abcCeEgGijklNpRsStUVXzZ] [-d ctext] [-d string=text] [-D fallback-encoding] [-f font-family] [-F font-directory] [-I inclusion-directory] [-K input-encoding] [-L spooler-argument] [-m macro-package] [-M macro-directory] [-n page-number] [-o page-list] [-P postprocessor-argument] [-r cnumeric-expression] [-r register=numeric-expression] [-T output-device] [-w warning-category] [-W warning-category] [file ...] usage: groff {-v | --version} usage: groff {-h | --help} ...for example. groff (GNU roff) is a typesetting system that reads plain text input files that include formatting commands to produce output in PostScript, PDF, HTML, or DVI formats or for display to a terminal. See the groff(1) manual page. By contrast, when we present command-line options in the "Options" section of a man page, there is no pressing need to have such lengthy, descriptive parameter names, because these names are explicated in the immediate context. This convention should be familiar from mathematical writing. -D enc Use enc as preconv(1)’s fallback input encoding; implies -k. ... -I dir Works as troff’s option (see below), but also implies -g and -s. groff passes -I options and their arguments to soelim(1), troff(1), and output drivers; with the option letter changed to -M, the same arguments are passed to grn(1). ... -K enc Set input encoding used by preconv(1) to enc; implies -k. ... -L arg Pass arg to the print spooler. If multiple args are required, pass each with a separate -L option. groff does not prefix an option dash to arg before passing it to the spooler. ... -P arg Pass arg to the postprocessor. If multiple args are required, pass each with a separate -P option. groff does not prefix an option dash to arg before passing it to the postprocessor. ... -T dev Prepare output for device dev. groff passes the -T option and its argument to troff, then (unless the -Z option is used) runs an output driver to convert troff’s output to a form appropriate for dev; see subsection “Output devices” below. As you can see, it also makes for tidier typesetting. I use long parameter names again where this page (unique in the groff corpus) explicitly demurs from explaining them. Transparent options The following options are passed as‐is to the formatter program troff(1) and described in more detail in its man page. ... -d ctext -d string=text Define string. ... -r cnumeric‐expression -r register=numeric‐expression Define register. > "The combination constitutes a document in one of a family of languages we " > "also call I<roff>; see E<.MR roff 7> for background." If "E" means "error", then it looks like your tools may want to adapt to a new feature of groff 1.23's man(7) macros. groff_man(7): .MR topic [manual‐section [trailing‐text]] (since groff 1.23) Set a man page cross reference as “topic(manual‐section)”. If manual‐section is absent, the package omits the surrounding parentheses. If trailing‐text (typically punctuation) is specified, it follows the closing parenthesis without intervening space. Hyphenation is disabled while the cross reference is set. topic is set in the font specified by the MF string. If manual‐section is present, the cross reference hyperlinks to a URI of the form “man:topic(manual‐section)”. ... James Clark implemented the foregoing features in early versions of groff. Later, groff 1.20 (2009) originated .SY/.YS, .TQ, .MT/.ME, and .UR/.UE. Plan 9 from User Space’s troff introduced .MR in 2020. > Man page: groff.1 > Issue: I<\\%grn> → MR \\%grn 1 \\%grn 1 > > "It is passed to E<.MR \\%soelim 1> and the output driver, and I<\\%grn> is " > "passed an B<-M> option with I<dir> as its argument." Fixed in groff Git since September 2023. groff(1): -I dir Works as troff’s option (see below), but also implies -g and -s. groff passes -I options and their arguments to soelim(1), troff(1), and output drivers; with the option letter changed to -M, the same arguments are passed to grn(1). > Man page: groff.1 > Issue 1: I<\\%pic> → .MR \\%pic 1 > Issue 2: I<\\%troff> → .MR \\%troff 1 > > "Operate in unsafe mode: pass the B<-U> option to I<\\%pic> and I<\\%troff>." Thanks for the report. > Man page: groff.1 > Issue: cnumeric-expression → numeric-expression > > "B<-r\\ >I<cnumeric-expression>" This is not a typo, but an explication of the syntax, which admits no separating space. groff(1) defers explanation of this option, like `-d` to troff(1). groff(1): Transparent options The following options are passed as‐is to the formatter program troff(1) and described in more detail in its man page. troff(1): -r cnumeric‐expression -r register=numeric‐expression Define roff register c or register as numeric‐expression. c must be a one‐character identifier; register can be of arbitrary length. Such assignments happen before any macro file is loaded, including the startup file. Due to getopt_long(3) limitations, c cannot be, and register cannot contain, an equals sign, even though that is a valid character in a roff identifier. > Man page: groff.1 > Issue 1: I<roff> → .MR roff 7 > Issue 2: I<troff> → .MR \\%troff 1 I do not slavishly mark _every_ occurrence of a potential man page cross reference as such. This can get noisy and repetitious. Observe the specification of the `MR` macro. groff_man(7): .MR topic [manual‐section [trailing‐text]] (since groff 1.23) Set a man page cross reference as “topic(manual‐section)”. If manual‐section is absent, the package omits the surrounding parentheses. If trailing‐text (typically punctuation) is specified, it follows the closing parenthesis without intervening space. Hyphenation is disabled while the cross reference is set. topic is set in the font specified by the MF string. If manual‐section is present, the cross reference hyperlinks to a URI of the form “man:topic(manual‐section)”. I _do_ think that a cross reference should be written out in full (which, in groff 1.23, will also hyperlink them on supporting devices) on a first occurrence in a page. > -- > Man page: groff.1 > Issue: I<sed> → .MR sed 1 > > "We used a I<sed> command only to eliminate the 65 blank lines that would " > "otherwise flood the terminal screen." > -- Thanks for the report. > Man page: groff.1 > Issue 1: I<nroff> → .MR nroff 1 > Issue 2: I<troff> → .Mr troff 1 > > "These have one- or two-letter names arising from intense practices of naming > " > "economy in early Unix culture, a laconic approach that led to many of the " > "packages being identified in general usage with the I<nroff> and I<troff> " > "option letter used to invoke them, sometimes to punning effect, as with " > "\\[lq]man\\[rq] (short for \\[lq]manual\\[rq]), and even with the option " > "dash, as in the case of the I<s> package, much better known as I<ms> or even > " > "I<-ms>." > > "It provides the features of the AT&T I<troff> and I<nroff> programs as well > " > "as many extensions." > -- As above, this is an avoidance of slavish repetition. > Man page: groff.1 > Issue: Use colon at end of line? > "An output device may be any of the following." > > "Once a E<.MR man 1> librarian program has located a man page, it may execute > " > "a I<groff> command much like the following." Negative. Use of a colon is poor grammar when the ensuing list fails to exhibit sentence-ending punctuation, as is often the case in man pages composed by inexpert (or indifferent) technical writers. I editorialized about this problem four years ago. commit 3afcaf0ed409093626c3a9fe346bd33afec60f29 Author: G. Branden Robinson <g.branden.robin...@gmail.com> Date: Sun Sep 6 04:54:06 2020 +1000 doc/groff.texi, groff_diff(7): Tweak example. It's like bathing a cat to get programmers to punctuate inset examples that are grammatically part of a sentence, as if they were part of a sentence. People love to just trail off with "the following:", blitz the user with 1-100 lines of block-quoted literal, and then pretend they ended a sentence. (This is suggestive of the console jockey ethos; once one has thrown code at you, they're done with you.) Mathematical literature is more careful. However, the man macros make doing the right thing difficult; in nroff mode there just aren't many font styles to go around, and while one could ".if t" around that problem, a miniature BSD daemon materializes on my shoulder and pokes me with a pitchfork if I even consider it. And doing so doesn't help the likely majority of people who _only_ read man pages in a terminal window. In the end the best solution is to just recast. Our man pages are already overrun with lazy "sentences" ending in "the following:" and similar constructions anyway, so it's no burden to scrub out one more. tl;dr: A colon does not relieve you of your duty to finish a sentence. > -- > Man page: groff.1 > Issue: ISO 646 1991:IRV → ISO/IEC 646:1991 (what des IRV stand for?) IRV stands for "International Reference Version". https://agimcami.wordpress.com/wp-content/uploads/2019/07/ascii-characters-set-aivosto-com.pdf > "for terminals using the ISO 646 1991:IRV character set and encoding, also " > "known as US-ASCII." > -- > Man page: groff.1 > Issue: ISO → ISO/IEC > "for terminals using the ISO Latin-1 (ISO 8859-1) character set and > encoding." > > "for terminals using the ISO 10646 (\\[lq]Unicode\\[rq]) character set in " > "UTF-8 encoding." > > "Conversely, the output device B<cp1047> is not available on systems based on > " > "the ISO\\ 646 or ISO\\ 8859 character encoding standards." > -- As I understand it, ISO and IEC are not merged organizations. It is appropriate to denote a standard document as "ISO/IEC" when it is actually issued under the joint aegis of the two bodies. When making such a rewrite recommendation, you should cite an authoritative reference indicating that the IEC has cosponsored the document in question. A blind sed(1) rewrite of "ISO" will not do. One would not say "ISO/IEC 9000 quality management". > Man page: groff.1 > Issue: I<\\%gxditview> → .MR \\%gxditview 1 > > "for previewing with I<\\%gxditview> using 75 dpi resolution and a 10-point " > "base type size." > > "for previewing with I<\\%gxditview> using 75 dpi resolution and a 12-point " > "base type size." > > "for previewing with I<\\%gxditview> using 100 dpi resolution and a 10-point > " > "base type size." > > "for previewing with I<\\%gxditview> using 100 dpi resolution and a 12-point > " > "base type size." > > "The B<-X> option overrides this selection, causing I<\\%gxditview> to serve > " > "as the output driver." Aleady cross referenced earlier in the page. -X Use gxditview(1) instead of the usual postprocessor to (pre)view a document on an X11 display. Combining this option with “-T ps” uses the font metrics of the PostScript device, whereas the “-T X75”, “-T X75-12” “-T X100”, and “-T X100-12” options use the metrics of X11 fonts. > -- > Man page: groff.1 > Issue: I<\\%afmtodit> → .MR \\%afmtodit 1 > > "translates a PostScript Type\\ 1 font in PFB (Printer Font Binary) format " > "to PFA (Printer Font ASCII), which can then be interpreted by > I<\\%afmtodit>." Already cross referenced in the immediately preceding paragraph. afmtodit(1) creates font description files for PostScript Type 1 fonts. > -- > Man page: groff.1 > Issue 1: I<troff> → .MR troff 1 > Issue 2: I<nroff> → .MR nroff 1 > Issue 3: I<\\%soelim> → .MR soelim 1 > Issue 4: I<\\%indxbib> → .MR indxbib 1 > Issue 5: I<\\%lookbib> → .MR lookbib 1 > > "Besides I<troff>, the prefix applies to the formatter I<nroff>; the " > "preprocessors I<eqn>, I<grn>, I<pic>, I<\\%refer>, I<tbl>, and I<\\%soelim>; > " > "and the utilities I<\\%indxbib> and I<\\%lookbib>." Similarly, the paragraph tags in subsection "Utilities" already cross reference the latter three of these, and the former two earlier still. > -- > Man page: groff.1 > Issue: I<preconv>(1) → .MR preconv 1 > > "The value of this variable is passed to the I<preconv>(1) preprocessor's > B<-" > "e> option to select the character encoding of input files." > > "If set but empty, I<groff> calls I<preconv> without an B<-e> option." > -- Cross-referenced earlier. -k Run preconv(1) preprocessor. Refer to its man page for its behavior if neither of groff’s -K or -D options is also specified. > Man page: soelim.1 > Issue: I<\\%soelim> → B<soelim> Conventions are split here. mandoc(1), and Thomas Dickey's man pages, tend to boldface a page's own topic name(s) at every occurrence. I think this is too busy. groff_man_style(7): Be frugal with italics for emphasis, and particularly with bold. Article titles and brief runs of literal text, such as references to individual characters or short strings, including section and subsection headings of man pages, are suitable objects for quotation; see the \(lq, \(rq, \(oq, and \(cq escape sequences in subsection “Portability” below. I am not alone; also see <https://uit.stanford.edu/accessibility/concepts/typography>. > -- > Man page: soelim.1 > Issue: I<roff> → .MR roff 7 > > "I<soelim> was designed to handle situations where the target of a I<roff> " > "source request requires a preprocessor such as E<.MR \\%eqn 1 ,> E<.MR \\" > "%pic 1 ,> E<.MR \\%refer 1 ,> or E<.MR \\%tbl 1 .>" Already cross referenced in the first sentence of the document. Description GNU soelim is a preprocessor for the groff(7) document formatting system. soelim works as a filter to eliminate source requests in roff(7) input; that is, it replaces lines of the form “.so included‐file” within each text input‐file with the contents of included‐file, recursively. > Man page: soelim.1 > Issue: I<\\%troff> → .MR troff 1 > > "That is, files sourced with \\[lq]B<so>\\[rq] are normally read I<only> by " > "the formatter, I<\\%troff>." Thanks for the report. > Man page: soelim.1 > Issue 1: I<\\%soelim> → B<\\%soelim> > Issue 2: I<\\%troff> → .MR \\%troff 1 > > "I<\\%soelim> is I<not> required for I<\\%troff> to source files." As this is the very next sentence, another cross reference here would be superfluous. Automated style checking is a valuable thing to have, but technical writing, if it is be of sufficient quality to engage a human reader productively, is not a robotic practice. I counsel against a lazy prescription that every single mention of a word that might be a man page cross reference should be marked up as such. _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?66103> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/
signature.asc
Description: PGP signature
