Writing Help for man
Volume Number: 24 (2008)
Issue Number: 09
Column Tag: Help
Writing Help for man
Learn how to write, install and test man help files on Mac OS X
by José R.C. Cruz
Helping The Masses
When they first showed on personal computers, most software packages came with printed manuals. Now modern packages come with electronic manuals, which are easy to search and update.
MacOS X can handle four different formats of electronic manuals. It uses a separate tool to display each format. For manuals written in PDF, Mac OS X uses the Preview utility. For manuals written in HTML, it uses either Safari or Help Viewer. For those written in either TEXT or RTF, it uses the TextEdit utility. And for manuals written in mdoc, it uses the command-line tool man.
In this article, you will learn how to use the man tool to view a manual. Then you will learn how to write and format a manual using mdoc macros. Next, you will find out how to install and test your manual on MacOS X. You will also learn how to export the manual to three different file formats.
So let us get started, shall we?
The Man Tool
The man tool is part of the basic help system found in all Unix-based operating system. This tool is located in the /usr/bin directory, and is available to all users. And as stated earlier, the man tool displays manuals written as mdoc files.
Using the Tool
The basic usage syntax of the man tool is shown below.
man [section] file_name
The file_name argument is the name of the mdoc file you want to view. This is often the same name as the tool that "owns" the file. The section argument sets the subdirectory to look for the mdoc file. More about man subdirectories are covered later in this article.
Using the man tool is simplicity itself. For example, to display the manual for the gzip tool, type man gzip at the Terminal prompt. First, the man tool searches the directory /usr/share/man for gzip's mdoc file. When it finds the file, it displays its first page onto the Terminal window. Otherwise, it displays an error message stating that the tool does not have an mdoc file.
Navigating the Manual
Navigating the displayed manual is quite simple. To display the next page, press the Space bar. The tool then displays the next N lines of the manual, where N is the maximum number of lines that the Terminal window can show. To display the previous page, press the <B> key.
To display half of the next page, press the <D> key. The tool then displays the next N/2 lines of the manual. To display half of the previous page, press the <U> key.
To scroll down the manual by one line, press the <Down-Arrow> key. To scroll up by one line, press the <Up-Arrow> key.
To scroll down the manual by n number of lines, enter the number at the <:> prompt and press the <Return> key. For example, to scroll down by ten lines, type the number 10 at the prompt and then press the same key.
To scroll down to a specific line on the manual, enter the line number at the <:> prompt and press the <G> key. For example, to scroll down to line 10 of the manual, type the number 10 at the prompt and then press the same key.
Searching the Manual
The man tool can also search for a specific word or phrase in the manual. The search always starts at the first line of the mdoc file. When the tool finds a matching word or phrase, it highlights the word or phrase on the displayed page.
To search forwards for the word foobar, type /foobar at the <:> prompt and press the <Return> key. To repeat this search, type only the </> character at the prompt and then press the same key. Additionally, typing 'n' will find the next match.
To search backwards for the word foobar, type ?foobar at the <:> prompt, and press the <Return> key. Again, to repeat this search, type only the <?> character and then press the same key. Also, like typing 'n', you can use shift-N to find the previous match.
Writing An Mdoc File
The mdoc file serves as the electronic manual for a command-line tool. In its basic form, the manual shows how to use the tool, and how to configure it. It also shows what options are offered by the tool, and what errors it may return. The manual also refers to other tools that do related functions.
Anatomy of the File
Figure 1 shows the structure of a basic mdoc file. The header (orange) shows the file name, and its section number and title. The summary (red) shows the name of the target tool, and a brief description of that tool.
The synopsis (green) shows the usage syntax of the target tool. The usage syntax shows all the options and arguments used by the tool. If the tool has more than one usage syntaxes, this area will show those syntaxes as well.
The document body (blue) provides a detailed description of the tool. It shows how to use the tool and how to configure it. It also describes any options available from the tool, any error codes returned by the tool, and any known issues and limitations.
The cross-reference (purple) lists the manual titles and section numbers for other related tools.
Figure 1. Structure of a basic mdoc file
The contents of an mdoc file are formatted using mdoc macros. Each macro is two characters in length, and is placed before the text being formatted. Also, if the macro is at the start of the line, it is preceded by a period.
You can use your favorite text editor to write an mdoc file. Be aware, however, that most of these editors lack any palette support for the macro language. Thankfully, you only need a handful of macros to write a decent mdoc file. You can always learn more about the macro language by typing man mdoc at the Terminal prompt.
Writing the Header
To write the header, first set the document date with the Dd macro. For example, assume you created the mdoc file on January 1, 2007. To use that date, type the entry as follows.
.Dd January 01, 2007
Make sure to type the entire date in full; do not abbreviate any parts of that date.
Next, set the document title and section with the Dt macro. If possible, use the name of the tool as the document title. For instance, for the foobar tool, type the entry as follows.
.Dt FOOBAR 1
Always type the document title in uppercase. Also, use Table 2 to choose the right section number for your file.
Finally, set the host operating system with the Os macro. For instance, since the foobar tool runs on Mac OS X, type the entry as follows.
.Os Darwin
Use the value from the sysctl node kern.ostype as the text for this macro.
Writing the Summary
To write the summary, first set the section heading by typing .Sh NAME. Then use the Nm macro to display the tool's name. Finally, use the Nd macro to display brief description of the tool. Make sure to keep the description as short as possible. A good rule of thumb is to keep it within 80 characters.
The following example shows the entries for the foobar tool's summary.
.Sh NAME
.Nm foobar
.Nd Lorem ipsum dolor sit amet
If you type man foobar at the Terminal prompt, the man tool displays the above summary as follows.
NAME
foobar - Lorem ipsum dolor sit amet
Notice that the man tool displays the name and brief description on the same line. Also, notice that it indents that line from the left margin by five spaces.
Writing the Synopsis
To write the synopsis, first set the section heading by typing .Sh SYNOPSIS. Then enter each usage syntax in the following order.
.Nm
optional_flags
optional_arguments
flags
arguments
Here, the Nm macro displays the primary name of the tool.
Use the Fl macro to set the flags, and the Ar macro to set the arguments. The Fl macro displays the flags preceded by a dash. The Ar macro displays the arguments as underlined text. For flags or arguments deemed optional by the tool, set them with the Op macro. This macro displays those flags and arguments enclosed in square brackets.
Suppose, for example, that the usage syntax for the foobar tool is as follows.
foobar [-abcde] [arg1] –B arg2 arg3
To display the above syntax, type the synopsis entries as shown below.
.Sh SYNOPSIS
.Nm
.Op Fl abcde
.Op Ar arg1
.Fl B Ar arg2
.Ar arg3
Now assume that the foobar tool has the following usage syntax.
foobar –fgh arg2 arg4
To include this second syntax, modify the entries as follows.
.Sh SYNOPSIS
.Nm
.Op Fl abcde
.Op Ar arg1
.Fl B Ar arg2
.Ar arg3
.Nm
.Fl fgh
.Ar arg2 arg4
Again, notice that the Nm macro still precedes the entries for the second syntax.
Writing the Document Body
A document body can have more than one section. Most, if not all of them, start with a DESCRIPTION section. First, set the section heading by typing .Sh DESCRIPTION. Then type the paragraph text that goes after the heading.
For example, suppose you want the mdoc file to use the following description.
DESCRIPTION
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat
eu tellus, voluptas molestie. Nunc amet in, tempus ut mauris
morbi, sed convallis arcu aspernatur morbi odio, ac integer.
Pretium rhoncus eget libero, et ultricies faucibus.
To create this description, enter the entries as follows.
.Sh DESCRIPTION
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat
eu tellus, voluptas molestie. Nunc amet in, tempus ut mauris morbi,
sed convallis arcu aspernatur morbi odio, ac integer. Pretium rhoncus
eget libero, et ultricies faucibus.
It matters not if you typed the paragraph as one continuous line of text, or as lines of text ending with a carriage return. The man tool will decide for itself how to display the paragraph on the Terminal window. Make sure to avoid breaking up a word; this will prevent the tool from adding a space between the broken parts. For instance, if you typed the following entries
Lorem ipsum dol
or sit amet
the man tool will display them as Lorem ipsum dol or sit amet.
You can have multiple paragraphs under the same section heading. To separate the paragraphs, use the Pp macro. This will separate the paragraphs by two CRLF characters. For example, assume you want your description to read as follows.
DESCRIPTION
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat
eu tellus, voluptas molestie.
Nunc amet in, tempus ut mauris morbi, sed convallis arcu
aspernatur morbi odio, ac integer. Pretium rhoncus eget libero,
et ultricies faucibus.
To create this description, modify the entries as follows.
.Sh DESCRIPTION
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat
eu tellus, voluptas molestie.
.Pp
Nunc amet in, tempus ut mauris morbi, sed convallis arcu aspernatur
morbi odio, ac integer. Pretium rhoncus eget libero, et ultricies
faucibus.
You can also use the Sh macro to start a new section heading. Table 1 is a list of some common headings used by other mdoc files. Choose the right heading for your section, or use your own heading.
Table 1. Some common section headings.
Finally, you can use the Nm to insert the tool's name into the paragraph. You can also use the Op, Fl, and Ar macros to format any text that refer to an option, flag, or argument. Make sure to place each macro in a separate line.
For example, suppose you want the following paragraph in your EXAMPLES section:
EXAMPLES
To use the foobar tool, type the following statement at the prompt.
foobar -ax arg1 arg2
Make sure that arg1 is a valid file and arg2 is an existing
directory.
To create the above paragraph, type the entries as follows.
.Sh EXAMPLES
To use the
.Nm
tool, type the following statement at the prompt.
.Pp
.Nm Fl ax Ar arg1 arg2
.Pp
Make sure that
.Ar arg1
is a valid file and
.Ar arg2
is an existing directory.
Writing the Cross-Reference
To write the cross-reference, first set the section heading by typing .Sh SEE ALSO. Then enter each cross-reference in the following format
.Xr document_name section_number
The argument document_name is the name of mdoc file you are referring to. The argument section_number is the section number for that file. Make sure to end each entry with a space and a comma, with the exception of the last one.
For example, suppose you want the mdoc file to have the following cross-references.
SEE ALSO
foo(1), bar(2)
To create the above cross-references, type the entries as follows.
.Sh SEE ALSO
.Xr foo 1 ,
.Xr bar 2
Editing The Mdoc File
As you write your mdoc file, you may find some words or phrases that need extra emphasis. You may also find that some entries are better displayed as a list. Sometimes, you want to add standard statements or your own comments to the file.
Once again, you can do many of these tasks with mdoc macros.
Working with Font Styles
An effective and simple way to emphasize a word or phrase is to change the font style. Assume, for example, you have the following phrase in your mdoc file.
Lorem ipsum dolor sit amet, tellus nullam
To underline the words ipsum and dolor, use the Em macro as shown below.
Lorem
.Em ipsum dolor
dolor sit amet, tellus nullam
The man tool will display the phrase as follows.
Lorem ipsum dolor sit amet, tellus nullam
Notice that the Em macro does not underline the space between the two words.
To display those words in bold, use the Sy macro.
Lorem
.Sy ipsum dolor
dolor sit amet, tellus nullam
Again, the tool will display the phrase as follows.
Lorem ipsum dolor sit amet, tellus nullam
To display only the word dolor in plain font, insert an Li macro before that word.
Lorem
.Sy ipsum Li dolor
dolor sit amet, tellus nullam
The tool will now display the phrase as follows.
Lorem ipsum dolor sit amet, tellus nullam
Note that the Li macro cancels the setting made by the Sy macro.
Making a One-column List
Some entries are best shown as a one-column list. Below are the macros that make up that list.
.Bl [-bullet | -item | -enum]
.It
entry_1
.It
entry_2
.
.
.It
entry_n
.El
The Bl macro marks the start of the list. It also selects the type of list to be displayed. The It macro marks each entry in the list. Finally, the El macro marks the end of the list.
Suppose, for example, you want to show the following bulleted list.
- Lorem ipsum dolor sit amet
- Pretium rhoncus eget libero
- Etiam erat vestibulum
To create this list, type the entries into your mdoc file as shown below.
.Bl -bullet
.It
Lorem ipsum dolor sit amet
.It
Pretium rhoncus eget libero
.It Etiam erat vestibulum
.El
Note that the Bl macro uses the -bullet option. To display these same entries as an ordered list, change the Bl option to -enum. To display them as a simple sequence, change the option to -item.
Making a Two-column List
Now, some entries are best shown as a two-column list. Below are the macros that make up that list.
.Bl [-tag | -hang | -ohang]
.It column_1_entry_1
column_2_entry_1
.It column_1_entry_2
column_2_entry_1
.
.
.It column_1entry_n
column_2_entry_1
.El
Note that the entries for the first column follows the It macro. The entries for the second column, however, comes right after the It entry. Finally, note that the list can have one of three possible forms.
For example, assume you want to use the following entries in the mdoc file.
lorem Lorem ipsum dolor sit amet, tellus nullam justo felis
ac nullam Ac nullam pellentesque in enim
To display a tagged list, type these entries as shown below.
.Bl -tag
.It lorem
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat
eu tellus
.It ac nullam
Ac nullam pellentesque in enim
.El
The list will appear as follows.
lorem Lorem ipsum dolor sit amet, tellus nullam justo felis
feugiat eu tellus
ac nullam Ac nullam pellentesque in enim
In the above list, the width of column 1 is the length of the longest word, which is ac nullam. Also, five spaces separate column 1 and column 2. Finally, column 2 word-wraps the longer phrase, and aligns the wrapped text to its left margin.
To display a hanging list, change the Bl option to -hang. The list now appears as follows.
lorem Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat
eu tellus
ac nullam Ac nullam pellentesque in enim
Again, column 1 does not keep a constant width. Also, the spacing between column 1 and column 2 varies with each entry. And column 2 aligns the wrapped text to its own left margin.
To display an overhanging list, change the Bl option to -ohang. This list then appears as follows.
lorem
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat eu
tellus
ac nullam
Ac nullam pellentesque in enim
This time, the column 1 and column 2 alternate their entries down the list. They also align their entries to the same left margin.
Formatting a List
All previous list examples double-space their rows, i.e. each row ends with two <CRLF> characters. Double-spacing makes each row more readable, especially when the row has long text phrases. But if you prefer to use single-spacing, change the row spacing by using the Bl option compact. For example, to use single-spacing on the bulleted list example, change the entries as follows.
.Bl -bullet
.It
Lorem ipsum dolor sit amet
.It
Pretium rhoncus eget libero
.It Etiam erat vestibulum
.El
The bulleted list now appears as shown below.
- Lorem ipsum dolor sit amet
- Pretium rhoncus eget libero
- Etiam erat vestibulum
Also, a tagged list sets the column 1 width to its longest word or phrase. If you want to specify your own width, use the Bl option -width. For example, to set the column 1 width to the word "lorem", modify the list entries as follows.
.Bl -tag -width "lorem"
.It lorem
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat
eu tellus
.It ac nullam
Ac nullam pellentesque in enim
.El
The tagged list now appears as shown below.
lorem Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat eu
tellus
ac nullam
Ac nullam pellentesque in enim
Notice that the second entry in column 2 appears below the second entry in column 1.
Finally, the entire list aligns itself to the document's left margin by default. To change this, use the Bl option -offset. Type –offset indent to place the list five spaces away from the document's left margin. Type -offset indent-two to place it ten spaces. And type -offset left to place the list at the document's left margin, which is the default.
Suppose, for example, you have the following entries in your mdoc file.
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat eu
tellus, voluptas molestie.
.Pp
.Bl -bullet
.It
Nunc amet in, tempus ut mauris morbi
.It
Ac nullam pellentesque in enim
.El
.Pp
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat eu
tellus, voluptas molestie.
These entries place a bulleted list between two paragraphs as shown below.
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat eu
tellus, voluptas molestie.
- Nunc amet in, tempus ut mauris morbi
- Ac nullam pellentesque in enim
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat eu
tellus, voluptas molestie.
Now add the option -offset indent to the Bl macro. The list then appears between the paragraphs as follows.
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat eu
tellus, voluptas molestie.
- Nunc amet in, tempus ut mauris morbi
- Ac nullam pellentesque in enim
Lorem ipsum dolor sit amet, tellus nullam justo felis feugiat eu
tellus, voluptas molestie.
Miscellany
You can also use mdoc macros to insert custom and standard entries to the mdoc file. For instance, to add a comment, use the \" macro as shown below.
.\" Your comment goes here
This macro prevents the comment from being displayed on the Terminal window.
To display author information, use the An and Aq macros. For example, to add the name Alan Smithee and the e-mail address alan.smithee@mail.box, type the entry as follows.
.An Alan Smithee
.Aq alan.smithee@mail.box
Finally, to display a standard statement on return values, add the entry Rv -std to the document.
Testing The Mdoc File
When you use the man tool to display an mdoc file, the tool searches ten subdirectories for that file. These subdirectories are all located inside the man directory /usr/share/man (Figure 2).
Figure 2. Directory structure of the man help system.
Table 2 is a list of man subdirectories on MacOS X. This table shows that the files in each subdirectory cover a specific help topic. It also shows that those same files use a unique file extension.
Table 2. The man subdirectories on MacOS X
Installation and Testing
Assume, for example, that foobar is a command-line tool available to all users. To install its mdoc file, first set the file name to foobar.1. Then type the following statement at the Terminal prompt.
sudo cp foobar.1 /usr/share/man/man1
The Terminal window then prompts you for an administrative password. Enter the right password to finish the installation.
To test the file, type man foobar at the prompt. The man tool searches each subdirectory for the file foobar.1. Once found, it displays the file's contents on the Terminal window.
Sometimes, the same tool can have multiple mdoc files, each one on a different topic. For instance, assume that foobar.1 covers the basic usage of the tool, whereas foobar.5 covers the file formats created by the tool. To install these files, type the following statements at the prompt.
sudo cp foobar.1 /usr/share/man/man1
sudo cp foobar.5 /usr/share/man/man5
To display the first file, type man foobar at the Terminal prompt. To display the second file, type man 5 foobar at the prompt. Observe that the latter statement includes the section number for that file.
Custom Man Subdirectories
As you may have noticed, access to the /usr/share/man directory is restricted by design. You have to use the sudo command to install or remove mdoc files from that directory. You can, however, install your files in a different and more accessible directory. But you must configure the man tool to include that directory in its search process.
Suppose, for example, you want to store your own mdoc files in /Library/Documentation. First, re-create the man directory structure as shown in Figure 3.
Figure 3. The custom man directory structure
Then use the Finder to install your mdoc files into the right man subdirectory. For example, to install the file foobar.1, select the file from the Finder. Choose Copy from the Edit menu to make a copy of the file. Navigate to the directory /Library/Documentation/man/man1, and choose Paste from the Edit menu to place the copy of foobar.1 onto that directory.
Next, open the .bash_profile file with your favorite text editor. Add the following entry to the end of that file.
MANPATH=$MANPATH:/Library/Documentation/man
export MANPATH
The above tells the man tool to include the custom man directory in its search. Save your changes and restart your Terminal window to allow your changes to take effect.
If you made the above changes correctly, typing man foobar at the Terminal window will display the contents of foobar.1.
Exporting The Mdoc File
Sometimes, you need to export your mdoc file to a different format. Perhaps you want to send the file to another person for editing. Perhaps you plan to post it on the web for reading or downloading by the public. Or perhaps you want to merge it with other files to create an eBook.
You cannot use the man tool as it lacks any export features. Instead, you will use a different command-line tool called groff. With this tool, you can export your mdoc file into one of five possible formats: ASCII, HTML, PostScript, DVI, and PCL5.
Exporting With Groff
Suppose you want to export the file foobar.1. To export it to an ASCII text format, type the following statement at the Terminal prompt.
groff -t -e -mandoc -Tascii foobar.1 | col -bx > foobar.txt
The -t and -e options tell groff to preprocess any table and equation macros in foobar.1.
The mandoc option tells it to use mdoc macros in the export. Finally, the -T option sets the export format, which is ASCII text.
The groff tool then passes the export results to the command line tool col. This tool removes any backspaces added during the export. It also replaces all tab characters with multiple spaces. The tool then saves its output into the file foobar.txt.
To export foobar.1 to an HTML format, change the -T option as follows.
groff -t -e -mandoc -Thtml foobar.1 | col -bx > foobar.html
Note that the rest of the groff options remain the same. Also, note that it again uses the col tool to clean up the exported results before saving it to the file foobar.html.
To export foobar.1 to a PostScript format, change the -T option again as follows.
groff -t -e -mandoc -Tps foobar.1 > foobar.ps
This time, the groff tool does not use col to clean up its export results. Instead, it saves the results directly into the file foobar.ps. And if you open the PostScript file using the Preview application, you can re-save the file in PDF.
Exporting from Xcode
In most cases, you use Xcode to write and install your mdoc file. You can then use an Xcode menu script to export your file to the desired format. Listing 1 is one example of such a script.
First, this script prompts you for an export filename. It offers the default name of untitled.txt. Next, the script checks if you cancelled the export session. If you did not, the script exports the currently displayed mdoc file to the specified ASCII file. It then checks if the export was successful, prompting you with the results.
As you may have noticed, this menu script exports the file as an ASCII text. To use a different export format, simply make a copy of the script, and change the groff -T option to the desired format.
Listing 1. Exporting a mdoc file from Xcode
#! /bin/bash
#
# - PB User Script Info -
# %%%{PBXName=Man To ASCII}%%%
# %%%{PBXInput=None}%%%
# %%%{PBXOutput=SeparateWindow}%%%
# %%%{PBXKeyEquivalent=}%%%
# %%%{PBXArgument=}%%%
# %%%{PBXIncrementalDisplay=YES}%%%
#
# initialise the following shell variables
MAN_SRC=%%%{PBXFilePath}%%%
MAN_MSG="Save the exported file as:"
#prompt the user for a destination directory
MAN_DST=`%%%{PBXUtilityScriptsPath}%%%/AskUserForNewFileDialog ¬
"$MAN_MSG" "untitled.txt"`
# was it successful?
MAN_CHK=`expr "$MAN_DST" : '.*'`
if [ $MAN_CHK -gt 0 ];
then
# export the mdoc file
groff -t -e -mandoc -Tascii $MAN_SRC | col -bx > $MAN_DST
# was it successful?
if [ -f $MAN_DST ];
then
# the export is done
echo "Exported the mdoc file as: $MAN_DST"
else
# the export failed
echo "Failed to export the mdoc file"
fi
fi
Exporting from BBEdit
If you are using BBEdit to write your mdoc file, you have to create a different menu script to export that file. Unlike Xcode, BBEdit uses the AppleScript language for its menu scripts. Listing 2 shows how that menu script might look.
First, the script gets the file path to the active mdoc file. It then prompts you to select one of four possible export formats. Next, the script prompts you for the name and location of the exported file. It also offers the name untitled as the default export name.
Finally, the script prepares the groff shell command based on the selected file format. It then executes the shell command using the library function do shell script.
Listing 2. Exporting a mdoc file from BBEdit
property kFormats : {"ASCII", "UTF8", "HTML", "PostScript"}
on run
local tSrc, tDoc, tFmt, tCmd
- retrieve the path to the current file
tell application "BBEdit 6.5"
get the front document
set tDoc to the result
end tell - application "BBEdit 6.5"
set tSrc to the file of tDoc
set tSrc to the POSIX path of tSrc
- select the export format
choose from list kFormats with title ¬
"Export Formats" with prompt ¬
"Select the export file format" OK button name ¬
"Select" multiple selections allowed false ¬
without empty selection allowed
set tFmt to item 1 of result
- select the export destination
choose file name with prompt ¬
"Save the exported file as:" default name "untitled"
set tDst to result
set tDst to POSIX path of tDst
- prepare the shell command
set tCmd to "groff -t -e -mandoc -T"
- determine the selected export format
if (tFmt is equal to "ASCII") then
- export:format:ASCII
set tCmd to tCmd & "ascii " & tSrc
set tCmd to tCmd & " | col -bx"
set tDst to tDst & ".txt"
else if (tFmt is equal to "UTF8") then
- export:format:UTF8
set tCmd to tCmd & "utf8 " & tSrc
set tCmd to tCmd & " | col -bx"
set tDst to tDst & ".txt"
else if (tFmt is equal to "HTML") then
- export:format:HTML
set tCmd to tCmd & "html " & tSrc
set tCmd to tCmd & " | col -bx"
set tDst to tDst & ".htm"
else if (tFmt is equal to "PostScript") then
- export:format:PostScript
set tCmd to tCmd & "ps " & tSrc
set tDst to tDst & ".ps"
else
- export:format:unknown
set tCmd to ""
end if
if not (tCmd = "") then
- finalise the shell command
set tCmd to tCmd & " > " & tDst
- run the shell command
do shell script tCmd
end if - not(tCmd = "")
end run
Concluding Remarks
Help documents are an essential part of any software product. They must supply the correct information to the user in a clear and coherent form. Software with poorly written help is about as useless as one with none at all.
MacOS X makes it easy for you to create and install an mdoc file for a command-line tool. It allows you to use your favorite text editor to write those files. It also lets you use custom man subdirectories to store the files. It even gives you the means to write scripts to export the mdoc files to a different format.
So the next time you have your groundbreaking software ready, take the extra time to write some user-friendly help.
Bibliography and References
Gerfen, Bodhi. Darwin man page HOWTO. 2001 Jun 08. Copyright 2001. Apple Computers, Inc. Online: http://docs.huihoo.com/darwin/opendarwin/articles/man_page_howto/index.html
Kollar, Larry. Writing Effective Manual Pages. Copyright 2004. Larry Kollar. Online: http://home.alltel.net/kollar/groff/effman.html.
Schweikhardt, Jens. Linux Man Page HOWTO. Copyright 1995-2001. Jens Schweikhardt. Online: http://www.faqs.org/docs/Linux-mini/Man-Page.html.
JC is a freelance engineering writer who lives happily in North Vancouver, British Columbia. He divides his time between writing technical articles, and teaching origami at his district's public library. He can be reached at anarakisware@gmail.com.
