[bug #66103] Issues in man pages

[Helge Kreutzmann]

URL:
  <https://savannah.gnu.org/bugs/?66103>

                 Summary: Issues in man pages
                   Group: GNU roff
               Submitter: kreutzm
               Submitted: Sun 18 Aug 2024 05:53:10 PM UTC
                Category: None
                Severity: 3 - Normal
              Item Group: None
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any


    _______________________________________________________

Follow-up Comments:


-------------------------------------------------------
Date: Sun 18 Aug 2024 05:53:10 PM UTC By: Helge Kreutzmann <kreutzm>
Dear groff maintainer,
the manpage-l10n project maintains a large number of translations of
man pages both from a large variety of sources (including groff) as
well for a large variety of target languages.

During their work translators notice different possible issues in the
original (english) man pages. Sometimes this is a straightforward
typo, sometimes a hard to read sentence, sometimes this is a
convention not held up and sometimes we simply do not understand the
original.

We use several distributions as sources and update regularly (at
least every 2 month). This means we are fairly recent (some
distributions like archlinux also update frequently) but might miss
the latest upstream version once in a while, so the error might be
already fixed. We apologize and ask you to close the issue immediately
if this should be the case, but given the huge volume of projects and
the very limited number of volunteers we are not able to double check
each and every issue.

Secondly we translators see the manpages in the neutral po format,
i.e. converted and harmonized, but not the original source (be it man,
groff, xml or other). So we cannot provide a true patch (where
possible), but only an approximation which you need to convert into
your source format.

Finally the issues I'm reporting have accumulated over time and are
not always discovered by me, so sometimes my description of the
problem my be a bit limited - do not hesitate to ask so we can clarify
them.

I'm now reporting the errors for your project. If future reports
should use another channel, please let me know.

Please note: I know you are not following traditional man rules any 
more, 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.

Man page: groff.1
Issue:    I<roff> → B<roff>(7)

"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."
--
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?

"[B<-abcCeEgGijklNpRsStUVXzZ>] [B<-d\\ >I<ctext>] [B<-d\\ "
">I<string>B<=>I<text>] [B<-D\\ >I<fallback-encoding>] [B<-f\\ >I<font-"
"family>] [B<-F\\ >I<font-directory>] [B<-I\\ >I<inclusion-directory>] [B<-"
"K\\ >I<input-encoding>] [B<-L\\ >I<spooler-argument>] [B<-m\\ >I<macro-"
"package>] [B<-M\\ >I<macro-directory>] [B<-n\\ >I<page-number>] [B<-o\\ "
">I<page-list>] [B<-P\\ >I<postprocessor-argument>] [B<-r\\ >I<cnumeric-"
"expression>] [B<-r\\ >I<register>B<=>I<numeric-expression>] [B<-T\\ "
">I<output-device>] [B<-w\\ >I<warning-category>] [B<-W\\ >I<warning-"
"category>] [I<file\\ >.\\|.\\|.]"
--
Man page: groff.1
Issue:    I<roff> → .MR roff 7

"GNU I<roff> is a typesetting system that reads plain text input files that "
"include formatting commands to produce output in PostScript, PDF, HTML, DVI,
"
"or other formats, or for display to a terminal."

"The front end programs available in the GNU I<roff> system make it easier to
"
"use than traditional I<roff>s that required the construction of pipelines or
"
"use of temporary files to carry a source document from maintainable form to
"
"device-ready output."

"The discussion below summarizes the constituent parts of the GNU I<roff> "
"system."

"(I<roff> systems were developed in the days of paper-based terminals with 66
"
"lines to a page.)"

"Input to a I<roff> system is in plain text interleaved with control lines "
"and escape sequences."

"The combination constitutes a document in one of a family of languages we "
"also call I<roff>; see E<.MR roff 7> for background."

"An overview of GNU I<roff> language syntax and features, including lists of
"
"all supported escape sequences, requests, and predefined registers, can be "
"found in E<.MR groff 7 .>"

"A preprocessor interprets a domain-specific language that produces I<roff> "
"language output."

"Frequently, such input is confined to sections or regions of a I<roff> input
"
"file (bracketed with macro calls specific to each preprocessor), which it "
"replaces."

"Preprocessors therefore often interpret a subset of I<roff> syntax along "
"with their own language."

"Macro files are I<roff> input files designed to produce no output themselves
"
"but instead ease the preparation of other I<roff> documents."

"Macro packages can be loaded prior to any I<roff> input documents with the "
"B<-m>\\ option."

"(invariably called \\[lq]mom\\[rq])  is a modern package written by Peter "
"Schaffter specifically for GNU I<roff>."

"I<\\%andoc> is a wrapper package specific to GNU I<roff> that recognizes "
"whether a document uses I<man> or I<mdoc> format and loads the corresponding
"
"macro package."

"Many macro files augment the function of the full-service packages, or of "
"I<roff> documents that do not employ such a package\\[em]the latter are "
"sometimes characterized as \\[lq]raw\\[rq]."

"The formatter, the program that interprets I<roff> language input, is E<.MR
"
"\\%troff 1 .>"

"The postprocessors provided by GNU I<roff> are I<output drivers>, which "
"prepare a document for viewing or printing."

"GNU I<roff> includes a suite of utilities."

"marks differences between a pair of I<roff> input files."

"A trio of tools transform material constructed using I<roff> preprocessor "
"languages into graphical image files."

"If it is not set, the installation directory of the GNU I<roff> executables,
"
"I</usr/\\:\\%bin>, is searched before I<PATH>."

"I<roff> systems are best known for formatting man pages."

"To process a I<roff> input file using the preprocessors I<\\%tbl> and I<\\"
"%pic> and the I<me> macro package in the way to which AT&T I<troff> users "
"were accustomed, one would type (or script)  a pipeline."

"Most macro files supplied with GNU I<roff> are stored in
I</usr/\\:\\%share/"
"\\:\\%groff/\\:\\%1.23.0/\\:\\%tmac> for the installation corresponding to "
"this document."

"For a catalog of macro files GNU I<roff> provides, see E<.MR groff_tmac 5
.>"

"Device and font description files supplied with GNU I<roff> are stored in
I</"
"usr/\\:\\%share/\\:\\%groff/\\:\\%1.23.0/\\:\\%font> for the installation "
"corresponding to this document."
--
Man page: groff.1
Issue:    I<groff> → B<groff>

"If no I<file> operands are specified, or if I<file> is \\[lq]B<->\\[rq], "
"I<groff> reads the standard input stream."

"A reimplementation and extension of the typesetter from AT&T Unix, I<groff>
"
"is present on most POSIX systems owing to its long association with Unix "
"manuals (including man pages)."

"I<groff> is capable of producing typographically sophisticated documents "
"while consuming minimal system resources."

"The I<groff> command orchestrates the execution of preprocessors, the "
"transformation of input documents into a device-independent page description
"
"language, and the production of output from that language."

"Because I<groff> is intended to subsume most users' direct invocations of "
"the E<.MR \\%troff 1> formatter, the two programs share a set of options."

"Refer to its man page for its behavior if neither of I<groff>'s B<-K> or
B<-"
"D> options is also specified."

"I<groff> does not prefix an option dash to I<arg> before passing it to the "
"spooler program."

"Write version information for I<groff> and all programs run by it to the "
"standard output stream; that is, the given command line is processed in the
"
"usual way, passing B<-v> to the formatter and any pre- or postprocessors "
"invoked."

"Output the pipeline that I<groff> would run to the standard output stream, "
"but do not execute it."

"Those with a programmer's bent may be pleased to know that they can use "
"I<groff> in a read-evaluate-print loop (REPL)."

"I<groff> uses the command-line option B<-P> to pass options to output "
"devices; for example, use the following for PostScript output on A4 paper in
"
"landscape orientation."

"Use the E<.MR grog 1> program to infer an appropriate I<groff> command line
"
"to format a document."

"infers the I<groff> command a document requires."

"Using I<groff>, this pipe can be shortened to an equivalent command."
--
Man page: groff.1
Issue 1:  I<groff> → B<groff>
Issue 2:  I<\\%troff> → .MR troff 1

"However, I<groff> has some options that I<\\%troff> does not share, and "
"others which I<groff> interprets differently."

"The following options either do not exist in GNU I<troff> or are interpreted
"
"differently by I<groff>."

"I<groff> then calls an output driver to convert I<\\%troff>'s output to a "
"form appropriate for I<dev>; see subsection \\[lq]Output devices\\[rq]
below."
--
Man page: groff.1
Issue:    I<\\%troff> → .MR troff 1

"At the same time, not all valid I<\\%troff> options can be given to
I<groff>."

"Works as I<\\%troff>'s option (see below), but is also passed to E<.MR \\"
"%eqn 1 ,> E<.MR grap 1 ,> and E<.MR \\%grn 1 .>"

"Direct I<\\%troff> to format the input for the output device I<dev>."

"I<\\%troff> output will appear on the standard output stream (unless "
"suppressed with B<-z>); see E<.MR groff_out 5> for a description of this "
"format."

"Enable AT&T I<troff> compatibility mode; implies B<-c>."

"Inhibit I<\\%troff> error messages; implies B<-Ww>."

"Suppress formatted device-independent output of I<\\%troff>."

"The I<papersize> macro package, automatically loaded by I<\\%troff>, "
"provides an interface for configuring page dimensions by convenient names, "
"like \\[lq]letter\\[rq] or \\[lq]A4\\[rq]; see E<.MR groff_tmac 5 .>"

"Tokens are generally preserved in preprocessor output and interpreted as "
"macro calls subsequently by I<\\%troff>."

"GNU I<troff> generates output in a device-independent, but not device-"
"agnostic, page description language detailed in E<.MR groff_out 5 .>"

"I<\\%troff> output is formatted for a particular I<output device>, typically
"
"specified by the B<-T> option to the formatter or a front end."

"Any program that interprets the output of GNU I<troff> is a postprocessor."

"adds information to AT&T I<troff> font description files to enable their use
"
"with GNU I<troff>."

"For example, GNU I<troff> would be installed as I<gtroff>."

"Viewer for\\ I<groff>\\ (and AT&T device-independent\\ I<troff>)\\
documents:"
--
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."
--
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>."
--
Man page: groff.1
Issue:    cnumeric-expression → numeric-expression

"B<-r\\ >I<cnumeric-expression>"
--
Man page: groff.1
Issue 1:  I<roff> → .MR roff 7
Issue 2:  I<troff> → .MR \\%troff 1

"The architecture of the GNU I<roff> system follows that of other device-"
"independent I<roff> implementations, comprising preprocessors, macro "
"packages, output drivers (or \\[lq]postprocessors\\[rq]), a suite of "
"utilities, and the formatter I<\\%troff> at its heart."

"In GNU I<roff>, the page dimensions for the formatter I<\\%troff> and for "
"output devices are handled separately."

"GNU I<roff> extensions to the AT&T I<troff> language, a common subset of "
"I<roff> dialects extant today, are detailed in E<.MR groff_diff 7 .>"

"GNU I<roff> provides reimplementations of most preprocessors familiar to "
"users of AT&T I<troff>; these routinely have extended features and/or "
"require GNU I<troff> to format their output."

"A preprocessor unique to GNU I<roff> is E<.MR preconv 1 ,> which converts "
"various input encodings to something GNU I<troff> can understand."

"The GNU I<roff> system implements most well-known macro packages for AT&T "
"I<troff> in a compatible way and extends them."

"The command-line option B<-C> switches I<\\%troff> into I<compatibility "
"mode>, which tries to emulate AT&T I<troff> as closely as is practical to "
"enable the formatting of documents written for the older system."

"GNU I<roff> can be configured at compile time to apply a prefix to the names
"
"of the programs it provides that had a counterpart in AT&T I<troff>, so that
"
"name collisions are avoided at run time."
--
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."
--
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."
--
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."
--
Man page: groff.1
Issue:    ISO 646 1991:IRV  → ISO/IEC 646:1991  (what des IRV stand for?)

"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."
--
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."
--
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>."
--
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>."
--
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."
--
Man page: soelim.1
Issue:    I<\\%soelim> → B<soelim>

"In the absence of I<input-file> arguments, I<\\%soelim> reads the standard "
"input stream."

"Any other escape sequence in I<macro-file>, including \\[lq]B<\\[rs]"
"[rs]>\\[rq], prevents I<\\%soelim> from replacing the source request."

"The dot must be at the beginning of a line and must be followed by "
"\\[lq]B<so>\\[rq] without intervening spaces or tabs for I<\\%soelim> to "
"handle it."

"This convention allows source requests to be \\[lq]protected\\[rq] from "
"processing by I<\\%soelim>, for instance as part of macro definitions or "
"\\[lq]B<if>\\[rq] requests."
--
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 .>"
--
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>."
--
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."








    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?66103>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

signature.asc
Description: PGP signature