ManEdit - Tutorial

Contents->Tutorial

1. Introduction
2. Open An Existing Manual Page
3. Create A New Manual Page
4. Editing The Header
5. Editing Sections
   - Paragraph <LP>
   - Styles
   - List <TP>
   - Symbolic Representations
6. Reordering
7. Saving Your Manual Page
8. Installing Your Manual Page

### Introduction

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.

Back to the top

### Open An Existing Manual Page

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.

Back to the top

### Create A New Manual Page

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

Back to the top

### Editing The Header

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:

- Name Specifies the name (not the file name) of the manual page.
- Section Number Specifies the section number that this manual page belongs in. Typical section 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. Kernel & Modules
- Version Specifies the version of the subject the manual page is describing (not the version of the manual page itself). Typical version numbers have 3 numbers separated by a `.`, such as `1.2.3`.
- Author Specifies the author of the manual page's subject (not the author of the manual page itself).
- Category Specifies the category that the subject belongs to.
- Comments Specifies multiple lines of comments, typically describing copyright or other legal notices. Comments are not shown when you view manual pages normally, you can only see the comments when you view it with ManEdit, `cat`, or `more`.

All header values (including comments) may not contain any XML codes.

Back to the top

### Editing Sections

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 `&lt;` 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.

### Paragraph <LP>

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

### Styles

The text displayed in each section can have 3 different styles:

1. Normal `<fR>`
2. Bold `<fR>`
3. Underline or Italic `<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.

### List <TP>

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

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 &lt; 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.

Back to the top

### Reordering

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

Back to the top

### Saving Your Manual Page

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.

Back to the top

### Installing 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:

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

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`

Back to the top

ManEdit is Copyright © 1997-2008 WolfPack Entertainment