doc/src/rtd/README

   1
   2 This directory contains source for the project mandated "read the
   3 docs" .rst documentation.  If the "tfm" tool is available, the
   4 Makefile will both build the doc from the source here and "install" it
   5 into the docs directory at the repo root.  Then the generated .rst
   6 files must be checked into the repo and committed with changes to the
   7 source (maybe not the best practice).
   8
   9 The command 'make all' should be all that is needed to build the
  10 rtd documentation. Follow that with 'make publish' to actually move
  11 the .rst files into the docs directory at the root; only the changed
  12 files are moved.
  13
  14 Adding A New Man Page
  15 When a new manual page is added to the source (../man), it must be
  16 added to the list in the user's guide source in this directory.
  17
  18 Rationale
  19 Documentation is just code, and by maintaining the documentation as
  20 source is is possible to generate various forms of output with a
  21 single make.  While it is possible to convert X to Y, a true document
  22 composition language is far better at generating readable Postscript
  23 output with embedded figures as well as text and tables.
  24
  25 CAUTION:
  26 The RST syntax is as bad as python when it comes to dealing with
  27 spaces.  For example &bold( foo ) will insert spaces after the initial
  28 bold trigger, and before the trailing bold trigger which will throw
  29 the tox validation into a tizzy.  Further,  something like 'void *'
  30 and 'rmr_ '  does as well.  If needed, use the defined escape macro
  31 to add an escape in such situations; it should only generate for RST
  32 and not impact other output formats.