RE: How to make table of contents, back-of-the-book index in Mathematica?

*To*: mathgroup at smc.vnet.net*Subject*: [mg104293] RE: [mg104273] How to make table of contents, back-of-the-book index in Mathematica?*From*: "David Park" <djmpark at comcast.net>*Date*: Sun, 25 Oct 2009 23:26:09 -0500 (EST)*References*: <31571602.1256450755161.JavaMail.root@n11>

Hi Nasser, It's really nice to see someone who is interested in using Mathematica as a technical writing medium. It is so powerful and expressive and has so many advantages that I don't see why everyone doesn't use it that way. The crucial question is: who is the audience for your reports? If they have Mathematica, everything is great; if not, then all kinds of problems intrude. You have to involve another program, convert the output, give up most or all dynamics, change your whole style of working and lose many of the advantages of Mathematica. So let's assume that your audience can read your notebooks. Writing "electronic" documents with Mathematica is quite different than writing a paginated printed document. I think that it is better not to try to reproduce the techniques and artifacts of paginated documents but to think how to obtain equivalent, and usually better, functionality within the active medium. So, suppose that your report is relatively short and can be contained within a single notebook. You could produce a table of contents by using Cell Tags and having a text cell at the top with links to the cells. But would you really need a table of contents? If you use sectional groupings (with group openers) and send the notebook with all groups closed, then the document itself is organized as a table of contents. A table of contents at the front is just an anachronistic artifact - like vestigial human tailbones. Similarly, with active median you can do searches with Find or using a NotebookFind statement: NotebookFind[EvaluationNotebook[], "subject", All]; And I guess you could also use Google to search your notebooks, although I'm still not certain how, or how well, that works. In any case, searches ought to be just as good, or even better than an index. Most technical documents have "references" to ancillary material. These might be footnotes, equations elsewhere in the document, citations, and more recently sidebars. The footnotes and citations are sometimes at the bottom of the page or collected at the end of a book. If a note or reference is at the bottom of the page or if a referenced equation is on the same or adjacent page, fine and good, but otherwise you are set off on a search. (It is especially irritating when one must search many pages for a reference equation and then it is in a somewhat different context and refers you to another previous equation.) In an active document one can make links to these various referenced objects. Click the link and you are instantly transferred to another part of the document or another document entirely that contains the object. Is this the best way to do it? I don't think so. It's jerking the reader around. Much better is to bring the object to the place where the reader is. It could be displayed with an inline opener, or in a popup window or as a tooltip. An artifact of active notebook documents, that doesn't occur so much in most printed technical documents, is a "Boiler Plate" or "Specifications" section. You might have elaborate custom graphics or dynamic displays in your document that require detailed specification. Most readers will only want to see the results and not the specifications. One can put these in a Section with quite faint font color in the heading so it doesn't appear so much to be part of the reading portion of the document. (One can close Input/Out cell groups to just show the output but if the output is deleted the input specification reappears so I think it is better to put elaborate specifications somewhere else.) For larger documents that involve many notebooks one can use Workbench/DocuTools. The notebooks can be part of the Documentation files. A Guide page could now serve as a table of contents. With many notebooks in the document a table of contents would now be necessary - at least to link to the various notebooks. It is difficult for me to think of any serious project that wouldn't generate its own specialized routines and packages(s). One could even move the "Boiler Plate" specifications to a package so they wouldn't be seen at all by a reader of an application. Things such as references and key equations might also be contained in Data packages. One newer feature of Mathematica is the ability to have each new cell automatically generate a unique CellID. You can use DocuTools to make links, and create paclet URLs using these CellIDs. This kind of approach has great advantages. Most of all, it is a way to organize and preserve your work. Don't let the fruit of your labors slip through your fingers. It preserves generated knowledge. Routines can be documented with examples. The documents are largely self-proofing. It's all part of normal Mathematica and the normal interface. It communicates to other people. This use of Mathematica is a new medium. We haven't had time to learn and absorb this medium yet. We have to think in terms of the medium and not older technologies. All the basic pieces are there but we still could use a little developmental help from WRI - most of all they could make it easier for other people to read our work. I've tried to collect what might be some principles for using this new medium: 1) In dynamics combine graphical and numerical/symbolic information. 2) In animation and dynamics always provide a fixed background. 3) Don't jerk the reader around. Bring the material to the reader. 4) Duplication is economical and often considerate to the reader. David Park djmpark at comcast.net http://home.comcast.net/~djmpark/ From: Nasser M. Abbasi [mailto:nma at 12000.org] hi; Version 7. If I am to consider using Mathematica for writing things other than just code, I would need to be able to have table of contents (TBL) and an index in the notebook at least. So far, I could not find a way to do this. Once I create the Title, Section, etc.., I need to create TBL at the start and an index at the end, and be able to export the notebook to HTML and PDF and have links created automatically from the table of content to each separate section and subsection listed in the TBL. There used to be an AuthroTool package, but it seems to have disappeared ? and can't find where to download it http://documents.wolfram.com/mathematica/Add-onsLinks/AuthorTools/WhatIsAuth orTools.html What replaces it? And I do not want to look at publicon, as I am not sure if it is even still active (do not hear about it, and no version number or a date on the web site) http://www.wolfram.com/products/publicon/ and I also want to just use one program to do everything, not 2. If I am to copy stuff from my Mathematica notebook to publicon to create a report, then I might as well copy things to Latex as I currently do. So, some people recommend using Mathematica for doing all the coding and the report as well, ie. not just for the code, and I would like to be able to do this (simplify life) but without these basic things, I do not see how this can be productive. I hope I am just overlooking something here? Thank you, --Nasser