MathGroup Archive 2009

[Date Index] [Thread Index] [Author Index]

Search the Archive

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 





  • Prev by Date: Re: Re: JLink broken on Snow Leopard
  • Next by Date: Re: Using "/@" Effectively
  • Previous by thread: How to make table of contents, back-of-the-book index in Mathematica?
  • Next by thread: Summing all the elements along a dimension in a matrix