Re: Octave Function Reference Manual?

[David Bateman]

John W. Eaton wrote:
>
> I don't object to having a separate reference manual if people find
> that useful.
>   
There is no consensus on this point yet.

> My preference would be to omit all internal and deprecated/obsolete
> functions from the list.
>   
Ok. In fact all I've done so far is try and make a document that might
resemble what such a manual might look like to give something to talk
about.. There is of course lots of changes that are needed. PDF
navigation is the major missing feature for me.

> Also, I think the perl script could probably be simplified
> considerably.  We already have tools to generate Texinfo source files
> from the DOCSTRING files and input files that look like this:
>
>   @DOCSTRING(all)
>
>   @DOCSTRING(any)
>
>   ...
>
> so it seems that it would be simpler to reuse that script and just
> have yours emit @DOCSTRING(name) lines (have your script generate a
> .txi file and add a few dependencies and rules in
> doc/interpreter/Makefile.in, and I think you are done).
>   
I tried to be a bit fancy and also extract the first sentence for the
table of contents by toolbox section, and the makeinfo version of the
manual. If we decide to get rid of that section it might make sense to
do as you say.. Also what about the operators and keywords? The script I
sent does the same as the octave-forge indexing code and calls octave
for functions it can't get from the *.m or *.cc or DOCSTRINGS files, and
this includes keywords and operators..

> For proper formatting, we should be parsing the Texinfo to extract the
> parts we need instead of running makeinfo.  I think your lookfor
> function already does something close to what is needed to generate
> the brief description for the categorical list.  To really make this
> work well, we will either need to enforce some discipline for writing
> the first line of any docstring, or we will need to introduce another
> (perhaps optional) command in the docstring like @synopsis{...} that
> could be used for this purpose.  
The matlab way is the first line is a short description... Also note
that the makeinfo code is called only for the formatting of the first
sentence, and texinfo is used for the rest of the formatting. In fact
the Flookfor function is based on the octave-forge perl script and
essentially does the same thing to extract the first sentence..

I suppose if the code is integrated in octave, then it makes sense to
only have one mechanism to do something, so yes it would make sense to
as much as possible use the lookfor code for the first sentence.

> We might also consider an optional
> @category{} command that could be used when automatic determination of
> the category fails.
>   
Yes all of these might help, but imply additional work.. I suppose I was
looking for a quick solution to write as much of the documentation as
possible..

D.



> jwe
>
>   


-- 
David Bateman                                address@hidden
Motorola Labs - Paris                        +33 1 69 35 48 04 (Ph) 
Parc Les Algorithmes, Commune de St Aubin    +33 6 72 01 06 33 (Mob) 
91193 Gif-Sur-Yvette FRANCE                  +33 1 69 35 77 01 (Fax) 

The information contained in this communication has been classified as: 

[x] General Business Information 
[ ] Motorola Internal Use Only 
[ ] Motorola Confidential Proprietary