Markus Armbruster
e9a69b6bc9
Mark obsolete pages with '+' in subject pages. Drop the separate
"Obsolete" subject page: move "info Innards" to subject "Server", and
"info update" to "Updates" (where it came from in commit a5764534,
v4.3.10).
121 lines
3.8 KiB
Text
121 lines
3.8 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 remake 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.
|
|
|
|
|
|
--- 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
|
|
- arg2 is a one-line description of the info page which will be
|
|
put on the Subject page 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 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 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.
|
|
|
|
|
|
==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 _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 these script 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.
|
|
|
|
|
|
==APPENDIX B - The checklist.pl script==
|
|
|
|
FIXME This does not work at the moment
|
|
|
|
This little perl script compares the "list" of legal Empire commands
|
|
in your server with the Empire commands documented in info. 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.
|