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 or a reference type man:tbl(1)
  87
  88 The ``\%`` is :
  89
  90   a  word  may be broken at hyphens, at ``\%`` or ``\:`` escape sequences
  91
  92 whatfore at the word start ?
  93
  94 Branden writes:
  95
  96   You will not need to generate the arguments to the MR macro with a leading
  97   \% escape sequence. ... see feature request #107
  98
  99 groff_man_style on
 100
 101    Hyperlink macros
 102        Man  page  cross references like ls(1) are best presented with .MR.  Text may be
 103        hyperlinked to email addresses with .MT/.ME or other URIs with .UR/.UE.   Hyper‐
 104        linked  text  is  supported  on  HTML and terminal output devices; terminals and
 105        pager programs must support ECMA-48 OSC  8  escape  sequences  (see  grotty(1)).
 106        When  device support is unavailable or disabled with the U register (see section
 107        “Options” below), .MT and .UR URIs are rendered between angle brackets after the
 108        linked text.
 109
 110        .MT, .ME, .UR, and .UE are GNU extensions not defined on systems  running  AT&T,
 111        Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below.  Plan 9 from
 112        User Space's troff implements .MR.
 113
 114        The arguments to .MR, .MT, and .UR should be prepared for typesetting since they
 115        can appear in the output.  Use special character escape sequences to encode Uni‐
 116        code  basic  Latin  characters  where  necessary, particularly the hyphen-minus.
 117        (See section “Portability” below.)  URIs can be lengthy; rendering them can  re‐
 118        sult  in jarring adjustment or variations in line length, or troff warnings when
 119        a hyperlink is longer than an output  line.   The  application  of  non-printing
 120        break point escape sequences \: after each slash (or series thereof), and before
 121        each  dot  (or  series  thereof)  is recommended as a rule of thumb.  The former
 122        practice avoids forcing a trailing slash in a URI onto a separate  output  line,
 123        and  the  latter  helps the reader to avoid mistakenly interpreting a dot at the
 124        end of a line as a period (or multiple dots as an ellipsis).  Thus,
 125               .UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
 126        has several potential break points in the  URI  shown.   Consider  adding  break
 127        points  before  or after at signs in email addresses, and question marks, amper‐
 128        sands, and number signs in HTTP(S) URIs.  The formatter removes  \:  escape  se‐
 129        quences  from  hyperlinks  when supplying device control commands to output dri‐
 130        vers.
 131
 132
 133 Used macros ... to be completed
 134 -------------------------------
 135
 136        .TP [indentation]
 137               Set  a  paragraph  with a leading tag, and the remainder of the paragraph
 138               indented.  A one-line input trap is planted; text on the next line, which
 139               can be formatted with a macro, becomes the tag, which is  placed  at  the
 140               current  left  margin.   The  tag  can be extended with the \c escape se‐
 141               quence.  Subsequent text is indented by indentation, if specified, and by
 142               the amount of the IN register otherwise.  If the tag is not  as  wide  as
 143               the indentation, the paragraph starts on the same line as the tag, at the
 144               applicable indentation, and continues on the following lines.  Otherwise,
 145               the  descriptive  part  of the paragraph begins on the line following the
 146               tag.
 147
 148        .TQ    Set an additional tag for a paragraph tagged with .TP.  An input trap  is
 149               planted as with .TP.
 150
 151               This  macro  is  a  GNU  extension  not  defined on systems running AT&T,
 152               Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below.
 153
 154
 155
 156 Notes
 157 -----
 158
 159 * Images and equations are discouraged.
 160
 161 * Lists in admonitions are not intended.
 162
 163 Discussions
 164 -----------
 165
 166 * Encoding declaration ``'\" t -*- coding: ISO-8859-1 -*-``
 167   in first line.
 168
 169   The part after ``t`` is a GNU Emacs convention.  A *groff* program
 170   called *preconv*\(1) understands it, but GNU *troff*\(1) itself does
 171   not.
 172
 173   The ``t`` is part of a *man*\(1) convention; GNU *troff*\(1) doesn't
 174   understand it, either (but since *tbl*\(1) is a *roff* preprocessor,
 175   it's too late by the time ``troff`` sees the input anyway).
 176
 177 * BUT if UTF-8 is declared tables are no longer processed.
 178
 179 * BUT we have a comment there and the macros following it
 180
 181 * Input and output encoding are problematic at least.
 182
 183 * input/optionstoo.txt:23: (ERROR/3) Unexpected indentation.
 184   is what it is ... leave it so.
 185
 186   TODO the curly brace on start of line hides the line
 187
 188 * doublespace after end of sentence in manpages ?
 189
 190   see https://sourceforge.net/p/docutils/bugs/427/
 191
 192   Chicago manual of style ... hard to automate.
 193
 194 Check ``docs/user/manpage.txt``
 195
 196 * escape double quotes in macro arguments ?
 197
 198   Use the special character escape sequence ``\(dq``.
 199   groff_man_style(7) explains.
 200
 201        \(dq   Basic Latin quotation mark (double quote).  Use in macro
 202               calls to prevent ‘"” from being interpreted as beginning a
 203               quoted argument, or simply for readability.
 204
 205                      .TP
 206                      .BI "split \(dq" text \(dq
 207
 208 * How to write long syntax lines.
 209
 210   groff_man_style(7) explains.::
 211
 212        \newline
 213               Join the next input line to the current one.  Except for
 214               the update of the input line counter (used for diagnostic
 215               messages and related purposes), a series of lines ending
 216               in backslash‐newline appears to groff as a single input
 217               line.  Use this escape sequence to split excessively long
 218               input lines for document maintenance.
 219
 220 * Line ends around email or web addresses in texts.
 221
 222   The ``UE`` and ``ME`` macros accept an argument, which is appended to
 223   the link text without intervening space.
 224
 225   groff_man_style(7) explains.
 226
 227        \c     End a text line without inserting space or attempting a
 228               break.  Normally, if filling is enabled, the end of a text
 229               line is treated like a space; an output line may be broken
 230               there (if not, an adjustable space is inserted); if
 231               filling is disabled, the line will be broken there, as in
 232               .EX/.EE examples.  The next line is interpreted as usual
 233               and can include a macro call (contrast with \newline).  \c
 234               is useful when three font styles are needed in a single
 235               word, as in a command synopsis.
 236
 237                      .RB [ \-\-stylesheet=\c
 238                      .IR name ]
 239
 240               It also helps when changing font styles in .EX/.EE
 241               examples, since they are not filled.
 242
 243                      .EX
 244                      $ \c
 245                      .B groff \-T utf8 \-Z \c
 246                      .I file \c
 247                      .B | grotty \-i
 248                      .EE
 249
 250   Here's an example using groff's ``MT`` and ``ME`` macros.::
 251
 252    Mail the maintainer (\c
 253    .MT maint@example.com
 254    Arthur Pewtey
 255    .ME )
 256    to submit patches.
 257
 258   How to distinguish something is inline or not in the writer
 259   so to maybe put long urls after the current paragraph ?
 260
 261