help-octave
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

How to type texinfo doc-strings? [was: tex documentation]


From: Christoph Spiel
Subject: How to type texinfo doc-strings? [was: tex documentation]
Date: Sat, 17 Feb 2001 16:30:33 +0100
User-agent: Mutt/1.2.5i

On Thu, Feb 15, 2001 at 11:51:20AM -0600, John W. Eaton wrote:
> The source for the manual is in the doc/interpreter directory in the
> source distribution (mostly in .txi files).  It is written using
> Texinfo, not LaTeX.  The function descriptions in the manual are now
> actually part of the source code.  For example, in
> src/DLD-FUNCTIONS/svd.cc, you will find:
> 
>   DEFUN_DLD (svd, args, nargout,
>     "-*- texinfo -*-\n\
>   @deftypefn {Loadable Function} address@hidden =} svd (@var{a})\n\
>   @deftypefnx {Loadable Function} address@hidden, @var{s}, @var{v}] =} svd 
> (@var{a})\n\
>   @cindex singular value decomposition\n\
>   Compute the singular value decomposition of @var{a}\n\
>   @iftex\n\
>   @tex\n\
>   $$\n\
>    A = U\\Sigma V^H\n\
>   $$\n\
>   ...

As we are at it ...  How do the gurus type in the doc-string?  What
bothers me is the explicit '\n\'-sequence at the end of each line,
which gets screwed up after each (fill-paragraph).  Is there are tool
that appends the correct line ends, inserts the text, etc.?

Currently, I run the sources through a preprocessor, which substitutes
the texinfo help file into the C-file before the compiler looks at it:
        DEFUN_DLD(xdot, args, , "<<<xdot.texi>>>")
where xdot.texi contains the text.  This violates the
docu-goes-with-code rule, I know, but it makes localizing the
doc-string really easy.  :-)

To have the doc-string in the source, something like here documents
would be necessary:
        DEFUN_DLD(xdot, args, , <<END_OF_XDOT_DOCUMENTATION
-*- texinfo -*-
@deftypefn {Loadable Function} address@hidden =} xdot (@var{x}, @var{y})

...

@var{s} rounded to double precision.
END_OF_XDOT_DOCUMENTATION
)

Anyhow, are these good, bad, or ugly ideas to make doc-strings a bit
more programmer friendly?


Cheers,
        Chris

-- 
Christoph L. Spiel  <address@hidden>
Hammersmith Consulting,  web: www.hammersmith-consulting.com
Phone: +49-8022-662908, fax: +49-8022-662909



-------------------------------------------------------------
Octave is freely available under the terms of the GNU GPL.

Octave's home on the web:  http://www.octave.org
How to fund new projects:  http://www.octave.org/funding.html
Subscription information:  http://www.octave.org/archive.html
-------------------------------------------------------------



reply via email to

[Prev in Thread] Current Thread [Next in Thread]