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 remake 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
  11         --- How to add a new info page ---
  12
  13 To create a new info page, follow these steps:
  14
  15 1.  Decide which chapter to put your info page in:
  16       Commands     - Empire Commands
  17       Concepts     - Game concepts
  18       Introduction - General info about playing Empire
  19       Server       - Info about the server
  20
  21 2.  Decide what to call your info page:
  22     - If it's an Empire command, give it the same name as the command
  23       as listed in lib/player/empmod.c
  24     - Info names are case-insensitive.  Make sure there isn't another
  25       one that differs only in case.
  26     - Make sure your info page doesn't have the same name as an existing
  27       subject or chapter.
  28
  29 3.  Format your info page.
  30
  31 The file name for a page NAME must be NAME.t.  It's easiest to start
  32 with an existing file.
  33
  34 The first line must be a title header:
  35 .TH arg1 arg2
  36   - arg1 should be the chapter, one of: Command, Concept,
  37     Introduction, Server
  38   - arg2 is the title of your page.  If it contains more than one
  39     word, make sure it's in double quotes
  40   - if the info page is for an Empire command, then arg2 must be the
  41     command name in ALL UPPERCASE.
  42
  43 The second line must be a name header:
  44 .NA arg1 arg2
  45   - arg1 must be the name
  46   - arg2 is a one-line description of the info page which will be
  47     put on the Subject page that your info page belongs to.  It should
  48     be in double quotes
  49
  50 The third line must be a level header:
  51 .LV arg
  52   - arg must be a level, one of Basic, Expert
  53
  54 The last line should be a see also:
  55 .SA "item1, item2, ..., subject1, subject2"
  56   - the stuff in quotes is a list of other info pages which are
  57     related to this page and info Subjects to which this page belongs.
  58   - the stuff in quotes must all be on the same line
  59   - You must include at least one subject (see the Subjects
  60     subdirectory) in the list (at the end of the list by convention).
  61
  62 The lines in between can contain troff requests.  The following
  63 additional requests are available:
  64
  65 Empire command syntax:
  66 .SY "command <ARGS>"
  67
  68 An Empire command example:
  69 .EX "command args"
  70
  71 No Formatting:
  72 .NF
  73 this stuff
  74 won't be formatted
  75 .FI
  76
  77 Begin paragraph:
  78 .s1
  79
  80 Item in a description:
  81 .L
  82
  83 Fancy troff magic is prone to break HTML output.
  84
  85 4. Format your info page, update table of contents and index
  86   Run make info html.  If it fails, peruse the error messages and fix
  87   your info page.
  88
  89
  90 ==APPENDIX A  -  What exactly the Perl scripts do==
  91
  92 The scripts read all of the info pages and create a two-level table of
  93 contents for them, organized by subject.  An info page belongs to a
  94 subject if that subject appears as an entry in the .SA ("SEE ALSO")
  95 field of the info page _and_ that entry is not the name of another
  96 info page.
  97
  98 For example, the .SA field of headlines.t contains the entries
  99 "newspaper" and "Communication".  Since there's already an info page
 100 called "newspaper.t", but there is no "Communication" info page, then
 101 the headlines info page is considered to be a member of the
 102 Communication
 103 subject.
 104
 105 The output of these script is a bunch of .t files.  The file TOP.t is
 106 the top-level table of contents and lists all of the subjects.  Then
 107 for each SUBJECT, a SUBJECT.t file is created, listing all of the info
 108 pages that belong to it.
 109
 110
 111 ==APPENDIX B  -  The checklist.pl script==
 112
 113 FIXME This does not work at the moment
 114
 115 This little perl script compares the "list" of legal Empire commands
 116 in your server with the Empire commands documented in info.  To run
 117 it, login to your game and type:
 118
 119   [##:##]% list > list.out
 120
 121 Then, move the list.out file to this directory and run checklist.pl.