Manual pages are help documentation used by most UNIX computers, they are individual files written in the groff file format.
Users often rely on manual pages when they need help on using a particular program or figuring out a particular file format. Programmers often rely on manual pages when they need help on writing programs that use a particular library API.
Since manual pages are written in the groff file format, a very non-intuitive text file format, it can be difficult for the average user or programmer to write manual pages. ManEdit helps users and programmers compose manual pages in a more easier to understand format called XML (X Markup Language) and arranges each manual page into sections.
When using ManEdit to create/edit manual page, ManEdit allows you to
edit each manual page in individual sections in XML format, similar
to how web pages (.html
files) are written.
This tutorial will describe how to write manual pages using ManEdit.
To open an existing manual page, run ManEdit's Editor with the full path to the manual page that you want to edit:
manedit --editor <manual_page_file_path>
Note that some manual page files come in a compressed format,
such as GZip or BZip2 (they have the extension
.gz
or .bz2
), ManEdit automatically
compresses/decompresses the manual page for you when you open and
save them.
To create a new manual page, first run ManEdit's Editor:
manedit --editor
Then go to File->New From Template...
You will be then prompt to select a manual page template file
(a premade manual page with a generic header and sections).
Manual page template files have the extension .mpt
and are found in ManEdit's global templates directory:
/usr/share/manedit/templates/
Choose the template most appropriate for the manual page that you
want to create. For example, if you are writing a manual page
for a new program that you write, pick program.mpt
.
Each manual page should have exactly one header, it is the very first subitem that you see on ManEdit's layout tree.
If your manual page does not have a header then you need to create one by selecting the toplevel item of the manual page on ManEdit's layout tree and then go to: Layout->Add Header. A new header should then be added and selected.
Each header has the following fields:
.
,
such as 1.2.3
.
cat
, or more
.
All header values (including comments) may not contain any XML codes.
Sections make up the majority of a manual page, each manual page has one or more sections following its header. To create a new section, first select the position that you want to insert the new section to on ManEdit's layout tree, then go to Layout->Add Section.
Each section has a name and a body.
Section names are fairly standard, see the
manual page template files in
/usr/share/manedit/templates/
for examples.
The section's body contains multiple lines with XML code tags.
XML consists of tags and symbolic representations.
A tag starts with a <
character, then followed
by a sequence of characters describing the tag, and then closed by
a >
character at the end. For example
<br>
is an XML tag meaning "new line".
A symbolic representation is an alternate representation
of a character. For example, if you wanted to literally state the
character <
in your documentation, you would have to represent
it as <
instead of <
since
the <
character is used to denote the beginning of a
tag.
The order and usage of XML tags and symbolic representations are critically important to the writing of manual pages. Certain tags must come before others and the syntax of text following a tag must follow a strict format. For a list of XML tags and symbolic representations, see XML Reference. Below is a list of basic XML tags and their syntax of text.
Most text in a section will be arranged in paragraphs, the
<LP>
specifies a left-aligned paragraph.
The paragraph's text that follows must be a string on the next line
ended by a newline, for example:
<LP>
I am a left-aligned paragraph.
If you need to display a newline within a paragraph's text, use
the symbolic representation <br>
.
The text displayed in each section can have 3 different styles:
<fR>
<fR>
<fI>
For example:
<LP>
I am a left-aligned paragraph with <fB>bold<fR> text.
When that is displayed in the Viewer (go to View->Preview) it should look like:
I am a left-aligned paragraph with bold text.
ManEdit allows you to easilly set a text's style by selecting the region of text that you want to set and then go to the Tags menu or click on a tag style on the tags bar to set the style.
To create lists, use the <TP> tag, followed by a list item name on the next line and a description on the next line ended by a newline. For example:
<TP>
<fB>--help<fR>
Prints a helps screen and exits.
<TP>
<fB>--version<fR>
Prints the version information and exits.
<fB>--scan<fR> [<fI>value<fR>]
Scans for the specified <fI>value<fR>.
When that is displayed in the Viewer (go to View->Preview) it should look like:
--help Prints a helps screen and exits. --version Prints the version information and exits. --scan [value] Scans for the specified value.
Symbolic representations are used when you need to display
a character, but normally it would be interpreted as a XML tag or
control character (such as >
<
and &
).
Each symbolic representation starts with a &
character
and ends with a ;
character. For instance if you wanted
to literally display the less than character <
then you
would use:
<LP>
5 is < than 6
When that is displayed in the Viewer (go to View->Preview) it should look like:
5 is < than 6
For a list of XML tags and symbolic representations, see XML Reference.
To change the order of sections that appear in your manual page, simply select the section that you want to move and drag it to its new position.
You can even move or copy sections across different manual pages by opening several manual pages at once and select and drag sections to/from one another (to copy a section, hold down the control key when you drop the section to its new location).
To save your manual page, select any section or the header of your manual page and then go to File->Save.
If you have never saved your manual page before or you want to save it to a new location then go to File->Save As. You will then be prompted for a new location to save your manual page to.
When saving your manual page using save as, you can have
ManEdit automatically compress it using GZip or BZip2 simply
by adding a .gz
or .bz2
extension to the
name of your manual page.
Manual pages must be properly named and installed according to their
section number the manual page file's extension must be
a number that corresponds to its section number followed by
an additional .gz
or .bz2
if it is compressed.
The section numbers are as follows:
For example, if your manual page is for a program (which would
be a user command) called texteditor
then you name your
manual page texteditor.1
.
Then, depending on the FHS (filesystem hierarcy standards) for your system, you would install it in one of the following locations (make sure that you have root access):
/usr/local/man/man1/texteditor.1
/usr/share/man/man1/texteditor.1
/usr/man/man1/texteditor.1
Another example would be if your manual page describes a library
function called runsomething()
and it is BZip2 compressed
then you would name your manual page runsomething.3.bz2
and install it in one of the following locations:
/usr/local/man/man3/runsomething.3.bz2
/usr/share/man/man3/runsomething.3.bz2
/usr/man/man3/runsomething.3.bz2
ManEdit is Copyright © 1997-2008 WolfPack Entertainment |