ManPage Writing(5)

NAME
ManPage Writing - Procedures and tutorial on writing ManPages

DESCRIPTION

Covers the basics from creating a new manual page to writing complex lists of items in Manual Page XML format. For use with the program manedit(1), you are assumed to be running this program while reading this document.

EDITING

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.

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.

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

CREATE NEW

To create a new manual page you can select from the file menu either new or new from template. Selecting new just creates a new manual page with no existing header or sections. Selecting new from template will prompt you to pick a manual page template with premade generalized header and sections.

If this is your first time and/or you want to get started in a hurry, just select new from template and pick a template.

HEADER

Each manual page requires atleast one header, preferably as the first branch item on the manual page (use drag and drop to change the header's position in the manual page as needed).

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.

Each header has the following fields:

Name:
    Specifies name of this manual page.

Section Number:
    Specifies the section number that this manual page belongs in. Typical numbers are as follows:

        1 User Commands
        2 System Calls (programming)
        3 Library Functions (programming)
        4 Special Files
        5 File Formats
        6 Games
        7 Miscellaneous
        8 Administration
        9 Other

Version:
    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 Release 0.4.3.

Author:
    Specifies the individual or group involved in the creation of the subject (not the authors of the manual page).

Category:
    Specifies the category that the subject belongs to.

Comments:
    Put any text you want here, it's also good for copyright and other legal notices. Comments 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).

SECTIONS

Sections make up the majority of a manual page, each manual page has one or more sections following the header. See sample templates from above section CREATE NEW to get an idea of what typical sections should be for certain types of manual pages.

Each section consists of the section name (which is specified by the Section: field) and the section body which contains the bulk of the text.

To create a new section first select the position you want to add the section under and go to Layout->Add Section.

XML

In each section's body you will be using Manual Page XML tags. 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.

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.

XML consists of tags and symbolic representations. A tag starts with a < character, then follows with one or more characters identifying the tag, and finally a closing > character at the end. For example <br> is an XML tag where the identifier is br which stands for line break.

A symbolic representation is a bunch of characters representing one simpler character but would otherwise be interpreted as XML for instance if you wanted to put a < character (but it would otherwise be interprited as the start of an XML tag) then you can't just say <, instead you need to use its symbolic representation which would be &lt; which means < (more about symbolic representation in section SYMREP).

For a list of tags and symbolic representations see manpage_xml_reference(5).

The following sections deal with using XML tags to create common styles and formats seen in most manual pages.

PARAGRAPHS

Most text in a section will be arranged in paragraphs, the XML tag <LP> marks the beginning of a left aligned paragraph. An example of its use is as follows:

        <LP>
        Hi, I am a paragraph and I am talking
        about things that you would like to know.

As you can see there is a new line just after the <LP> 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.

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 preview button to see what we mean!

LINE CONTROL

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.

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 <br>. For instance:

        <LP>
        I am a paragraph, boy its a lovely
        day today, do you like the weather,
        I like the weather.
        <br>
        And I am going to be on a new line.

Create a section with the above text and click on the preview button. You will notice that after the <br> the sentance will be placed on a new line.

One draw back is that multiple uses of <br> 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 <LP>. That would effectivly separate the two sentances as two paragraphs.

STYLES

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:

<fR>
    Normal font output with nothing fancy added.

<fB>
    Bold (same character typed twice).

<fI>
    Underlined (typed twice with the second type being a underscore character). Note on GUI viewers this may appear as italic instead of underlined.

For example, to make a segment of text bold type in some text and then select it with the pointer. Then go to Tags->Bold. The code should look something like:

        <fB>Hi I am bold<fR>

When that is displayed in the viewer it should look like:

        Hi I am bold

Procedure for creating underlined text is the same, in each case make sure that the styled text ends with a <fR>.

LISTS

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 <TP>.

An example list describing two parameters would look like the following:

--help
    Summons a pack of wolves.

-scan [value]
    Scans for the specified value if given or scans the entire document if not.

Now for a behind the scenes look in XML! The first item looks like the following:

        <TP>
        <fB>--help<fR>
        Summons a pack of wolves.

The first line starts with the <TP> 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.

The second item in the example looks like in XML:

        <TP>
        <fB>-scan<fR> [<fI>value<fR>]
        Scans for the specified value if given
        or scans the entire document if not.

SYMREPS

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).

Each symbolic representation starts with a & and ends with a ; character. For instance if you wanted to use the less than character < you would have to type:

        &lt;

Which would produce a < character. Complete list of symbolic representations are in page_xml_reference(5).

One last important symbolic representation to point out is the & character. Its symbolic representation would have to be typed as:

        &amp;

SEE ALSO
manpage_xml_reference(5)