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

Latest Forum Discussions

See All

Whitethorn Games combines two completely...
If you have ever gone fishing then you know that it is a lesson in patience, sitting around waiting for a bite that may never come. Well, that's because you have been doing it wrong, since as Whitehorn Games now demonstrates in new release Skate... | Read more »
Call of Duty Warzone is a Waiting Simula...
It's always fun when a splashy multiplayer game comes to mobile because they are few and far between, so I was excited to see the notification about Call of Duty: Warzone Mobile (finally) launching last week and wanted to try it out. As someone who... | Read more »
Albion Online introduces some massive ne...
Sandbox Interactive has announced an upcoming update to its flagship MMORPG Albion Online, containing massive updates to its existing guild Vs guild systems. Someone clearly rewatched the Helms Deep battle in Lord of the Rings and spent the next... | Read more »
Chucklefish announces launch date of the...
Chucklefish, the indie London-based team we probably all know from developing Terraria or their stint publishing Stardew Valley, has revealed the mobile release date for roguelike deck-builder Wildfrost. Developed by Gaziter and Deadpan Games, the... | Read more »
Netmarble opens pre-registration for act...
It has been close to three years since Netmarble announced they would be adapting the smash series Solo Leveling into a video game, and at last, they have announced the opening of pre-orders for Solo Leveling: Arise. [Read more] | Read more »
PUBG Mobile celebrates sixth anniversary...
For the past six years, PUBG Mobile has been one of the most popular shooters you can play in the palm of your hand, and Krafton is celebrating this milestone and many years of ups by teaming up with hit music man JVKE to create a special song for... | Read more »
ASTRA: Knights of Veda refuse to pump th...
In perhaps the most recent example of being incredibly eager, ASTRA: Knights of Veda has dropped its second collaboration with South Korean boyband Seventeen, named so as it consists of exactly thirteen members and a video collaboration with Lee... | Read more »
Collect all your cats and caterpillars a...
If you are growing tired of trying to build a town with your phone by using it as a tiny, ineffectual shover then fear no longer, as Independent Arts Software has announced the upcoming release of Construction Simulator 4, from the critically... | Read more »
Backbone complete its lineup of 2nd Gene...
With all the ports of big AAA games that have been coming to mobile, it is becoming more convenient than ever to own a good controller, and to help with this Backbone has announced the completion of their 2nd generation product lineup with their... | Read more »
Zenless Zone Zero opens entries for its...
miHoYo, aka HoYoverse, has become such a big name in mobile gaming that it's hard to believe that arguably their flagship title, Genshin Impact, is only three and a half years old. Now, they continue the road to the next title in their world, with... | Read more »

Price Scanner via MacPrices.net

B&H has Apple’s 13-inch M2 MacBook Airs o...
B&H Photo has 13″ MacBook Airs with M2 CPUs and 256GB of storage in stock and on sale for up to $150 off Apple’s new MSRP, starting at only $849. Free 1-2 day delivery is available to most US... Read more
M2 Mac minis on sale for $100-$200 off MSRP,...
B&H Photo has Apple’s M2-powered Mac minis back in stock and on sale today for $100-$200 off MSRP. Free 1-2 day shipping is available for most US addresses: – Mac mini M2/256GB SSD: $499, save $... Read more
Mac Studios with M2 Max and M2 Ultra CPUs on...
B&H Photo has standard-configuration Mac Studios with Apple’s M2 Max & Ultra CPUs in stock today and on Easter sale for $200 off MSRP. Their prices are the lowest available for these models... Read more
Deal Alert! B&H Photo has Apple’s 14-inch...
B&H Photo has new Gray and Black 14″ M3, M3 Pro, and M3 Max MacBook Pros on sale for $200-$300 off MSRP, starting at only $1399. B&H offers free 1-2 day delivery to most US addresses: – 14″ 8... Read more
Department Of Justice Sets Sights On Apple In...
NEWS – The ball has finally dropped on the big Apple. The ball (metaphorically speaking) — an antitrust lawsuit filed in the U.S. on March 21 by the Department of Justice (DOJ) — came down following... Read more
New 13-inch M3 MacBook Air on sale for $999,...
Amazon has Apple’s new 13″ M3 MacBook Air on sale for $100 off MSRP for the first time, now just $999 shipped. Shipping is free: – 13″ MacBook Air (8GB RAM/256GB SSD/Space Gray): $999 $100 off MSRP... Read more
Amazon has Apple’s 9th-generation WiFi iPads...
Amazon has Apple’s 9th generation 10.2″ WiFi iPads on sale for $80-$100 off MSRP, starting only $249. Their prices are the lowest available for new iPads anywhere: – 10″ 64GB WiFi iPad (Space Gray or... Read more
Discounted 14-inch M3 MacBook Pros with 16GB...
Apple retailer Expercom has 14″ MacBook Pros with M3 CPUs and 16GB of standard memory discounted by up to $120 off Apple’s MSRP: – 14″ M3 MacBook Pro (16GB RAM/256GB SSD): $1691.06 $108 off MSRP – 14... Read more
Clearance 15-inch M2 MacBook Airs on sale for...
B&H Photo has Apple’s 15″ MacBook Airs with M2 CPUs (8GB RAM/256GB SSD) in stock today and on clearance sale for $999 in all four colors. Free 1-2 delivery is available to most US addresses.... Read more
Clearance 13-inch M1 MacBook Airs drop to onl...
B&H has Apple’s base 13″ M1 MacBook Air (Space Gray, Silver, & Gold) in stock and on clearance sale today for $300 off MSRP, only $699. Free 1-2 day shipping is available to most addresses in... Read more

Jobs Board

Medical Assistant - Surgical Oncology- *Apple...
Medical Assistant - Surgical Oncology- Apple Hill Location: WellSpan Medical Group, York, PA Schedule: Full Time Sign-On Bonus Eligible Remote/Hybrid Regular Apply Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Business Analyst | *Apple* Pay - Banco Popu...
Business Analyst | Apple PayApply now " Apply now + Apply Now + Start applying with LinkedIn Start + Please wait Date:Mar 19, 2024 Location: San Juan-Cupey, PR Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.