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.

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.

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.

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 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 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.

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.

Generate Function Pages

Generates function pages in a selected directory.

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.

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.

Generate Overview

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

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.

Extract Tutorials

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