Re: Texinfo 5 and deftypefnx

[Rik]

On 07/26/2013 07:35 AM, Carnë Draug wrote:
> On 03/24/2013 07:07 PM, jwe wrote:
>> On 03/24/2013 02:48 PM, Rik wrote:
>>> 3/24/13
>>>
>>> The fix is conceptually simple.  Texinfo 5 does not allow separating
>>> @deftypefn and @deftypefnx entries.  Most of the time the documentation is
>>> written as
>>>
>>> @deftypefn ...
>>> @deftypefnx ...
>>> ...
>>> @end deftypefn
>>>
>>> Occasionally, however, the documentation is
>>>
>>> @deftypefn ...
>>> Some documentation lines
>>> @deftypefnx ...
>>> Some more documentation lines
>>> @end deftypefn
>>>
>>> To change the second form into the first form requires moving the
>>> @deftypefnx entries to be adjacent to the @deftypefn entry -- which is
>>> easy.  Unfortunately it also requires re-writing the documentation lines so
>>> that the sentences still make sense.  That was a little harder which is why
>>> it hasn't been done.
>> In most cases, I'd prefer to have the deftypefn{,x} commands all
>> grouped together.  But if a function has many different ways that it
>> may be called and they are significantly different, it can be hard to
>> describe the behavior clearly when all the deftypefn{,x} commands are
>> together.
>>
>> Another possibility would be to do something like
>>
>>    @deftypefn ..
>>    ..
>>    @end deftypefn
>>    ...
>>    @deftypefn ..
>>    @deftypefnx .. (optionally)
>>    ..
>>    @end deftypefn
>>
>> I don't have a problem with using this form when it is justified, and
>> provided that any tools we have that operate on function doc strings
>> will display all of the deftypefn blocks that correspond to the given
>> function.  Previously, that was relatively easy as we just had to look
>> for a single pair of matching @deftypefn/@end deftypefn lines.  I
>> haven't experimented, so I'm not sure whether there is anything to fix
>> if we switch to using multiple @deftypefn/@end deftypefn blocks.  One
>> oher thing, if I remember correctly, is that each @deftypefn will
>> generate some indexing info.  Will multiple commands cause trouble?
> I have brought this up again because of the current problem with the
> statistics package. The solution proposed of ending deftypen and open
> a new one in the middle of the help text works fine to display the
> help text. However, it seems to mess up calls to print_usage (at least
> with TexInfo 4.13). In the development version, try print_usage
> ("gallery").
>
> How should the documentation be written for this cases?

Carnë,

The documentation is fine in this instance.  It is print_usage() that needs to 
change.  I checked in a changeset that fixes the behavior for functions with 
multiple @deftypefn/@end deftypefn pairs 
(http://hg.savannah.gnu.org/hgweb/octave/rev/ae7872816611).

--Rik