From maintainers-request at octave dot org Fri Jan 20 10:16:31 2006
Subject: Sparse Doc patch
From: "John W. Eaton" <jwe at bevo dot che dot wisc dot edu>
To: David Bateman <David dot Bateman at motorola dot com>
cc: octave maintainers mailing list <maintainers at octave dot org>
Date: Fri, 20 Jan 2006 11:16:19 -0500

On 20-Jan-2006, David Bateman wrote:

| Can you consider the attached patch and tar-file. It adds most of the 
| missing sparse matrix documentation based on a paper Andy and I 
| submitted to Octave 2006. However, it makes a couple of significant 
| changes to the manner in which the texinfo documentation of octave is 
| handled.
| 
| * Firstly it requires an updating of texinfo.tex to at least version 
| 4.7. I include in the patch the latest version from the texinfo website. 
| This is required to allow the use of the  at float and @caption commands of 
| texinfo to be used for the figures I introduced
| * I include several figure in the tar-file in EPS, PDF and PNG form. 
| These are appropriate for the PS, PDF and HTML versions of the 
| documentation respectively. For the info version of the documentation I 
| included a limited number of text figures to demonstrate the sparsity 
| preserving matrix reordering.
| 
| As this will be the first time figures are used in octave, I imagine 
| that you'll want to consider carefully this change.

I'm replying on the maintainers list to give others a chance to
comment.

Without looking at the patch, I'm in favor of the idea of making this
change.  I see no reason to omit figures from the docs now.  It was
more of a problem back in the dark ages (say, 10-12 years ago) when
fewer people had ways to display PostScript and Texinfo did not have
any standard way of supporting figures, so there was reason to avoid
them.  It would be nice to have ASCII art for the info format, but if
that is not possible, then we can just put a text tag in that briefly
describes the figure (for example, "[Figure showing the sparsity
pattern for FOO]").

If possible, I think we should store the source code for generating
the figures rather than the figures themselves, then add rules to
create EPS, PDF, PNG or whatever formats are needed.  That way, we can
easily modify the figures as needed in the future.  It will be much
harder to do that if all we have are the figures in the final
format(s).

jwe