[Octave-bug-tracker] [bug #60313] Move docstrings to dedicated single pages

[John W. Eaton]

Follow-up Comment #1, bug #60313 (project octave):

Thanks for working on this change.  Instead of modifying the manual sources, I
think we can do all of this automatically as part of the build process.  Then
the list of functions in the reference manual and the short descriptions in
the body of the manual will be updated automatically if functions are added or
removed or if the help text for a function changes.

Since the .txi files are already processed to generate .texi files which are
then given to Texinfo to generate various output formats, we should be able to
simply change what we do for the @DOCSTRING commands in the .txi files.

The text that is substituted for the @DOCSTRING lines in the .txi files comes
from the generated scripts/DOCSTRINGS and libinterp/DOCSTRINGS files.  To make
things simpler, we could extract the first sentence of the help text for each
function and store it on a separate line in the DOCSTRINGS files.  Then we
could use the entries in the DOCSTRINGS files to automatically transform the
@DOCSTRING line in the .txi file to be whatever @xref command is needed for
the body of the manual.

Separately, we could generate an alphabetized list of entries to go in a new
function reference appendix for the manual.

Then it should be easy to generate either the old-style or new-style manual
from the same source files.

So as I see it, the steps would be

0 Modify the libinterp/mk-doc.pl and scripts/mk-doc.pl scripts to extract the
first help sentence and store it in the generated DOCSTRINGS files.
0 Modify the doc/interpreter/munge-texi.pl script to optionally transform the
@DOCSTRING lines to the desired @ref lines.
0 Create a new script to extract the list of all documented functions by
finding all @DOCSTRING lines in the manual sources, then sort the list and
generate the function reference appendix by extracting the corresponding
entries from the DOCSTRINGS files in the sorted order.  A separate script is
needed because the munge-texi.pl script works on a single file at a time and
it should probably remain that way so that it can work in parallel.

At least for now, I think it would be best if generating the new and old style
manuals could remain optional.


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?60313>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/