--- How to build the info pages 0---
It is very easy to build the info pages. Note that you need prel5 installed to
build the Subject info pages. The default ones are supplied, but if you want
to build new ones yourself, you need perl5.
To build the info pages, just type "make" at the high level info directory.
This will build you the text info pages that the game uses and put them into
the info.nr directory.
To build the html info page, just type "make html" at the high level info
directory. This will build you the html info pages (thanks Drake!) and put
them into the info.html directory. Use the "TOP.html" or the "all.html" as
the first html pages you reference (TOP.html is better.)
--- How to add a new info page ---
NOTE: info.pl requires perl5. If you don't have perl5, your Subject.t
files will have to be built for you by someone who has perl5.
==EASY INSTALL==
To create a new info page, follow these five easy steps:
1. Copy an existing info page and change the relevant stuff.
2. The .SA ("SEE ALSO") line at the bottom must contain at
least one Subject (see the Subjects subdirectory).
3. Make sure that the entire .SA line is on one line (i.e. no line-breaks
inside the quotes).
4. Type "info.pl".
5. Type "make".
==SECURE INSTALL==
If something goes wrong, or if you like doing things carefully, then
follow these more elaborate directions:
1. Decide which subdirectory to put your info page in:
Commands - Empire Commands
Concepts - Game concepts
Introduction - General info about playing Empire
Server - Info about the server
2. Decide what to call your info page:
- If it's an Empire command, give it the same name as the command
as listed in lib/player/empmod.c
- You may not name your info page any of the following:
"Command", "Commands", "Concept", "Concepts", "Introduction", "Server"
- Make sure there isn't another info page with the same name in a
different subdirectory.
- Make sure your info page doesn't have the same name as an existing
Subject name (see the "Subjects" subdirectory).
3. Format your info page.
Copy the same format as a similar file in the same directory.
The first "Title Header" line must be:
.TH arg1 arg2
- arg1 should be one of: Command, Concept, Introduction, Server
- arg1 should match the directory the info page is in
- If arg2 contains more than one word, make sure it's in double quotes
- if the info page is for an Empire command, then arg2 must be the
command name in ALL UPPERCASE.
The second "NAME" line must be:
.NA arg1 arg2
- arg1 must be the name of the file
- arg2 must be in quotes
- arg2 is a one-line description of the info page which info.pl will
put on the Subject page that your info page belongs to.
The last "SEE ALSO" line should be:
.SA "item1, item2, ..., subject1, subject2"
- the stuff in quotes is a list of other info pages which are
related to this page and info Subjects to which this page belongs.
- the stuff in quotes must all be on the same line
- You must include at least one subject (see the Subjects
subdirectory) in the list (at the end of the list by convention).
The lines in between can contain the following formatting characters:
Empire command syntax:
.SY "command <ARGS>"
An Empire command example:
.EX "command args"
No Formatting:
.NF
this stuff
won't be formatted
.FI
Begin paragraph:
.s1
4. Run "info.pl"
Type "info.pl" at the unix prompt.
If there are any problems with your info page, info.pl will abort
with a clear error message explaining what went wrong.
5. Type "make"
This will compile your info pages into ../info.nr
==APPENDIX A - What exactly info.pl does==
info.pl reads all of the info pages and creates a table of contents
for them organized by subject. An info page belongs to a subject if
that subject appears as an entry in the .SA ("SEE ALSO") field of the
info page _and_ that entry is not the name of another info page.
For example, the .SA field of headlines.t contains the entries
"newspaper" and "Communication". Since there's already an info page
called "newspaper.t", but there is no "Communication" info page, then
the headlines info page is considered to be a member of the
Communication
subject.
The output of this script is a bunch of files in the "Subjects"
subdirectory. The file Subjects/TOP.t is the toplevel table of
contents and lists all of the subjects. Then for each subject, a
Subjects/Subject.t file is created, listing all of the info pages that
belong to it.
==APPENDIX B - The checklist.pl script==
This little perl script compares the "list" of legal Empire commands in your
server with the Empire commands documented in the Commands
subdirectory. To run it, login to your game and type:
[##:##]% list > list.out
Then, move the list.out file to this directory and run checklist.pl.
