doc/README

   1 # Author: Scott Smedley
   2
   3 This directory contains fvwm XML documentation. It is configured
   4 to output an fvwm.1 man page & a plethora of HTML files - all from
   5 the same (XML) source.
   6
   7 By default, only the man page is generated. If you would like to
   8 generate the HTML documentation, use:
   9
  10   $ ./configure --enable-htmldoc
  11
  12 If you do not want to generate the man page, use:
  13
  14   $ ./configure --disable-mandoc
  15
  16 Once it is built, you should be able to point your web browser to:
  17
  18   file:///usr/local/share/doc/fvwm/index.html
  19
  20 (Change "/usr/local" if you use ./configure --prefix="...".)
  21
  22 For developers, the XML source files supersede the old fvwm man
  23 page.  Please make any documentation changes here & NOT in the
  24 fvwm/fvwm.1.in file.
  25
  26 If you are editing the documentation for an fvwm command, you will
  27 find an XML file relating to that command in the doc/command/
  28 directory.  Any other documentation changes (e.g. general
  29 description) will most likely need to be made in the doc/fvwm
  30 directory.
  31
  32 The XML syntax is intuitive - a cursory inspection of a few XML
  33 files should suffice to allow even a novice user to make their
  34 changes.  However, there are a few idiosyncrasies worth pointing
  35 out:
  36
  37 Formatting instructions
  38 =======================
  39
  40 * The name fvwm is spelled "fvwm".  At the beginning of a sentence
  41   or in other places where nouns are capitalized: "Fvwm".  It's
  42   *never* spelled "FVWM".
  43
  44 * Use <fvwmref cmd="Command"/> when referring to an fvwm
  45   command, e.g.:
  46
  47     <fvwmref cmd="Style"/>
  48
  49   This will create a link to the Style command (in HTML output).
  50   Caveat: don't use <fvwmref> to reference commands that are
  51   actually being described. ie. In the Style.xml file, you won't
  52   see any <fvwmref>s to the Style command.
  53
  54 * Use <fvwmref cmd="Command" opt="Option"/> when _referring_ to an
  55   fvwm command option, e.g.:
  56
  57     <fvwmref cmd="Style" opt="Font/>
  58
  59   This will create a link to the Font option of the Style command.
  60
  61 * Use <fvwmopt cmd="Command" opt="Option"> when _describing_ an
  62   option to a command, e.g.:
  63
  64     <fvwmopt cmd="Style" opt="Font"/>
  65
  66   This will highlight the option name & allow the option to be
  67   referenced elsewhere.
  68
  69 * Use <fvwmref mod="Module"/> when referring to an fvwm module, e.g.:
  70
  71     <fvwmref mod="FvwmPager"/>
  72
  73   This will create a link to the FvwmPager module (in HTML
  74   output).
  75
  76 * Use <fvwmref sect="filename" opt="option" name="text"/> when
  77   refering to a different section.
  78
  79     <fvwmref sect="colorGradients" opt="color_gradients"
  80      name="Color Gradients"/>
  81
  82 * Use <... output="html"> to wrap text that should only appear in
  83   HTML output.  E.g.
  84
  85     <para output="html">This text only appears in HTML.</para>
  86
  87 * Use <... output="man"> to wrap text that should only only appear
  88   in man-page output, e.g.
  89
  90     <para output="man">This text only appears in man page.</para>
  91
  92 * Use <filename> for filenames.
  93
  94 * Use <envar> for environment variables.
  95
  96 * Use <ulink> for links to web pages.
  97
  98 * Use <acronym> for acronyms.
  99
 100 * Use <keysym> for key names.
 101
 102
 103 How to add documentation for a new fvwm command
 104 ===============================================
 105
 106 1. Copy a similar command, e.g.
 107
 108      $ cd doc/commands && cp Echo.xml EchoFuncDefinition.xml
 109
 110 2. Edit contents appropriately. Make sure the section id, title
 111    and cmdsynopsis are correct.
 112
 113 3. Ensure the new command appears in the appropriate section of the
 114    man page, e.g. this line is included in fvwm/userFunctions.xml:
 115
 116      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 117       href="../commands/EchoFuncDefinition.xml" />
 118
 119 4. Add the new command to groupedCommands.html.
 120
 121 5. Add the new command to allCommands.html - this content is
 122    auto-generated by a script in the util/ subdirectory.  First
 123    add the command name to the alphabetically sorted util/cmds.txt
 124    file, then run:
 125
 126      $ cd doc/util
 127      $ ./genAllCommands.pl cmds.txt
 128
 129 7. Add a ChangeLog entry to doc/ChangeLog.