sandbox/manpage-writer/TODO.txt

   1 TODOs
   2 =====
   3
   4 :Date: $Date$
   5
   6 * lines starting with a ``{not typeset}  abc``
   7
   8 # #480 document information comment with docutils version
   9
  10 * #481 no uppercasing of titles (config option)
  11
  12 * #482 no default formatting ... use macros or leave to writer
  13
  14 * How to typeset command/manpage names in text.
  15
  16   There are conflicting traditions and conventions on these points.
  17   groff_man_style(7) has recommendations.
  18
  19               Use bold for literal portions of syntax synopses, for
  20               command‐line options in running text, and for literals
  21               that are major topics of the subject under discussion; for
  22               example, this page uses bold for macro, string, and
  23               register names.  In an .EX/.EE example of interactive I/O
  24               (such as a shell session), set only user input in bold.
  25
  26               Use italics for file and path names, for environment
  27               variables, for C data types, for enumeration or
  28               preprocessor constants in C, for variant (user‐
  29               replaceable) portions of syntax synopses, for the first
  30               occurrence (only) of a technical concept being introduced,
  31               for names of journals and of literary works longer than an
  32               article, and anywhere a parameter requiring replacement by
  33               the user is encountered.  An exception involves variant
  34               text in a context already typeset in italics, such as file
  35               or path names with replaceable components; in such cases,
  36               follow the convention of mathematical typography: set the
  37               file or path name in italics as usual but use roman for
  38               the variant part (see .IR and .RI below), and italics
  39               again in running roman text when referring to the variant
  40               material.
  41
  42   Plan 9 from User Space troff and groff 1.23.0 support an ``MR`` macro
  43   for the specific purpose of setting man page cross references.  It is
  44   reasonable to assume that groff 1.23.0 has not propagated yet to every
  45   platform Python docutils would like to support yet.  You can wait
  46   until it has, or supply a fallback definition in the man(7) documents
  47   you generate. ::
  48
  49    .\" Define fallback for groff 1.23's MR macro if the system lacks it.
  50    .nr df 0 \" do fallback?
  51    .if !\n(.f           .nr df 1 \" mandoc
  52    .if  \n(.g .if !d MR .nr df 1 \" older groff
  53    .if !\n(.g           .nr df 1 \" non-groff *roff
  54    .if \n(df \{\
  55    .de MR
  56    .ie \\n(.$=1 \
  57    .I \%\\$1
  58    .el \
  59    .IR \%\\$1 (\\$2)\\$3
  60    ..
  61    .\}
  62    .rr df
  63
  64 see groff_man_style ::
  65
  66   .SH "See also"
  67   .
  68   .MR \%tbl 1 ,
  69   .MR \%eqn 1 ,
  70   and
  71   .MR \%refer 1
  72   are preprocessors used with man pages.
  73   .
  74   .MR man 1
  75   describes the man page librarian on your system.
  76
  77 but the rST source would be more like this ::
  78
  79   See also
  80   ========
  81
  82   tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.
  83   man(1) describes the man page ...
  84
  85 so the MR things need to be found with regexp or marked with a role/directive ?
  86
  87
  88 groff_man_style on
  89
  90    Hyperlink macros
  91        Man  page  cross references like ls(1) are best presented with .MR.  Text may be
  92        hyperlinked to email addresses with .MT/.ME or other URIs with .UR/.UE.   Hyper‐
  93        linked  text  is  supported  on  HTML and terminal output devices; terminals and
  94        pager programs must support ECMA-48 OSC  8  escape  sequences  (see  grotty(1)).
  95        When  device support is unavailable or disabled with the U register (see section
  96        “Options” below), .MT and .UR URIs are rendered between angle brackets after the
  97        linked text.
  98
  99        .MT, .ME, .UR, and .UE are GNU extensions not defined on systems  running  AT&T,
 100        Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below.  Plan 9 from
 101        User Space's troff implements .MR.
 102
 103        The arguments to .MR, .MT, and .UR should be prepared for typesetting since they
 104        can appear in the output.  Use special character escape sequences to encode Uni‐
 105        code  basic  Latin  characters  where  necessary, particularly the hyphen-minus.
 106        (See section “Portability” below.)  URIs can be lengthy; rendering them can  re‐
 107        sult  in jarring adjustment or variations in line length, or troff warnings when
 108        a hyperlink is longer than an output  line.   The  application  of  non-printing
 109        break point escape sequences \: after each slash (or series thereof), and before
 110        each  dot  (or  series  thereof)  is recommended as a rule of thumb.  The former
 111        practice avoids forcing a trailing slash in a URI onto a separate  output  line,
 112        and  the  latter  helps the reader to avoid mistakenly interpreting a dot at the
 113        end of a line as a period (or multiple dots as an ellipsis).  Thus,
 114               .UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
 115        has several potential break points in the  URI  shown.   Consider  adding  break
 116        points  before  or after at signs in email addresses, and question marks, amper‐
 117        sands, and number signs in HTTP(S) URIs.  The formatter removes  \:  escape  se‐
 118        quences  from  hyperlinks  when supplying device control commands to output dri‐
 119        vers.
 120
 121
 122 Used macros ... to be completed
 123 -------------------------------
 124
 125        .TP [indentation]
 126               Set  a  paragraph  with a leading tag, and the remainder of the paragraph
 127               indented.  A one-line input trap is planted; text on the next line, which
 128               can be formatted with a macro, becomes the tag, which is  placed  at  the
 129               current  left  margin.   The  tag  can be extended with the \c escape se‐
 130               quence.  Subsequent text is indented by indentation, if specified, and by
 131               the amount of the IN register otherwise.  If the tag is not  as  wide  as
 132               the indentation, the paragraph starts on the same line as the tag, at the
 133               applicable indentation, and continues on the following lines.  Otherwise,
 134               the  descriptive  part  of the paragraph begins on the line following the
 135               tag.
 136
 137        .TQ    Set an additional tag for a paragraph tagged with .TP.  An input trap  is
 138               planted as with .TP.
 139
 140               This  macro  is  a  GNU  extension  not  defined on systems running AT&T,
 141               Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below.
 142
 143
 144
 145 Notes
 146 -----
 147
 148 * Images and equations are discouraged.
 149
 150 * Lists in admonitions are not intended.
 151
 152 Discussions
 153 -----------
 154
 155 * Encoding declaration ``'\" t -*- coding: ISO-8859-1 -*-``
 156   in first line.
 157
 158   The part after ``t`` is a GNU Emacs convention.  A *groff* program
 159   called *preconv*\(1) understands it, but GNU *troff*\(1) itself does
 160   not.
 161
 162   The ``t`` is part of a *man*\(1) convention; GNU *troff*\(1) doesn't
 163   understand it, either (but since *tbl*\(1) is a *roff* preprocessor,
 164   it's too late by the time ``troff`` sees the input anyway).
 165
 166 * BUT if UTF-8 is declared tables are no longer processed.
 167
 168 * BUT we have a comment there and the macros following it
 169
 170 * Input and output encoding are problematic at least.
 171
 172 * input/optionstoo.txt:23: (ERROR/3) Unexpected indentation.
 173   is what it is ... leave it so.
 174
 175   TODO the curly brace on start of line hides the line
 176
 177 * doublespace after end of sentence in manpages ?
 178
 179   see https://sourceforge.net/p/docutils/bugs/427/
 180
 181   Chicago manual of style ... hard to automate.
 182
 183 Check ``docs/user/manpage.txt``
 184
 185 * escape double quotes in macro arguments ?
 186
 187   Use the special character escape sequence ``\(dq``.
 188   groff_man_style(7) explains.
 189
 190        \(dq   Basic Latin quotation mark (double quote).  Use in macro
 191               calls to prevent ‘"” from being interpreted as beginning a
 192               quoted argument, or simply for readability.
 193
 194                      .TP
 195                      .BI "split \(dq" text \(dq
 196
 197 * How to write long syntax lines.
 198
 199   groff_man_style(7) explains.::
 200
 201        \newline
 202               Join the next input line to the current one.  Except for
 203               the update of the input line counter (used for diagnostic
 204               messages and related purposes), a series of lines ending
 205               in backslash‐newline appears to groff as a single input
 206               line.  Use this escape sequence to split excessively long
 207               input lines for document maintenance.
 208
 209 * Line ends around email or web addresses in texts.
 210
 211   The ``UE`` and ``ME`` macros accept an argument, which is appended to
 212   the link text without intervening space.
 213
 214   groff_man_style(7) explains.
 215
 216        \c     End a text line without inserting space or attempting a
 217               break.  Normally, if filling is enabled, the end of a text
 218               line is treated like a space; an output line may be broken
 219               there (if not, an adjustable space is inserted); if
 220               filling is disabled, the line will be broken there, as in
 221               .EX/.EE examples.  The next line is interpreted as usual
 222               and can include a macro call (contrast with \newline).  \c
 223               is useful when three font styles are needed in a single
 224               word, as in a command synopsis.
 225
 226                      .RB [ \-\-stylesheet=\c
 227                      .IR name ]
 228
 229               It also helps when changing font styles in .EX/.EE
 230               examples, since they are not filled.
 231
 232                      .EX
 233                      $ \c
 234                      .B groff \-T utf8 \-Z \c
 235                      .I file \c
 236                      .B | grotty \-i
 237                      .EE
 238
 239   Here's an example using groff's ``MT`` and ``ME`` macros.::
 240
 241    Mail the maintainer (\c
 242    .MT maint@example.com
 243    Arthur Pewtey
 244    .ME )
 245    to submit patches.
 246
 247   How to distinguish something is inline or not in the writer
 248   so to maybe put long urls after the current paragraph ?
 249
 250