Re: munge-texi.pl

[Pantxo Diribarne]

2016-04-27 22:53 GMT+02:00 Rik <address@hidden>:

On 04/27/2016 01:33 PM, address@hidden wrote:

Subject:

Re: Re: Help strings in the text body of the manual

From:

Pantxo Diribarne <address@hidden>

Date:

04/27/2016 01:33 PM

To:

address@hidden

List-Post:

<mailto:address@hidden>

Precedence:

list

MIME-Version:

1.0

References:

<address@hidden> <address@hidden> <address@hidden> <address@hidden> <address@hidden>

In-Reply-To:

<address@hidden>

Message-ID:

<address@hidden>

Content-Type:

multipart/mixed; boundary="------------060403090001020909090908"

Message:

3

Yes, rewriting the @DOCSTRING macro in munge-texi.pl is definitely the best solution. Unfortunately I got lost as soon as I dared looking for the first time at a a Perl script. I'll remember the references, if ever I want to learn a minimal bit of perl :-).

That would be my doing.  It is not obfuscated Perl, if you already know the language;  But it is not an easy introductory script either.  I used lots of concise features of the language as well as optimizations.  If a consensus is reached on how to proceed I can update munge-texi.  Offhand, It looks like introducing an @DOCLINK macro would be the easiest thing.  That would expand to a link which pointed to the full text of the help string which would be positioned in the manual with @DOCSTRING.

--Rik

Just to see how it looks, I modified plot.txi (attached patch) using an octave function.
Basically, in place of the original @DOCSTRING, I put a link followed by the first help sentence.
The actual doc string is pushed at the end of the chapter.

Pantxo

I would think of something like
* @DOCLINK:  creates a link plus first sentence of the docstring at the location where it is placed
* @DOCSTRING: same as @DOCLINK but also adds the full doctring at the end of the chapter where it is placed or at the end of the manual.

The advantages are:
* the current .txi files don't have to be modified,
* lets us the ability to keep a form of organization and separate, in the function reference, what comes from the "Plotting" chapter from what's from the "Trigonometry"
* most of the time only @DOCSTRING is necessary. @DOCLINK is used only when you want an extensive reference (not a simple @xref) to a function somewhere else than the main section in which it was declared using @DOCSTRING.

Pantxo