Authoring Tutorial Pages Using DocumentationTools
A tutorial page focuses on a particular piece of functionality and includes examples, tables with links and short descriptions of useful functions, and mathematical textbook-like information. Sections are provided to link to other related documents.
The material below assumes that you have already set up an appropriate directory structure for saving and working with documentation using the DocumentationTools package. If you are working from Workbench it will already have been done. Otherwise with "MyApplication" representing the name of your application, create the directory structure MyApplication > Documentation > English and the directories Guides, ReferencePages, and Tutorials inside the English directory. Then create the directory Symbols within the ReferencePages directory.
Setting Up DocumentationTools
1. Choose Palettes ► DocumentationTools from the Mathematica menu bar. A gray palette will appear on the right side of the screen. Select the T tab at the top of the palette for tutorial page authoring tools.
2. If you are not starting Mathematica from a project within Workbench, you will need to configure DocumentationTools. Click Set PacletName & Path near the palette's top and navigate to the English directory of your application. This will activate the links in the authoring notebooks for testing purposes.
Note: If the palette appears nonfunctional, open the Option Inspector (Format ► Option Inspector) and check that DynamicUpdating->Automatic in the Global Preferences.
Authoring
1. Clicking New Tutorial brings up a dialog requesting that the title of the new tutorial be specified.
2. Once that is done, clicking OK will construct a new tutorial page with the title and metadata already filled in. In addition, the tutorial page will be saved in the project's tutorial directory. The dialog that comes up is informational and may be permanently dismissed if so desired.
Note: The authoring notebooks contain a series of placeholders that will not be included with the build unless you explicitly edit them. These placeholders will typically contain four X's.
Note: A sample tutorial page can be found by clicking Sample Tutorial Page near the top of the DocumentationTools palette.
4. Enter the functions into the table so that the function template is in the left column and a short description is in the right. Using the same procedure from "Authoring Symbol Pages Using DocumentationTools", use Template Input to format the template and function inputs.
5. You can add more rows to the definition box by placing the cursor at the end of the row and clicking the A button next to Definition Box on the DocumentationTools palette.
Note: Include only a few examples on the most important concepts mentioned in the tutorial. If a user has a specific question about a function they can go to the corresponding symbol page.
7. Add more tables by placing the cell insertion bar at a location in the notebook and again clicking Definition Box.
Adding Cross-Links
The More About section is for links to guide pages and the Related Tutorials section is for related tutorials.
Start typing in any section to add text. Then make a selection, choose Links on the DocumentationTools palette, and pick the type of link from the column. (Expand More Link Tools for more options.)
Adding Search Index Information
"Keyword" cells are what the Mathematica search index uses when cataloging the authoring notebooks, and are not case-sensitive.
Keywords are set up to return the page in the list of search results if a user were to search for that word in the Documentation Center.
Leaving XXXX
Whenever a cell is left with content XXXX, it will be omitted by the build process. Thus the author need not do anything with such cells. Rows in a table whose elements are all XXXX will be omitted by the build process. In addition, tables whose elements are all XXXX will likewise be omitted.
Working with Tutorials Created Prior to Mathematica 6
1. First, have all the tutorials you want to convert to a format usable by the documentation build process in a directory containing no other notebooks. This example uses Extract Tutorials on a directory of tutorials: C:\OldStyleTutorials. After clicking the Extract Tutorials button, a directory browser appears. Select the OldStyleTutorials directory and click OK.
2. For MyApplication the link base will be the same as the application's name. Fill in the resulting dialog's fields Application Name and Link Base with MyApplication. The tutorials produced will be created in a subdirectory of C:\OldStyleTutorials: C:\OldStyleTutorials\Tutorials.
3. The Tutorial Divider may be chosen to be Section or Title for this set of tutorials. If Section is chosen, the tutorials will be divided so that each cell group with style "Section" of the old tutorials becomes a new tutorial. If Title is chosen, since "Title" is the top level cell grouping in each of the old tutorials, each of the new tutorials will correspond to one of the old tutorials. In this example, the divider Section is chosen.
4. Sometimes tutorials prior to Mathematica 6 had numbering associated with each heading. To eliminate numbering prefixes from headings, check the associated checkbox and click OK.
5. The following message arises. Since "Introduction" occurs as a heading in at least two of the old tutorials after numbering prefixes are removed from the headings, those headings must be renamed in the old tutorials before you can proceed. After doing so, you can click Extract Tutorials to proceed as above without generating a message.
6. A notebook UnusedMaterial.nb has been created in C:\OldStyleTutorials\Tutorials\AuxiliaryMaterial with links to the notebooks containing the unused items. The links are not to specific cells since material prior to Mathematica 6 did not have CellIds. In this case these are just the notebook titles, so you do not need to be concerned about inserting this material into the created tutorials.
7. Behind the notebook UnusedMaterial.nb you can see UndefinedStyles.nb (when undefined styles exist), which is also in C:\OldStyleTutorials\Tutorials\AuxiliaryMaterial and has button links to specific cells in the created tutorials with styles not defined in the Tutorial Styles stylesheet. Clicking Style Substitutions brings up a dialog which enables you to automatically replace undefined styles.
8. Clicking the first button under Style: BottomBox in UndefinedStyles.nb and looking at the cell that the cursor highlights suggests that the "BottomBox" style be replaced with "Text".
9. Click "BottomBox" in the upper pane. "BottomBox" now appears with a frame around it. Next scroll to where "Text" appears in the bottom pane.
10. Click the "Text" button in the bottom pane. You will then see "BottomBox → Text" in the upper pane.
11. In this example, the other styles are also replaced by the "Text" style by selecting each in turn and clicking on "Text". It will not always be true that you would want all undefined styles replaced by the same style.
12. At this point, the OK button may be clicked in the Style Substitutions dialog. The style substitutions are then made in the constructed tutorials.
Note: Formatting work will probably be needed on pre-Mathematica 6 tutorials before applying the build process via Workbench.
Note: If you are just converting a single tutorial, open it, click the I button to the right of the Extract Tutorials button, and follow steps similar to what is detailed above.
In constructing the tutorials, an overview of them, Overview.nb, was also constructed in the same directory. The overview consists of links to all of the headings in the tutorials—essentially a table of contents.
13. The overview constructed made use of the tutorials ordered by their file names in alphabetical order. To make an overview with a different order, delete the overview constructed and click Overview Tools ► Generate Overview.
Manually Constructing an Overview
On occasion you may just want to use certain headings in tutorials to construct an overview. This may be done using Overview Tools.
1. Clicking New Overview Page brings up a dialog requesting that the title of the new tutorial be specified.
2. Once that is done, clicking OK will construct a new overview with the title and metadata already filled in. In addition, the overview will be saved in the project's tutorial directory. The dialog that comes up is informational and may be permanently dismissed if so desired.
3. Then use TOC Link Tools ► Browse to open a tutorial in which you want one or more headings to be linked from cells in the overview.
5. Then select the cell bracket of a cell in the overview that you want linked to the heading in the tutorial.
Manually Constructing an Overview
On occasion you may just want to use certain headings in tutorials to construct an overview. This may be done using Overview Tools.
1. Clicking New Overview Page brings up a dialog requesting that the title of the new tutorial be specified.
2. Once that is done, clicking OK will construct a new overview with the title and metadata already filled in. In addition, the overview will be saved in the project's tutorial directory. The dialog that comes up is informational and may be permanently dismissed if so desired.
3. Then use TOC Link Tools ► Browse to open a tutorial in which you want one or more headings to be linked from cells in the overview.
