[AD] Man pages

[George Foot <george.foot@xxxxxxxxxx>]

On Tue, Nov 16, 1999 at 08:10:35PM +0000, Shawn Hargreaves wrote:
> I'm hesitant to leap into learning how the manpage format works, though, 
> since I just looked a few, and they seem quite hairy :-) I don't suppose 
> anyone has a simple one that I could use as a template? If someone can 
> supply a sample of what something like install_allegro.man ought to look 
> like, I'll alter the makedoc utility to spit out everything else in that 
> format as well...

OK, I've attached `install_allegro.3'.  There's a bit more to it
than this though; `install_allegro' isn't very representative.
:)

manpages are basically *roff documents, but make use of the -man
macros.  The *roff formats get pretty complicated -- it's a
full-blown typesetting system really -- but you don't need to
know much.  Mostly you can just copy the system manpages and
especially refer to man(7), which describes the -man macros and
conventions for how things should look.  I don't think we need
to stick to the conventions rigorously; assuming the HTML output
already uses things like bold and italics to emphasise variable
names, you just need to change these to the roff format
(\fB..\fP and \fI..\fP).

We ought to have some form of index too.  We can have a manpage
`allegro.7' containing the main menu to other pages like
`allegro-using.7', `allegro-unicode.7', etc.  These pages
contain menus of other functions, like `install_allegro', which
all live in section 3.  This mirrors how SVGAlib's manpages are
laid out.

Of course everything goes into /usr/local/man/man*.  One other
thing we might like to do is remove any cached versions of our
pages when we install them; otherwise the changes won't be seen.

George

.TH install_allegro 3 "18 November, 1999" "Allegro 4.0" "Allegro manual"
.SH NAME
install_allegro \- initialises the Allegro library
.SH SYNOPSIS
.B #include <allegro.h>
.sp
.BI "int install_allegro(int " system_id ", int *" errno_ptr ", int (*" atexit_ptr ")());"
.SH DESCRIPTION
Initialises the Allegro library. You must call either this or
\fBallegro_init\fP(3) before doing anything else. The available system ID
codes will vary from one platform to another, but you will almost
always want to pass \fBSYSTEM_AUTODETECT\fP.  Alternatively, \fBSYSTEM_NONE\fP
installs a stripped down version of Allegro that won't even try to
touch your hardware or do anything platform specific: this can be
useful for situations where you only want to manipulate memory
bitmaps, such as the text mode datafile tools or the Windows GDI
interfacing functions. The \fIerrno_ptr\fP and \fIatexit_ptr\fP parameters
should point to the \fIerrno\fP variable and \fIatexit\fP function from your
libc: these are required because when Allegro is linked as a DLL,
it doesn't have direct access to your local libc data.
.SH "SEE ALSO"
.BR allegro_init "(3), " allegro_exit (3)