docutils/docs/user/manpage.txt TODO items

"G. Branden Robinson" <[email protected]> Wed, 4 Oct 2023 13:11:51 -0500
Newsgroups	gmane.text.docutils.devel
Message-ID	<20231004181151.nk33nevyyt47tjdk@illithid>
Hi folks,

In looking over the Python docutils repo I spotted this list of
questions/problems and thought I could help.

> TODO - Open issues
> ''''''''''''''''''
>
> How to escape double quotes in macro arguments ?

  Use the special character escape sequence ``\(dq``.
  groff_man_style(7) explains.

       \(dq   Basic Latin quotation mark (double quote).  Use in macro
              calls to prevent ‘"” from being interpreted as beginning a
              quoted argument, or simply for readability.

                     .TP
                     .BI "split \(dq" text \(dq

> How to typeset command/manpage names in text.

  There are conflicting traditions and conventions on these points.
  groff_man_style(7) has recommendations.

              Use bold for literal portions of syntax synopses, for
              command‐line options in running text, and for literals
              that are major topics of the subject under discussion; for
              example, this page uses bold for macro, string, and
              register names.  In an .EX/.EE example of interactive I/O
              (such as a shell session), set only user input in bold.

              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.

  Plan 9 from User Space troff and groff 1.23.0 support an ``MR`` macro
  for the specific purpose of setting man page cross references.  It is
  reasonable to assume that groff 1.23.0 has not propagated yet to every
  platform Python docutils would like to support yet.  You can wait
  until it has, or supply a fallback definition in the man(7) documents
  you generate.

``.\" Define fallback for groff 1.23's MR macro if the system lacks it.
  .nr df 0 \" do fallback?
  .if !\n(.f           .nr df 1 \" mandoc
  .if  \n(.g .if !d MR .nr df 1 \" older groff
  .if !\n(.g           .nr df 1 \" non-groff *roff
  .if \n(df \{\
  .de MR
  .ie \\n(.$=1 \
  .I \%\\$1
  .el \
  .IR \%\\$1 (\\$2)\\$3
  ..
  .\}
  .rr df``

> How to write long syntax lines.

  groff_man_style(7) explains.

       \newline
              Join the next input line to the current one.  Except for
              the update of the input line counter (used for diagnostic
              messages and related purposes), a series of lines ending
              in backslash‐newline appears to groff as a single input
              line.  Use this escape sequence to split excessively long
              input lines for document maintenance.

> Line ends around email or web addresses in texts.
> How to distinguish something is inline or not ?

  groff_man_style(7) explains.

       \c     End a text line without inserting space or attempting a
              break.  Normally, if filling is enabled, the end of a text
              line is treated like a space; an output line may be broken
              there (if not, an adjustable space is inserted); if
              filling is disabled, the line will be broken there, as in
              .EX/.EE examples.  The next line is interpreted as usual
              and can include a macro call (contrast with \newline).  \c
              is useful when three font styles are needed in a single
              word, as in a command synopsis.

                     .RB [ \-\-stylesheet=\c
                     .IR name ]

              It also helps when changing font styles in .EX/.EE
              examples, since they are not filled.

                     .EX
                     $ \c
                     .B groff \-T utf8 \-Z \c
                     .I file \c
                     .B | grotty \-i
                     .EE

  Here's an example using groff's ``MR`` and ``ME`` macros.

``Mail the maintainer (\c
  .MR [email protected]
  Arthur Pewtey
  .UE )
  to submit patches.``

> Images and equations are discouraged.

  Unfortunately, yes.

> Lists in admonitions are not intended.

  This one I can't answer; I'll have to read more about Python docutils
  to understand the semantics and scope of admonitions.

> Encoding declaration ``'\" t -*- coding: ISO-8859-1 -*-``
> in first line.

  I would put Emacs file-local variables at the *end* of a man(7)
  document, not the beginning, but I admit I don't know of a mandb(8) or
  makewhatis(8) program in deployment on systems that Python docutils
  cares about that actually screws this up.

  Also, the ``t`` part of that is a hint to man(1) that it should run
  the tbl(1) preprocessor.  If you don't generate a tbl(1) table, you
  don't need the ``t`` in your first line.

> BUT if UTF-8 is declared tables are no longer processed.

  That's very strange.  If you can still reproduce this I'd appreciate a
  bug report.

> Input and output encoding are problematic at least.

  They shouldn't be with use of man-db man(1).  If you use groff
  directly, two factors are important.

  1.  Pass groff the ``-k`` option to tell it to run preconv(1) to
      attempt detection and translation of the character encoding used
      by the document.

  2.  Make sure you use an output device appropriate to the terminal's
      encoding.  You can run nroff(1) instead of groff(1) directly to
      have the system try to figure it out, or you can explicitly
      specify a ``-T`` option (to either nroff or groff).  groff
      supports the following.

      ``-T ascii``
      ``-T cp1047``
      ``-T latin1``
      ``-T utf8``

Let me know if any of the above is unclear or if I can be of further
assistance.

Regards,
Branden
signature.asc (application/pgp-signature, 833 B)