DocumentationTools Palette Quick Start

DocumentationTools is a package of tools for writing Mathematica documentation within the scheme introduced in the Documentation Center for Mathematica 6. DocumentationTools consists of package code, a palette, stylesheets, template files, and some menu additions.
Once the package is loaded in the appropriate directory and Mathematica is restarted, a palette listed as DocumentationTools appears in the Palettes menu. It may take a few seconds to open, particularly during startup, because of a few dynamic elements within the palette which require a kernel connection.
The DocumentationTools palette consists of a number of subpalettes, which are accessed using the single letter tab buttons across the top. If the palette appears too long for the screen, click on the top right button to activate the vertical scroll bar. The large black button near the top indicates the name of the palette tab, and also initiates a new document with the appropriate template and style sheet.
Within a particular tab (or page) of the DocumentationTools palette are numerous buttons and groups of hidden buttons. The hidden buttons are exposed by clicking on their grouping button, indicated with an alternate color and a down-pointing arrow.
All buttons are documented in the palette with tooltips, but the most important buttons are also described in the listing that follows. In order for some of the buttons and all links to work correctly, it is important to set a working directory for the documentation. For convenience, the Set Paclet Name & Path button opens a file browser for selecting your working directory, and that selection is stored in preferences so that it need only be configured once. Workbench sets the paclet name automatically from project to project, so this button can be ignored while using DocumentationTools within Workbench.

Function Page Buttons:

Main Button Group Buttons

New Function Page
Initiates a new function page using a template file from the DocumentationTools package layout.
Sample Function Page
Opens an annotated function page sample.
Set Paclet Name & Path
Opens a file browser for selecting the working directory of the documentation source files. This configuration is stored in preferences and need not be reapplied until the preferences are discarded. The small black button at its right (all buttons of this type are henceforth referred to as "notch" buttons) enables the setting of $ApplicationName and $Linkbase via a dialog.
Double Usage Line
Creates a new entry in the "Usage" cell. Apply this at the end of the usage text the new entry should follow.
Template Input
This is the single most important button on the palette, and is also available as a keyboard shortcut (refer to the top of the Format menu). Type a function head with brackets and sample arguments, all as one word. When typing is complete, activate this function and the function example will be formatted into a usage template. When formatting is complete, the cursor returns to a position allowing typing to continue. Refer to the tooltip for syntax conventions.
Inline Listing Toggle
Formats and unformats (for editing) the contents of a See Also listing, or any other inline listing formatted with bullet-like word separators. Refer to the tooltip for syntax conventions.

Notes

Note
Inserts a "Notes" cell when the cursor is between cells. Applies the "Notes" style when the cursor is at the cell bracket. It is intended that notes only be inserted below the usage cell and above the Tutorials section.
Options Table
A dialog allows choosing of a function's options with specified default values and comments about functionality to be inserted into the notes area.
1 Col / 2 Col / 3 Col
Inserts notes table of the specified number of columns. A 3-column table is typically for documenting options. Text variants insert tables with "TableText" in all columns.
Insert Custom Table
A dialog allows the choosing of the number of rows, 2 or 3 columns and Text format or not in a table to be inserted.
Switch Format
Changes selected table element from normal input to "TableText", or vice versa. When entering mixed format content into a table element in the first column (or both first and second columns in 3-column tables), first click Switch Format, then click Template Input within the "TableText" cell for input (computer voice).
Sort Table
Sorts a table on elements of the first column.
Merge Table
Merges tables having the same number of columns.

Examples

Insert Delimiter
Delimiters are used to separate example clusters, and reset all variables using a private context.
Insert Needs
Inserts a Needs input expression corresponding to an application.
Options for Function
Allows insertion of options missing from the Options section.

Link Buttons

Link to Guide, Tutorial, or Symbol
Applies the appropriate link style and button data URI using the contents of the selection as the target. Use the notch button to browse for a specific file if the file name cannot be derived from the selected contents.
Link to URL
Opens a dialog for setting the URL of the link to be applied to the selection. The dialog allows you to select link text variations.
Edit Link
Selects the button/hyperlink directly to the left of the selection and opens a dialog allowing editing of the button contents. This is needed in cases of hyperlinks within BoxData, which cannot be edited inline, unlike hyperlinks in TextData.

Link Subgroup Buttons

Link to Selection
Copies a link to the selected cell on to the clipboard. This will work equally well across notebooks as within a notebook. Links use CellID for targeting, so cell tags are not being added. Paste the link where desired, and edit the button contents (text of link) directly or use the Edit Link button in the palette.
Link to Document
Opens a dialog to browse for the target file for the link being made of the selection. Links to documents use paclet URIs derived from the target path. Supports linking to notebooks and PDF files.
Link with Custom URI
Opens a dialog to enter the paclet URI to be applied to the link for the selection. Use this when targeting documents outside the canonical documentation tree. The "S" notch button allows you to enter a paclet URI to use by default for your session. This also sets $TargetDocumentDir, making browsing for target documents convenient, but it can also be set independently. The "B" notch button is for browsing for the directory to set as the paclet URI and target document directory.

Formatting

Default Format
Restores the normal format for text in the cell after hyperlinks or other formatted text. This also removes formatting from any selected text.
Literal Input
For Mathematica input in text.
Undeploy
If the checkbox is checked, the input notebook will pass through the build process untouched.
Tentative
Marks a cell so as not to include it in the build process.
Annotate
Enables annotating a cell via a dialog. Annotations are not included in the build process.

Utilities

Generate Function Pages
Generates function pages in a selected directory.

Guide Page Buttons:

Main Button Group Buttons

Sample Guide Page
Opens an annotated guide page sample.
New Guide Page
Initiates a new guide page using a template file from the DocumentationTools package layout.
Set Paclet Name & Path
Opens a file browser for selecting the working directory of the documentation source files. This configuration is stored in preferences and need not be reapplied until the preferences are discarded.
1 Line Function Listing
Inserts a single cell function listing consisting of the function name followed by the descriptive text in the same cell.
Delimiter
Inserts a delimiter between groups of listed functions.
Functions Inline Listing
Inserts and formats/unformats (for editing) the contents of a single-cell listing of multiple function names separated by bullets. Refer to the tooltip for syntax conventions.
Insert Artwork Banner
Inserts a placeholder for product branding artwork. This will only appear on the root guide and should only be applied to the root guide page.

Tutorial Page Buttons:

Main Button Group Buttons

Sample Tutorial Page
Opens an annotated tutorial page sample.
New Tutorial Page
Initiates a new tutorial page using a template file from the DocumentationTools package layout.
Set Paclet Name & Path
Opens a file browser for selecting the working directory of the documentation source files. This configuration is stored in preferences and need not be reapplied until the preferences are discarded.
Definition Box
Inserts a definition box template. Notch buttons provide features for additional rows, merging multiple boxes, deleting entries, and switching definition box item selection between normal and spanning orientation.
Math Caption
Inserts templates for math caption, or math caption and input cell.
Section, Subsection, Text
Inserts templates for or changes selection to each style.

Overview Tools

Generate Overview
Chooses a list of tutorials from which to construct an overview.

TOC Link Tools

Browse
Chooses a tutorial.
Select Cell
Selects a particular heading.
Paste
Links the selected cell in the overview being constructed to the chosen tutorial cell.

Utilities

Extract Tutorials
Generates tutorials from a collection of existing documentation files. The notch button does the same thing from the input notebook.