TweetFollow Us on Twitter

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.

 
AAPL
$94.72
Apple Inc.
+0.78
MSFT
$44.83
Microsoft Corpora
-0.01
GOOG
$594.74
Google Inc.
+5.27

MacTech Search:
Community Search:

Software Updates via MacUpdate

Airmail 1.4 - Powerful, minimal email cl...
Airmail is a powerful, minimal mail client.It was designed to retain the same experience with a single or multiple accounts and provide a quick, modern and easy-to-use user experience. Airmail... Read more
Macs Fan Control 1.1.12 - Monitor and co...
Macs Fan Control allows you to monitor and control almost any aspect of your computer's fans, with support for controlling fan speed, temperature sensors pane, menu-bar icon, and autostart with... Read more
A Better Finder Rename 9.37 - File, phot...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
MacBook Air EFI Firmware Update 2.9 - Fo...
MacBook Air EFI Firmware Update is recommended for MacBook Air (Mid 2011) models. This update addresses an issue where systems may take longer to wake from sleep than expected and fixes a rare issue... Read more
FileZilla 3.9.0.1 - Fast and reliable FT...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface.Version 3.9.0.1: MSW: Fix installation issue with locked DLLs... Read more
OS X Yosemite 10.10 DP4 - Developer Prev...
Note: This is a Developer Preview. You must be a registered Apple Mac Developer to download this update. OS X Yosemite is Apple's newest operating system for Mac. An elegant design that feels... Read more
FinderPop 2.5.6 - Classic Mac utility, n...
FinderPop is a Universal preference pane that extends OS X's contextual menus using a FinderPop Items folder much as the Apple Menu Items folder used to do for the Apple menu. It has other features... Read more
SpiderOak 5.1.7 - Secure cloud backup, s...
SpiderOak is a multi-platform secure online backup, storage, access, and sharing solution engineered for the consumer and small businesses. You must first sign up to use SpiderOak. Running natively... Read more
Espionage 3.6 - Simple, state of the art...
Espionage offers state-of-the-art encryption and plausible deniability for your confidential data. Sometimes, encrypting your data isn't enough to protect it. That's why Espionage 3 goes beyond data... Read more
calibre 1.45.0 - Complete e-library mana...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital... Read more

Latest Forum Discussions

See All

Celebrate Summer With a Cat in the Hat L...
Celebrate Summer With a Cat in the Hat Learning Library Sale Posted by Ellis Spice on July 22nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
MyTaskList Review
MyTaskList Review By Jennifer Allen on July 22nd, 2014 Our Rating: :: EFFECTIVE IF PLAINUniversal App - Designed for iPhone and iPad It’s not the most stylish of task management apps, but MyTaskList has all the features you could... | Read more »
FlyCraft Herbie: Crazy Machines Review
FlyCraft Herbie: Crazy Machines Review By Jennifer Allen on July 22nd, 2014 Our Rating: :: TRICKY FLYINGUniversal App - Designed for iPhone and iPad A tough game of careful thrusting and navigation, FlyCraft Herbie: Crazy Machines... | Read more »
MTN Review
MTN Review By Jessica Fisher on July 22nd, 2014 Our Rating: :: ADORABLE, SERENE, AND AMUSINGUniversal App - Designed for iPhone and iPad MTN is an adorable, talking pet mountain that is less game and more zen garden.   | Read more »
Fly High with Ninja UP! Now Available o...
Fly High with Ninja UP! Now Available on the App Store Posted by Jessica Fisher on July 22nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Bio Inc. Review
Bio Inc. Review By Nadia Oxford on July 22nd, 2014 Our Rating: :: SICKENING - IN A COMPELLING WAYUniversal App - Designed for iPhone and iPad Bio Inc is about orchestrating the medical destruction of a single person. If that doesn’... | Read more »
HELMUT Review
HELMUT Review By Andrew Fisher on July 21st, 2014 Our Rating: :: TRUNDLE SIMULATOR 2014Universal App - Designed for iPhone and iPad HELMUT is a fun, fleeting time-sink that offers a momentary distraction and nothing else.   | Read more »
Walkr Review
Walkr Review By Jennifer Allen on July 21st, 2014 Our Rating: :: ORIGINAL WALKINGiPhone App - Designed for the iPhone, compatible with the iPad Walking is a bit more exciting thanks to this planet building/discovering sim reliant... | Read more »
Zombie Commando Review
Zombie Commando Review By Jennifer Allen on July 21st, 2014 Our Rating: :: MINDLESS SLAUGHTERUniversal App - Designed for iPhone and iPad Briefly fun but ultimately forgettable, Zombie Commando will scratch an itch then be... | Read more »
Swords & Poker Adventures Review
Swords & Poker Adventures Review By Jennifer Allen on July 21st, 2014 Our Rating: :: SOULLESS POKER PLAYUniversal App - Designed for iPhone and iPad Swords & Poker Adventures is a mishmash of Poker and RPGing, but it lacks... | Read more »

Price Scanner via MacPrices.net

WaterField Designs Unveils Cycling Ride Pouch...
High end computer case and bag maker WaterField Designs of San Francisco now enters the cycling market with the introduction of the Cycling Ride Pouch – an upscale toolkit with a scratch-free iPhone... Read more
Kingston Digital Ships Large Capacity Near 1T...
Kingston Digital, Inc., the Flash memory affiliate of Kingston Technology Company, Inc.,has announced its latest addition to the SSDNow V300 series, the V310. The Kingston SSDNow V310 solid-state... Read more
15-inch 2.0GHz MacBook Pro Retina on sale for...
B&H Photo has the 15″ 2.0GHz Retina MacBook Pro on sale for $1829 including free shipping plus NY sales tax only. Their price is $170 off MSRP. B&H will also include free copies of Parallels... Read more
Apple restocks refurbished Mac minis for up t...
The Apple Store has restocked Apple Certified Refurbished Mac minis for up to $150 off the cost of new models. Apple’s one-year warranty is included with each mini, and shipping is free: - 2.5GHz Mac... Read more
Twelve South HiRise For MacBook – Height-Adju...
If you use your MacBook as a workhorse desktop substitute, as many of us do, a laptop stand combined with an external keyboard and pointing device are pretty much obligatory if you want to avoid... Read more
Why The Mac Was Not Included In The Apple/IBM...
TUAW’s Yoni Heisler cites Fredrick Paul of Network World whoi blogged last week that the Mac’s conspicuous absence from Apple and IBM’s landmark partnership agreement represents a huge squandered... Read more
Save $100 on 13-inch Retina MacBook Pros, plu...
Adorama has 13″ Retina MacBook Pros on sale for $100 off MSRP. Shipping is free, and Adorama charges sales tax in NY & NJ only: - 13″ 2.4GHz/128GB MacBook Pro with Retina Display: $1199 - 13″ 2.... Read more
Blurr it 2.3 for iOS – Quickly Blurs Selected...
Hyderabad, India based TouchLabs has announced a new update of Blurr it 2.3, their photography app for iOS users. Blurr it allows you to blur part of the image to hide potentially sensitive or... Read more
MacBook Airs on sale for $100 off MSRP, start...
Best Buy has the new 2014 MacBook Airs on sale for up to $100 off MSRP on their online store. Choose free home shipping or free local store pickup (if available). Prices valid for online orders only... Read more
Amazon Announces Kindle Unlimited: Unlimited...
Amazon.com has introduced Kindle Unlimited — a new subscription service which allows customers to freely read as much as they want from over 600,000 Kindle books, and listen as much as they want to... Read more

Jobs Board

Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Sr *Apple* Engineer - IT - Requisition #: -...
For more information about TIAA-CREF, visit our website . The Apple Engineer will provide engineering and third-level incident support for 300- 500 MacOS desktop/laptop Read more
*Apple* Systems Administrator - DISH (United...
…satellite service provider, and Dish is currently looking for an experienced Apple /Mac Systems Administrator. Apple systems administrator will be responsible for Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.