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
$112.24
Apple Inc.
-0.41
MSFT
$47.84
Microsoft Corpora
+0.32
GOOG
$509.27
Google Inc.
-1.83

MacTech Search:
Community Search:

Software Updates via MacUpdate

calibre 2.13 - Complete e-library manage...
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 librarian... Read more
Mellel 3.3.7 - Powerful word processor w...
Mellel is the leading word processor for OS X and has been widely considered the industry standard since its inception. Mellel focuses on writers and scholars for technical writing and multilingual... Read more
ScreenFlow 5.0.1 - Create screen recordi...
Save 10% with the exclusive MacUpdate coupon code: AFMacUpdate10 Buy now! ScreenFlow is powerful, easy-to-use screencasting software for the Mac. With ScreenFlow you can record the contents of your... Read more
Simon 4.0 - Monitor changes and crashes...
Simon monitors websites and alerts you of crashes and changes. Select pages to monitor, choose your alert options, and customize your settings. Simon does the rest. Keep a watchful eye on your... Read more
BBEdit 11.0.2 - Powerful text and HTML e...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
ExpanDrive 4.2.1 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
Adobe After Effects CC 2014 13.2 - Creat...
After Effects CC 2014 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous After Effects customer). After Effects CS6 is still available... Read more
Evernote 6.0.5 - Create searchable notes...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
Command-C 1.1.7 - Clipboard sharing tool...
Command-C is a revolutionary app which makes easy to share your clipboard between iOS and OS X using your local WiFi network, even if the app is not currently opened. Copy anything (text, pictures,... Read more
Tidy Up 4.0.2 - Find duplicate files and...
Tidy Up is a complete duplicate finder and disk-tidiness utility. With Tidy Up you can search for duplicate files and packages by the owner application, content, type, creator, extension, time... Read more

Latest Forum Discussions

See All

BulkyPix Celebrates its 6th Anniversary...
BulkyPix Celebrates its 6th Anniversary with a Bunch of Free Games Posted by Jessica Fisher on December 19th, 2014 [ permalink ] BulkyPix has | Read more »
Indulge in Japanese cuisine in Cooking F...
Indulge in Japanese cuisine in Cooking Fever’s new sushi-themed update Posted by Simon Reed on December 19th, 2014 [ permalink ] Lithuanian developer Nordcurrent has yet again updated its restaurant simulat | Read more »
Badland Daydream Level Pack Arrives to C...
Badland Daydream Level Pack Arrives to Celebrate 20 Million Downloads Posted by Ellis Spice on December 19th, 2014 [ permalink ] | Read more »
Far Cry 4, Assassin’s Creed Unity, Desti...
Far Cry 4, Assassin’s Creed Unity, Destiny, and Beyond – AppSpy Takes a Look at AAA Companion Apps Posted by Rob Rich on December 19th, 2014 [ permalink ] These day | Read more »
A Bunch of Halfbrick Games Are Going Fre...
A Bunch of Halfbrick Games Are Going Free for the Holidays Posted by Ellis Spice on December 19th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Shift - Photo Filters Designed By You (...
Shift - Photo Filters Designed By You 1.0 Device: iOS Universal Category: Photography Price: $.99, Version: 1.0 (iTunes) Description: | Read more »
Elastic Drums (Music)
Elastic Drums 1.0 Device: iOS iPhone Category: Music Price: $3.99, Version: 1.0 (iTunes) Description: *** Introduction price 3,99$ instead of 7,99$ *** Elastic Drums is a music app with 6 channels of synthesized drum sounds, a step... | Read more »
Fireworks Simulator (Games)
Fireworks Simulator 1.0.8 Device: iOS Universal Category: Games Price: $.99, Version: 1.0.8 (iTunes) Description: *** 50% discount – For a short time only *** You can play Fireworks Simulator on these devices: - iPhone 5, 5s, 5c, 6,... | Read more »
Nicky's Gift (Games)
Nicky's Gift 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Everybody! Merry Christmas! There's 48 levels in the game. Let's go! Nicky's Gift | Read more »
The Hit List — Simply Powerful Tasks, To...
The Hit List — Simply Powerful Tasks, To-Dos, Projects, & Reminders 2.0 Device: iOS iPhone Category: Productivity Price: $9.99, Version: 2.0 (iTunes) Description: >> LAUNCH SPECIAL: The Hit List 2 for iPhone is ONLY $9.99... | Read more »

Price Scanner via MacPrices.net

It’s 1992 Again At Sony Pictures, Except For...
Techcrunch’s John Biggs interviewed a Sony Pictures Entertainment (SPE) employee, who quite understandably wished to remain anonymous, regarding post-hack conditions in SPE’s L.A office, explaining “... Read more
Holiday sales this weekend: MacBook Pros for...
 B&H Photo has new MacBook Pros on sale for up to $300 off MSRP as part of their Holiday pricing. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1699... Read more
Holiday sales this weekend: MacBook Airs for...
B&H Photo has 2014 MacBook Airs on sale for up to $120 off MSRP, for a limited time, for the Thanksgiving/Christmas Holiday shopping season. Shipping is free, and B&H charges NY sales tax... Read more
Holiday sales this weekend: iMacs for up to $...
B&H Photo has 21″ and 27″ iMacs on sale for up to $200 off MSRP including free shipping plus NY sales tax only. B&H will also include a free copy of Parallels Desktop software: - 21″ 1.4GHz... Read more
Holiday sales this weekend: Mac minis availab...
B&H Photo has new 2014 Mac minis on sale for up to $80 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 1.4GHz Mac mini: $459 $40 off MSRP - 2.6GHz Mac mini: $629 $70 off MSRP... Read more
Holiday sales this weekend: Mac Pros for up t...
B&H Photo has Mac Pros on sale for up to $500 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2599, $400 off MSRP - 3.5GHz 6-core Mac Pro: $3499, $... Read more
Save up to $400 on MacBooks with Apple Certif...
The Apple Store has Apple Certified Refurbished 2014 MacBook Pros and MacBook Airs available for up to $400 off the cost of new models. An Apple one-year warranty is included with each model, and... Read more
Save up to $300 on Macs, $30 on iPads with Ap...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
iOS and Android OS Targeted by Man-in-the-Mid...
Cloud services security provider Akamai Technologies, Inc. has released, through the company’s Prolexic Security Engineering & Research Team (PLXsert), a new cybersecurity threat advisory. The... Read more
KMI MIDI K-Board Great Gift for Amateur &...
The K-Board is a MIDI Nano keyboard for music creation for iPad, Android, And computers; the easiest way to make music with iPads & Android tablets, and Mac, Windows, or Linux computers. Ultra-... Read more

Jobs Board

Project Manager, *Apple* Financial Services...
**Job Summary** Apple Financial Services (AFS) offers consumers, businesses and educational institutions ways to finance Apple purchases. We work with national and 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
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, 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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.