.TH "ManPage Writing" "5" "Release 0.0.0" "WolfPack Entertainment" "File Formats"
.SH "NAME"
\fBManPage Writing\fR \- Procedures and tutorial on writing ManPages
.SH "DESCRIPTION"
.LP 
Covers the basics from creating a new manual page
to writing complex lists of items in
\fIManual Page XML format\fR.
For use with the program manedit(1), you are assumed to
be running this program while reading this document.
.SH "EDITING"
.LP 

To edit an existing man page, first copy the man page file to another directory. It is not wise to work on original files. Most man page files come in a compressed format, usually .gz or .bz2. Therefore you need to decompress it using an appropriate tool such as GNUZip.

.LP 

Once this is done, you can start Manedit and open the uncompressed file.Good working practice would also suggest that you make regular saves while editing your work.All the usual editing facilities are available such as cut, paste, justify left,right and centre, copy etc. As you edit, you can call up the preview mode via the dropdown windows menu to check your work.

.LP 
 Once you have finished working on the file save it and recompress it if needed. 


.SH "CREATE NEW"
.LP 
To create a new manual page you can select from
the file menu either \fInew\fR or \fInew from
template\fR. Selecting \fInew\fR just creates a
new manual page with no existing header or sections.
Selecting \fInew from template\fR will prompt you
to pick a manual page template with premade generalized
header and sections.
.LP 
If this is your first time and/or you want to get
started in a hurry, just select \fInew from template\fR
and pick a template.
.SH "HEADER"
.LP 
Each manual page requires atleast one header, preferably
as the \fIfirst\fR branch item on the manual page (use drag
and drop to change the header's  position in the
manual page as needed).
.LP 
To add a new header simply select the manual page
you want to add the header to and go to
Layout\->Add Header. A new header should be added
and selected.
.LP 
Each header has the following fields:
.TP 
\fBName:\fR
Specifies name of this manual page.
.TP 
\fBSection Number:\fR
Specifies the section number that this manual page belongs
in. Typical numbers are as follows:
.LP 
        \fB1\fR User Commands
        \fB2\fR System Calls (programming)
        \fB3\fR Library Functions (programming)
        \fB4\fR Special Files
        \fB5\fR File Formats
        \fB6\fR Games
        \fB7\fR Miscellaneous
        \fB8\fR Administration
        \fB9\fR Other
.TP 
\fBVersion:\fR
Specifies the version of the subject the manual page
is describing, not the version of the manual page itself.
Recently the trend is to make this a value with
three version numbers, for example \fBRelease 0.4.3\fR.
.TP 
\fBAuthor:\fR
Specifies the individual or group involved in the
creation of the subject (not the authors of the manual page).
.TP 
\fBCategory:\fR
Specifies the category that the subject belongs to.
.TP 
\fBComments:\fR
Put any text you want here, it's also good for copyright
and other legal notices. \fBComments\fR is not shown
during regular viewing of the manual page. You only see
it when you load it in manedit's editor or viewing it
literally with a program such as more(1).
.SH "SECTIONS"
.LP 
Sections make up the majority of a manual page, each
manual page has one or more sections following the
header. See sample \fItemplates\fR from above section
\fBCREATE NEW\fR to get an idea of what typical sections
should be for certain types of manual pages.
.LP 
Each section consists of the section name (which
is specified by the \fBSection:\fR field) and the
section body which contains the bulk of the text.
.LP 
To create a new section first select the position
you want to add the section under and go to
Layout\->Add Section.
.SH "XML"
.LP 
In each section's body you will be using
\fIManual Page XML tags\fR. Since the on\-file manual page
format (which is called groff(1)) is neither user friendly
nor program friendly to read and write, manedit(1) converts
each manual page's section body into Manual Page XML
format when loading and back into groff(1) when saving.
.LP 
XML is a simpler but more ambiguous version of HTML
(HyperText Markup Language) commonly used for creating
Web Pages for the Internet World Wide Web. The XML format
is quite simple to understand.
.LP 
XML consists of \fItags\fR and \fIsymbolic
representations\fR. A \fItag\fR starts with
a \fB<\fR character, then follows with one or more
characters identifying the tag, and finally a closing
\fB>\fR character at the end.
For example \fB<br>\fR is an XML tag where
the identifier is \fBbr\fR which stands for \fIline break\fR.
.LP 
A \fIsymbolic representation\fR
is a bunch of characters representing one simpler
character but would otherwise be interpreted as XML
for instance if you wanted to put a \fB<\fR character
(but it would otherwise be interprited as the start of
an XML tag) then you can't just say \fB<\fR, instead you
need to use its \fIsymbolic representation\fR
which would be \fB&lt;\fR which means \fB<\fR
(more about symbolic representation in section
\fBSYMREP\fR).
.LP 
For a list of tags and symbolic representations see
manpage_xml_reference(5).
.LP 
The following sections deal with using XML tags to create
common styles and formats seen in most manual pages.
.SH "PARAGRAPHS"
.LP 
Most text in a section will be arranged in paragraphs,
the XML tag \fB<LP>\fR marks the beginning of
a left aligned paragraph. An example of its use
is as follows:
.LP 
        \fB<LP>\fR
.br 
        Hi, I am a paragraph and I am talking
        about things that you would like to know.
.LP 
As you can see there is a new line just after the
\fB<LP>\fR tag which marks the start of
a left aligned paragraph and the paragraph's text starts
on the very next line and continues for one more line.
When viewing the above as a parsed manual page
(click on the preview button), you will
see one paragraph and the lines will be automatically
aligned and formatted. This is commonly refered to
as WYSIWYM (What You Say Is What You Mean), for instance
putting a bunch of carrage returns dosen't always mean
you will get exactly that many new lines or a new line
at exactly the same position you placed the carrage return.
.LP 
Instead you give the above code to a manual page reader
and it will automatically put in the needed
spaces and new lines. Create a section with the above
example and click on the \fIpreview\fR button to see
what we mean!
.SH "LINE CONTROL"
.LP 
In a traditional plain text editor, you would have
to put in an exact number of spaces to achieve an indent
or put in an exact number of carrage returns to achieve
the right amount of line spacing.
.LP 
However in XML you need to use XML tags to control line
spacing. To ensure that a sentance in a paragraph
starts on a new line, you need to use the tag
\fB<br>\fR. For instance:
.LP 
        \fB<LP>\fR
        I am a paragraph, boy its a lovely
        day today, do you like the weather,
        I like the weather.
        \fB<br>\fR
        And I am going to be on a new line.
.LP 
Create a section with the above text and click on the
preview button. You will notice that after the
\fB<br>\fR
the sentance will be placed on a new line.
.LP 
One draw back is that multiple uses of \fB<br>\fR
does not produce multiple lines. So incase you would have
to ensure that there is an empty line between two
sentances, you would have to use \fB<LP>\fR.
That would effectivly separate the two sentances as two
paragraphs.
.SH "STYLES"
.LP 
Manual pages are primarly for output on typewriter\-like
instruments, which severly limit the available styles of
text that you can have. Basically you can have:
.TP 
\fB<fR>\fR
Normal font output with nothing fancy added.
.TP 
\fB<fB>\fR
\fBBold\fR (same character typed twice).
.TP 
\fB<fI>\fR
\fIUnderlined\fR (typed twice with the second type
being a underscore character). Note on GUI viewers this
may appear as italic instead of underlined.
.LP 
For example, to make a segment of text \fBbold\fR type
in some text and then select it with the pointer.
Then go to Tags\->Bold. The code should look something
like:
.LP 
        \fB<fB>\fRHi I am bold\fB<fR>\fR
.LP 
When that is displayed in the viewer it should look
like:
.LP 
        \fBHi I am bold\fR
.LP 
Procedure for creating underlined text is the same, in
each case make sure that the styled text ends with
a \fB<fR>\fR.
.SH "LISTS"
.LP 
Listing an array of parameters (often with possible values)
is used very often in manual pages. Thankfully its
quite easy to write these lists in XML, using the
tag \fB<TP>\fR.
.LP 
An example list describing two parameters would look like
the following:
.TP 
\fB\-\-help\fR
Summons a pack of wolves.
.TP 
\fB\-scan\fR [\fIvalue\fR]
Scans for the specified \fIvalue\fR if given
or scans the entire document if not.
.LP 
Now for a behind the scenes look in XML! The first item
looks like the following:
.LP 
        \fB<TP>\fR
.br 
        \fB<fB>\fR\-\-help\fB<fR>\fR
.br 
        Summons a pack of wolves.
.LP 
The first line starts with the \fB<TP>\fR
tag. Then a (mandatory) newline which contains
the parameter, the parameter and any values must be all
on one line! Finally the description which may contain
more than one line.
.LP 
The second item in the example looks like in XML:
.LP 
        \fB<TP>\fR
.br 
        \fB<fB>\fR\-scan\fB<fR>\fR
[\fB<fI>\fRvalue\fB<fR>\fR]
.br 
        Scans for the specified \fIvalue\fR if given
        or scans the entire document if not.
.SH "SYMREPS"
.LP 
Symbolic representations are used when you need to output
a character, but it would be interpreted as XML input.
(such as the greater or less than characters being
XML tag deliminators).
.LP 
Each symbolic representation starts with a \fB&\fR
and ends with a \fB;\fR character.
For instance if you wanted to use the less than
character \fB<\fR you would have to type:
.LP 
        \fB&lt;\fR
.LP 
Which would produce a \fB<\fR character.
Complete list of symbolic representations
are in page_xml_reference(5).
.LP 
One last important symbolic representation to point out
is the \fB&\fR character. Its symbolic representation
would have to be typed as:
.LP 
        \fB&amp;\fR
.SH "SEE ALSO"
manpage_xml_reference(5)
