bugGNU Octave - Bugs: bug #60313, Move docstrings to dedicated...

 
 

bug #60313: Move docstrings to dedicated single pages

Submitter:  Pantxo Diribarne <pantxo>
Submitted:  Tue 30 Mar 2021 08:23:12 PM UTC
   
 
Category:  Documentation Severity:  1 - Wish
Priority:  5 - Normal Item Group:  Feature Request
Status:  None Assigned to:  None
Originator Name:  Open/Closed:  * Open
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Wed 31 Mar 2021 12:32:00 AM UTC, comment #3: 

A wish for the function reference: Please generate individual pages for each referenced function docstring.  For example, "eigs.html" for the "eigs"-function.


Currently, I "misuse" Texinfos XREF, e.g. for the "eigs"-function it is

https://octave.org/doc/v6.2.0/XREFeigs.html

This looks a little ugly with the XREF prefix, but works quite nice. More complicated containers.Map

https://octave.org/doc/v6.2.0/XREFcontainers_005fMap.html

This is harder to read, guess, and find.

Kai Torben Ohlhus <siko1056>
Group Member
Tue 30 Mar 2021 09:53:39 PM UTC, comment #2: 

That sounds like a good solution but I can't speak Perl. Someone else will have to do the job.

Pantxo Diribarne <pantxo>
Group Member
Tue 30 Mar 2021 09:27:51 PM UTC, comment #1: 

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

  1. 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.
  2. Modify the doc/interpreter/munge-texi.pl script to optionally transform the @DOCSTRING lines to the desired @ref lines.
  3. 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.

John W. Eaton <jwe>
Group administrator
Tue 30 Mar 2021 08:23:12 PM UTC, original submission:  

Currently, dosctrings for Octave functions are scattered all around in the chapters of the manual, interlaced or not with explanatory text. This structure if often hard to read.

As proposed during the latest on-line meeting, I attached a test patch in which I moved all docstrings to a dedicated "Function Reference" appendix. A link, with the first help sentence is added where @DOCSTRING originally was.

I also attached the script I used to do the job automatically.

Pantxo Diribarne <pantxo>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #51164:  move_docstrings.patch added by pantxo (352KiB - text/x-patch)
file #51165:  move_docstrings.m added by pantxo (4KiB - text/x-objcsrc)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by siko1056 (Posted a comment)
  • -email is unavailable- added by jwe (Posted a comment)
  • -email is unavailable- added by pantxo (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 2 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-03-30 pantxo Attached File- Added move_docstrings.patch, #51164
        Attached File- Added move_docstrings.m, #51165

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code