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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

BetterTouchTool 2.332 - Customize multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
Capture One 11.0.1.40 - RAW workflow sof...
Capture One is a professional RAW converter offering you ultimate image quality with accurate colors and incredible detail from more than 400 high-end cameras -- straight out of the box. It offers... Read more
Capture One 11.0.1.40 - RAW workflow sof...
Capture One is a professional RAW converter offering you ultimate image quality with accurate colors and incredible detail from more than 400 high-end cameras -- straight out of the box. It offers... Read more
GraphicConverter 10.5.4 - $39.95
GraphicConverter is an all-purpose image-editing program that can import 200 different graphic-based formats, edit the image, and export it to any of 80 available file formats. The high-end editing... Read more
Dash 4.1.3 - Instant search and offline...
Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
Microsoft OneNote 16.9 - Free digital no...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that's too important to forget. Whether you're at... Read more
DEVONthink Pro 2.9.17 - Knowledge base,...
Save 10% with our exclusive coupon code: MACUPDATE10 DEVONthink Pro is your essential assistant for today's world, where almost everything is digital. From shopping receipts to important research... Read more
OmniGraffle 7.6 - Create diagrams, flow...
OmniGraffle helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use Graffle to... Read more
iFinance 4.3.7 - Comprehensively manage...
iFinance allows you to keep track of your income and spending -- from your lunchbreak coffee to your new car -- in the most convenient and fastest way. Clearly arranged transaction lists of all your... Read more
Opera 50.0.2762.58 - High-performance We...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more

Latest Forum Discussions

See All

Around the Empire: What have you missed...
Around this time every week we're going to have a look at the comings and goings on the other sites in Steel Media's pocket-gaming empire. We'll round up the very best content you might have missed, so you're always going to be up to date with the... | Read more »
Everything about Hero Academy 2: Part 4...
In this part of our Hero Academy 2 guide, we're going to have a look at some of the tactics you're going to need to learn if you want to rise up the ranks. We're going to start off slow, then get more advanced in the next section. [Read more] | Read more »
All the best games on sale for iPhone an...
Another week has flown by. Sometimes it feels like the only truly unstoppable thing is time. Time will make dust of us all. But before it does, we should probably play as many awesome mobile videogames as we can. Am I right, or am I right? [Read... | Read more »
The 7 best games that came out for iPhon...
Well, it's that time of the week. You know what I mean. You know exactly what I mean. It's the time of the week when we take a look at the best games that have landed on the App Store over the past seven days. And there are some real doozies here... | Read more »
Popular MMO Strategy game Lords Mobile i...
Delve into the crowded halls of the Play Store and you’ll find mobile fantasy strategy MMOs-a-plenty. One that’s kicking off the new year in style however is IGG’s Lords Mobile, which has beaten out the fierce competition to receive Google Play’s... | Read more »
Blocky Racing is a funky and fresh new k...
Blocky Racing has zoomed onto the App Store and Google Play this week, bringing with it plenty of classic kart racing shenanigans that will take you straight back to your childhood. If you’ve found yourself hooked on games like Mario Kart or Crash... | Read more »
Cytus II (Games)
Cytus II 1.0.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.1 (iTunes) Description: "Cytus II" is a music rhythm game created by Rayark Games. It's our fourth rhythm game title, following the footsteps of three... | Read more »
JYDGE (Games)
JYDGE 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: Build your JYDGE. Enter Edenbyrg. Get out alive. JYDGE is a lawful but awful roguehate top-down shooter where you get to build your... | Read more »
Tako Bubble guide - Tips and Tricks to S...
Tako Bubble is a pretty simple and fun puzzler, but the game can get downright devious with its puzzle design. If you insist on not paying for the game and want to manage your lives appropriately, check out these tips so you can avoid getting... | Read more »
Everything about Hero Academy 2 - The co...
It's fair to say we've spent a good deal of time on Hero Academy 2. So much so, that we think we're probably in a really good place to give you some advice about how to get the most out of the game. And in this guide, that's exactly what you're... | Read more »

Price Scanner via MacPrices.net

Deals on clearance 15″ Apple MacBook Pros wit...
B&H Photo has clearance 2016 15″ MacBook Pros available for up to $800 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: – 15″ 2.7GHz Touch Bar MacBook Pro... Read more
Apple restocked Certified Refurbished 13″ Mac...
Apple has restocked a full line of Certified Refurbished 2017 13″ MacBook Airs starting at $849. An Apple one-year warranty is included with each MacBook, and shipping is free: – 13″ 1.8GHz/8GB/128GB... Read more
How to find the lowest prices on 2017 Apple M...
Apple has Certified Refurbished 13″ and 15″ 2017 MacBook Pros available for $200 to $420 off the cost of new models. Apple’s refurbished prices are the lowest available for each model from any... Read more
The lowest prices anywhere on Apple 12″ MacBo...
Apple has Certified Refurbished 2017 12″ Retina MacBooks available for $200-$240 off the cost of new models. Apple will include a standard one-year warranty with each MacBook, and shipping is free.... Read more
Apple now offering a full line of Certified R...
Apple is now offering Certified Refurbished 2017 10″ and 12″ iPad Pros for $100-$190 off MSRP, depending on the model. An Apple one-year warranty is included with each model, and shipping is free: –... Read more
27″ iMacs on sale for $100-$130 off MSRP, pay...
B&H Photo has 27″ iMacs on sale for $100-$130 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 27″ 3.8GHz iMac (MNED2LL/A): $2199 $100 off MSRP – 27″ 3.... Read more
2.8GHz Mac mini on sale for $899, $100 off MS...
B&H Photo has the 2.8GHz Mac mini (model number MGEQ2LL/A) on sale for $899 including free shipping plus NY & NJ sales tax only. Their price is $100 off MSRP. Read more
Apple offers Certified Refurbished iPad minis...
Apple has Certified Refurbished 128GB iPad minis available today for $339 including free shipping. Apple’s standard one-year warranty is included. Their price is $60 off MSRP. Read more
Amazon offers 13″ 256GB MacBook Air for $1049...
Amazon has the 13″ 1.8GHz/256B #Apple #MacBook Air on sale today for $150 off MSRP including free shipping: – 13″ 1.8GHz/256GB MacBook Air (MQD42LL/A): $1049.99, $150 off MSRP Read more
9.7-inch 2017 WiFi iPads on sale starting at...
B&H Photo has 9.7″ 2017 WiFi #Apple #iPads on sale for $30 off MSRP for a limited time. Shipping is free, and pay sales tax in NY & NJ only: – 32GB iPad WiFi: $299, $30 off – 128GB iPad WiFi... Read more

Jobs Board

AppleCare Support Engineer for *Apple* Medi...
# AppleCare Support Engineer for Apple Media Products Job Number: 113222855 Santa Clara Valley, California, United States Posted: 14-Nov-2017 Weekly Hours: 40.00 Read more
QA Automation Engineer, *Apple* Pay - Apple...
# QA Automation Engineer, Apple Pay Job Number: 113202642 Santa Clara Valley, California, United States Posted: 11-Dec-2017 Weekly Hours: 40.00 **Job Summary** At Read more
*Apple* Video Partnerships - Apple (United S...
# Apple Video Partnerships Job Number: 113059126 Santa Clara Valley, California, United States Posted: 15-Nov-2017 Weekly Hours: 40.00 **Job Summary** Partnerships Read more
Sr. Engineering Manager- *Apple* Media Produ...
# Sr. Engineering Manager- Apple Media Products Job Number: 113335268 Santa Clara Valley, California, United States Posted: 17-Jan-2018 Weekly Hours: 40.00 **Job Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.