[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: @defun and @defvr in the "same" block?
From: |
Gavin Smith |
Subject: |
Re: @defun and @defvr in the "same" block? |
Date: |
Sat, 17 Dec 2022 07:31:51 +0000 |
On Fri, Dec 16, 2022 at 03:01:06PM -0800, Raymond Toy wrote:
> > You can do this using @deffn and @deffnx instead, at the expense of also
> > needing to specify "Function" on the first line:
> >
> > @deffn {Function} {check-region-query-size} {region}
> > @deffnx {@sansserif{Hemlock} Variable} @sansserif{Region Query Size} @
> > {@r{(initial value @code{30})}} @useindex{vr}
> > description
> > @end deffn
> >
> > (I used @sansserif to match the style of the original document although
> > this may not be what is desired.)
> >
>
> Oh, that works really well. I don't mind specifying Function. (In fact,
> that's what I was doing until I realized there was defun.)
>
> I hadn't considered matching the original text style. Perhaps I'll
> consider it, but the most important part was that I had a texinfo version
> that had all the information in it.
>
> When (or if) this lands in a release, I'll update the doc to use these
> features.
>
> Does @useindex have to be at the end of the line? Could it be at the
> beginning of the next line? Having it at the end makes an already long
> line even longer and harder to notice that we specified a different index
> for the item.
It has to be after the name of the symbol being indexed, inside the
arguments at the end of the line. You can use a line continuation, as
in:
@deffn {Variable} fun (args) @
@useindex{vr}
description
@end deffn
If you did
@deffn {Function} @useindex{ix} fun (args)
then it will not work due to @useindex{ix} being in the position for
the symbol.
@deffn @useindex{ix} {Function} fun (args)
does not work either, as this will take @useindex{ix} as the category
and Function as the name of the symbol. However, the following does
work:
@deffn {Function} fun @useindex{ix} (args)
This is not good to write though, so if we implement this in texi2any
and document it, then we should recommend or require that @useindex
be at the end of the line (or on the next one using an @ continuation).