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

   1         --- How to build the info pages 0---
   2
   3 It is very easy to build the info pages.  Note that you need prel5 installed to
   4 build the Subject info pages.  The default ones are supplied, but if you want
   5 to build new ones yourself, you need perl5.
   6
   7 To build the info pages, just type "make" at the high level info directory.
   8 This will build you the text info pages that the game uses and put them into
   9 the info.nr directory.
  10
  11 To build the html info page, just type "make html" at the high level info
  12 directory.  This will build you the html info pages (thanks Drake!) and put
  13 them into the info.html directory.  Use the "TOP.html" or the "all.html" as
  14 the first html pages you reference (TOP.html is better.)
  15
  16
  17         --- How to add a new info page ---
  18
  19 NOTE: info.pl requires perl5.  If you don't have perl5, your Subject.t
  20 files will have to be built for you by someone who has perl5.
  21
  22 ==EASY INSTALL==
  23
  24 To create a new info page, follow these five easy steps:
  25 1.  Copy an existing info page and change the relevant stuff.
  26 2.  The .SA ("SEE ALSO") line at the bottom must contain at
  27     least one Subject (see the Subjects subdirectory).
  28 3.  Make sure that the entire .SA line is on one line (i.e. no line-breaks
  29     inside the quotes).
  30 4.  Type "info.pl".
  31 5.  Type "make".
  32
  33 ==SECURE INSTALL==
  34
  35 If something goes wrong, or if you like doing things carefully, then
  36 follow these more elaborate directions:
  37
  38 1.  Decide which subdirectory to put your info page in:
  39       Commands     - Empire Commands
  40       Concepts     - Game concepts
  41       Introduction - General info about playing Empire
  42       Server       - Info about the server
  43
  44 2.  Decide what to call your info page:
  45     - If it's an Empire command, give it the same name as the command
  46       as listed in lib/player/empmod.c
  47     - You may not name your info page any of the following:
  48       "Command", "Commands", "Concept", "Concepts", "Introduction", "Server"
  49     - Make sure there isn't another info page with the same name in a
  50       different subdirectory.
  51     - Make sure your info page doesn't have the same name as an existing
  52       Subject name (see the "Subjects" subdirectory).
  53
  54 3.  Format your info page.
  55
  56 Copy the same format as a similar file in the same directory.
  57 The first "Title Header" line must be:
  58 .TH arg1 arg2
  59   - arg1 should be one of: Command, Concept, Introduction, Server
  60   - arg1 should match the directory the info page is in
  61   - If arg2 contains more than one word, make sure it's in double quotes
  62   - if the info page is for an Empire command, then arg2 must be the
  63     command name in ALL UPPERCASE.
  64
  65 The second "NAME" line must be:
  66 .NA arg1 arg2
  67   - arg1 must be the name of the file
  68   - arg2 must be in quotes
  69   - arg2 is a one-line description of the info page which info.pl will
  70     put on the Subject page that your info page belongs to.
  71
  72 The last "SEE ALSO" line should be:
  73 .SA "item1, item2, ..., subject1, subject2"
  74   - the stuff in quotes is a list of other info pages which are
  75     related to this page and info Subjects to which this page belongs.
  76   - the stuff in quotes must all be on the same line
  77   - You must include at least one subject (see the Subjects
  78     subdirectory) in the list (at the end of the list by convention).
  79
  80 The lines in between can contain the following formatting characters:
  81
  82 Empire command syntax:
  83 .SY "command <ARGS>"
  84
  85 An Empire command example:
  86 .EX "command args"
  87
  88 No Formatting:
  89 .NF
  90 this stuff
  91 won't be formatted
  92 .FI
  93
  94 Begin paragraph:
  95 .s1
  96
  97 4. Run "info.pl"
  98   Type "info.pl" at the unix prompt.
  99   If there are any problems with your info page, info.pl will abort
 100   with a clear error message explaining what went wrong.
 101
 102 5. Type "make"
 103   This will compile your info pages into ../info.nr
 104
 105
 106 ==APPENDIX A  -  What exactly info.pl does==
 107
 108 info.pl reads all of the info pages and creates a table of contents
 109 for them organized by subject.  An info page belongs to a subject if
 110 that subject appears as an entry in the .SA ("SEE ALSO") field of the
 111 info page _and_ that entry is not the name of another info page.
 112
 113 For example, the .SA field of headlines.t contains the entries
 114 "newspaper" and "Communication".  Since there's already an info page
 115 called "newspaper.t", but there is no "Communication" info page, then
 116 the headlines info page is considered to be a member of the
 117 Communication
 118 subject.
 119
 120 The output of this script is a bunch of files in the "Subjects"
 121 subdirectory.  The file Subjects/TOP.t is the toplevel table of
 122 contents and lists all of the subjects.  Then for each subject, a
 123 Subjects/Subject.t file is created, listing all of the info pages that
 124 belong to it.
 125
 126
 127 ==APPENDIX B  -  The checklist.pl script==
 128
 129 This little perl script compares the "list" of legal Empire commands in your
 130 server with the Empire commands documented in the Commands
 131 subdirectory.  To run it, login to your game and type:
 132
 133   [##:##]% list > list.out
 134
 135 Then, move the list.out file to this directory and run checklist.pl.