sandbox/manpage-writer/TODO.txt

   1 TODOs
   2 =====
   3
   4 :Date: $Date$
   5
   6 * input/optionstoo.txt:23: (ERROR/3) Unexpected indentation.
   7   is what it is ... leave it so.
   8
   9   TODO the curly brace on start of line hides the line
  10
  11 * doublespace after end of sentence in manpages ?
  12
  13   see https://sourceforge.net/p/docutils/bugs/427/
  14
  15   Chicago manual of style ... hard to automate.
  16
  17 Check ``docs/user/manpage.txt``
  18
  19 * escape double quotes in macro arguments ?
  20
  21   Use the special character escape sequence ``\(dq``.
  22   groff_man_style(7) explains.
  23
  24        \(dq   Basic Latin quotation mark (double quote).  Use in macro
  25               calls to prevent ‘"” from being interpreted as beginning a
  26               quoted argument, or simply for readability.
  27
  28                      .TP
  29                      .BI "split \(dq" text \(dq
  30
  31 * How to typeset command/manpage names in text.
  32
  33   There are conflicting traditions and conventions on these points.
  34   groff_man_style(7) has recommendations.
  35
  36               Use bold for literal portions of syntax synopses, for
  37               command‐line options in running text, and for literals
  38               that are major topics of the subject under discussion; for
  39               example, this page uses bold for macro, string, and
  40               register names.  In an .EX/.EE example of interactive I/O
  41               (such as a shell session), set only user input in bold.
  42
  43               Use italics for file and path names, for environment
  44               variables, for C data types, for enumeration or
  45               preprocessor constants in C, for variant (user‐
  46               replaceable) portions of syntax synopses, for the first
  47               occurrence (only) of a technical concept being introduced,
  48               for names of journals and of literary works longer than an
  49               article, and anywhere a parameter requiring replacement by
  50               the user is encountered.  An exception involves variant
  51               text in a context already typeset in italics, such as file
  52               or path names with replaceable components; in such cases,
  53               follow the convention of mathematical typography: set the
  54               file or path name in italics as usual but use roman for
  55               the variant part (see .IR and .RI below), and italics
  56               again in running roman text when referring to the variant
  57               material.
  58
  59   Plan 9 from User Space troff and groff 1.23.0 support an ``MR`` macro
  60   for the specific purpose of setting man page cross references.  It is
  61   reasonable to assume that groff 1.23.0 has not propagated yet to every
  62   platform Python docutils would like to support yet.  You can wait
  63   until it has, or supply a fallback definition in the man(7) documents
  64   you generate. ::
  65
  66    .\" Define fallback for groff 1.23's MR macro if the system lacks it.
  67    .nr df 0 \" do fallback?
  68    .if !\n(.f           .nr df 1 \" mandoc
  69    .if  \n(.g .if !d MR .nr df 1 \" older groff
  70    .if !\n(.g           .nr df 1 \" non-groff *roff
  71    .if \n(df \{\
  72    .de MR
  73    .ie \\n(.$=1 \
  74    .I \%\\$1
  75    .el \
  76    .IR \%\\$1 (\\$2)\\$3
  77    ..
  78    .\}
  79    .rr df
  80
  81 * How to write long syntax lines.
  82
  83   groff_man_style(7) explains.::
  84
  85        \newline
  86               Join the next input line to the current one.  Except for
  87               the update of the input line counter (used for diagnostic
  88               messages and related purposes), a series of lines ending
  89               in backslash‐newline appears to groff as a single input
  90               line.  Use this escape sequence to split excessively long
  91               input lines for document maintenance.
  92
  93 * Line ends around email or web addresses in texts.
  94
  95 groff_man_style(7) explains.
  96
  97        \c     End a text line without inserting space or attempting a
  98               break.  Normally, if filling is enabled, the end of a text
  99               line is treated like a space; an output line may be broken
 100               there (if not, an adjustable space is inserted); if
 101               filling is disabled, the line will be broken there, as in
 102               .EX/.EE examples.  The next line is interpreted as usual
 103               and can include a macro call (contrast with \newline).  \c
 104               is useful when three font styles are needed in a single
 105               word, as in a command synopsis.
 106
 107                      .RB [ \-\-stylesheet=\c
 108                      .IR name ]
 109
 110               It also helps when changing font styles in .EX/.EE
 111               examples, since they are not filled.
 112
 113                      .EX
 114                      $ \c
 115                      .B groff \-T utf8 \-Z \c
 116                      .I file \c
 117                      .B | grotty \-i
 118                      .EE
 119
 120   Here's an example using groff's ``MT`` and ``ME`` macros.::
 121
 122    Mail the maintainer (\c
 123    .MT maint@example.com
 124    Arthur Pewtey
 125    .ME )
 126    to submit patches.
 127
 128   How to distinguish something is inline or not in the writer
 129   so to maybe put long urls after the current paragraph ?
 130
 131
 132 * lines starting with a ``{not typeset}  abc``
 133