107 lines
3.5 KiB
Text
107 lines
3.5 KiB
Text
--- How to build the info pages ---
|
|
|
|
Make remakes info pages, table of contents and index automatically.
|
|
This requires Perl 5 and troff. To remake just formatted info pages,
|
|
run make info.
|
|
|
|
To make HTML info, run make html. This is not done by default. The
|
|
recommended start page is TOP.html, but you may also like all.html.
|
|
|
|
To make a single PostScript file for printing, run make info.ps. This
|
|
is not done by default. The result is currently quite ugly.
|
|
|
|
|
|
--- How to add a new info page ---
|
|
|
|
To create a new info page, follow these steps:
|
|
|
|
1. Decide which chapter 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
|
|
- Info names are case-insensitive. Make sure there isn't another
|
|
one that differs only in case.
|
|
- Make sure your info page doesn't have the same name as an existing
|
|
subject or chapter.
|
|
|
|
3. Format your info page.
|
|
|
|
The file name for a page NAME must be NAME.t. It's easiest to start
|
|
with an existing file.
|
|
|
|
The first line must be a title header:
|
|
.TH arg1 arg2
|
|
- arg1 should be the chapter, one of: Command, Concept,
|
|
Introduction, Server
|
|
- arg2 is the title of your page. If it 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 line must be a name header:
|
|
.NA arg1 arg2
|
|
- arg1 must be the name
|
|
- if the info page is for an Empire command, then arg2 must be the
|
|
exact command name
|
|
- arg2 is a one-line description of the info page which will be put
|
|
on the subject pages that your info page belongs to. It should be
|
|
in double quotes
|
|
|
|
The third line must be a level header:
|
|
.LV arg
|
|
- arg must be a level, one of Basic, Expert, Obsolete
|
|
|
|
The last line should be a see also:
|
|
.SA "item1, item2, ..., subject1, subject2"
|
|
- the stuff in quotes is a list of other info pages which are
|
|
related to this page, and subjects to which this page belongs.
|
|
- the stuff in quotes must all be on the same line
|
|
- You must include at least one subject in the list (at the end of
|
|
the list by convention). Valid subjects are listed in
|
|
info/subjects.mk.
|
|
|
|
The lines in between can contain troff requests. The following
|
|
additional requests are available:
|
|
|
|
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
|
|
|
|
Item in a description:
|
|
.L
|
|
|
|
Fancy troff magic is prone to break HTML output.
|
|
|
|
4. Format your info page, update table of contents and index
|
|
Run make info html. If it fails, peruse the error messages and fix
|
|
your info page. Run tests/info-test for additional consistency
|
|
checking.
|
|
|
|
|
|
==APPENDIX A - What exactly the Perl scripts do==
|
|
|
|
The scripts read all of the info pages and create a two-level 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.
|
|
|
|
The output of these scripts is a bunch of .t files. The file TOP.t is
|
|
the top-level table of contents and lists all of the subjects. Then
|
|
for each SUBJECT, a SUBJECT.t file is created, listing all of the info
|
|
pages that belong to it.
|