Re: Texinfo 5 and deftypefnx

[Carnë Draug]

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ë