Markus Armbruster
890e88d149
Since subjects were added in Empire 2, we've always picked them up from .SA requests. If you mistype a subject there, you get a "is a NEW subject" warning, and incorrect subject pages. When building a pristine tree, you get bogus "is a NEW subject" warnings for all subjects. If you somehow delete the generated subjects.mk, but not the generated subject files, the build breaks. Declare subjects in Make variable subjects. Drop generated makefile subject.mk. Treat unknown topics in .SA arguments as errors. This replaces the "$subj is a NEW subject" warning. Treat subjects without member pages as errors. This replaces the "The subject $subj has been removed" warning. Safer and simpler.
114 lines
3.5 KiB
Text
114 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 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 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.
|
|
|
|
|
|
==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.
|
|
|
|
|
|
==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.
|