Re: @ref into @seealso

[Søren Hauberg]

tir, 21 10 2008 kl. 10:57 -0400, skrev John W. Eaton:
> On 21-Oct-2008, Søren Hauberg wrote:
> 
> | tir, 21 10 2008 kl. 09:15 +0100, skrev David Bateman:
> | > Thorsten Meyer wrote:
> | > > Hi,
> | > >
> | > > I think that it would be quite useful to transform the references in the
> | > > @seealso sections in the documentation of the octave functions into
> | > > texinfo references (e.g. @ref).
> | > > I would like to do it like that:
> | > >  - add a perl script to the make sequence of the octave documentation,
> | > > that does the following:
> | > > - parse the .txi files to collect information on which file       
> contains
> | > > the documentation of which function
> | > > - postprocess the DOCSTRINGS files to transform all
> | > > @seealso(anyfunction) sections into 
> @seealso(@ref(anyfunction,,its-txifile))
> | > >
> | > > (I have found, that anchor for all the functions already get added to   
> | > > the .texi files by munch-texi).
> | > >
> | > > Would you consider an according changeset?
> | > > Is it ok to add the (as far as I can see) second perl dependency to the
> | > > build process?
> 
> Why would it need to be a second script?  Couldn't this be added to
> the munge-texi program?

The munge-texi program essentially replaces all @DOCSTRING(func) with
the texinfo help text of 'func', right? When reading the help text of
'func', we would then have to search for @seealso, and handle those
appropriately. I guess it wouldn't be to hard to do, but I think it
would be better to rewrite munge-texi as an m-file.

Some weeks ago I posted a suggestion on rewriting the help system as
m-files [1]. This approach included the function 'get_help_text' which
returns the raw texinfo help string of a function (using the code
already in Octave for this). Using this function, it would be trivial to
rewrite munge-texi as an m-file, which in turn would make it easier to
change munge-texi to expand @seealso.
 
> | Yeah, I think I did that in python. I remember trying to do it directly
> | in texinfo, but for some reason that never worked out.
> 
> The macro capabilities of Texinfo are unfortunately pretty limited.  I
> don't think there is a good way to parse an argument to a macro, so
> splitting the elements of the seealso list is probably impossible.

I seem to remember that I got pretty close to making it work by by
splitting to argument list to @seealso up in 'first element' and 'rest
of the list', and then recursively handle 'rest of the list'. I don't
remember the details, but I think I stopped simple because I realised I
would need to use python anyway for some other task (I can't remember
the details anymore).

Søren

[1] http://www.nabble.com/help-as-m-files-td19710556.html