octave-maintainers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Texinfo 5 and deftypefnx


From: John W. Eaton
Subject: Re: Texinfo 5 and deftypefnx
Date: Sun, 24 Mar 2013 15:07:09 -0400
User-agent: Mozilla/5.0 (X11; Linux i686; rv:10.0.11) Gecko/20121123 Icedove/10.0.11

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?

jwe


reply via email to

[Prev in Thread] Current Thread [Next in Thread]