From maintainers-request at octave dot org Fri Jan 20 10:48:42 2006
Subject: Re: Sparse Doc patch
From: Quentin Spencer <qspencer at ieee dot org>
To: "John W. Eaton" <jwe at bevo dot che dot wisc dot edu>
CC: David Bateman <David dot Bateman at motorola dot com>,         octave maintainers mailing list <maintainers@octave.org>
Date: Fri, 20 Jan 2006 10:38:03 -0600

John W. Eaton wrote:

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

I think including figures is a great idea, and I agree that it is now 
more practical than it once might have been. I also agree with John's 
suggestion of storing the source code. In addition to making long-term 
maintenance, having some example code in the octave distribution could 
also be a helpful resource for people asking one of the most FAQs of 
them all on the help list: "How do I save my figures?"

-Quentin