git.pond.sub.org Git - empserver/blob - info/README

   1         --- How to build the info pages ---
   2
   3 Make remakes info pages, table of contents and index automatically.
   4 This requires Perl 5 and troff.  To remake just formatted info pages,
   5 run make info.
   6
   7 To make HTML info, run make html.  This is not done by default.  The
   8 recommended start page is TOP.html, but you may also like all.html.
   9
  10 To make a single PostScript file for printing, run make info.ps.  This
  11 is not done by default.  The result is currently quite ugly.
  12
  13
  14         --- How to add a new info page ---
  15
  16 To create a new info page, follow these steps:
  17
  18 1.  Decide which chapter to put your info page in:
  19       Commands     - Empire Commands
  20       Concepts     - Game concepts
  21       Introduction - General info about playing Empire
  22       Server       - Info about the server
  23
  24 2.  Decide what to call your info page:
  25     - If it's an Empire command, give it the same name as the command
  26       as listed in lib/player/empmod.c
  27     - Info names are case-insensitive.  Make sure there isn't another
  28       one that differs only in case.
  29     - Make sure your info page doesn't have the same name as an existing
  30       subject or chapter.
  31
  32 3.  Format your info page.
  33
  34 The file name for a page NAME must be NAME.t.  It's easiest to start
  35 with an existing file.
  36
  37 The first line must be a title header:
  38 .TH arg1 arg2
  39   - arg1 should be the chapter, one of: Command, Concept,
  40     Introduction, Server
  41   - arg2 is the title of your page.  If it contains more than one
  42     word, make sure it's in double quotes
  43   - if the info page is for an Empire command, then arg2 must be the
  44     command name in ALL UPPERCASE.
  45
  46 The second line must be a name header:
  47 .NA arg1 arg2
  48   - arg1 must be the name
  49   - if the info page is for an Empire command, then arg2 must be the
  50     exact command name
  51   - arg2 is a one-line description of the info page which will be put
  52     on the subject pages that your info page belongs to.  It should be
  53     in double quotes
  54
  55 The third line must be a level header:
  56 .LV arg
  57   - arg must be a level, one of Basic, Expert, Obsolete
  58
  59 The last line should be a see also:
  60 .SA "item1, item2, ..., subject1, subject2"
  61   - the stuff in quotes is a list of other info pages which are
  62     related to this page, and subjects to which this page belongs.
  63   - the stuff in quotes must all be on the same line
  64   - You must include at least one subject in the list (at the end of
  65     the list by convention).  Valid subjects are listed in
  66     info/subjects.mk.
  67
  68 The lines in between can contain troff requests.  The following
  69 additional requests are available:
  70
  71 Empire command syntax:
  72 .SY "command <ARGS>"
  73
  74 An Empire command example:
  75 .EX "command args"
  76
  77 No Formatting:
  78 .NF
  79 this stuff
  80 won't be formatted
  81 .FI
  82
  83 Begin paragraph:
  84 .s1
  85
  86 Item in a description:
  87 .L
  88
  89 Fancy troff magic is prone to break HTML output.
  90
  91 4. Format your info page, update table of contents and index
  92   Run make info html.  If it fails, peruse the error messages and fix
  93   your info page.  Run tests/info-test for additional consistency
  94   checking.
  95
  96
  97 ==APPENDIX A  -  What exactly the Perl scripts do==
  98
  99 The scripts read all of the info pages and create a two-level table of
 100 contents for them, organized by subject.  An info page belongs to a
 101 subject if that subject appears as an entry in the .SA ("SEE ALSO")
 102 field of the info page.
 103
 104 The output of these scripts is a bunch of .t files.  The file TOP.t is
 105 the top-level table of contents and lists all of the subjects.  Then
 106 for each SUBJECT, a SUBJECT.t file is created, listing all of the info
 107 pages that belong to it.