On 29 Jun 2000, Niels Möller wrote:
> > > info -f ./lsh.info --usage lsh
> > >
> > > it brings up the "lsh basics" node (which is a tutorial section)
> > > rather than the reference section "Invoking lsh". Is there any special
> > > markup I can use in my sourcefile to help info --usage choose the
> > > right node?
> >
> > You need to follow GNU standards: the "Invoking" node should be in the
> > first-level or second-level menu in the manual.
>
> It is.
I will need to see the entire file to analyze why does it go to a
different section in your case.
In general, different manuals have their own ideas about how to organize
the usage info, and it is not easy to come out with a scheme that will
work for all of them. I did quite a bit of testing at the time to tune
the heuristics, with many different manuals, and succeeded to get it to
DTRT for most of them.
> I think it would be a good thing to add a new magic word
>
> @usage lsh
You don't need a new directive, just use this:
@anchor lsh-usage
> In general, I think it is better to use
> explicit markup than to rely in heuristics.
Explicit markup cannot be introduced as quickly as heuristics: you need
to wait until all the manual maintainers start using the new markup. For
example, @anchor was introduced last September, but it is still largely
unused in GNU manuals.
> BTW, non-interactive use of info --usage >some-file.txt seems to dump
> the entire info file, not just the invocation node. For example,
>
> info --usage gcc
>
> starts interactive info on the right node, but
>
> info --usage gcc |less
>
> displays the entire gcc manual. Is that intentional?
Looks like a bug: it works correctly for some manuals, but not for
others.
