Re: non-obvious help needed

[Bruce Korb]

On 08/05/12 09:59, Bruce Korb wrote:
> Hi,
>
> Here is some texi source:
>
> > @menu
> > * unshar usage::                  unshar help/usage (--help)
> > * unshar directory::              directory option (-d)
> > * unshar overwrite::              overwrite option (-c)
> > * unshar force::                  force option (-f)
> > * unshar split-at::               split-at option (-E)
> > * unshar exit-0::                 exit-0 option (-e)
> > * unshar config::                 presetting/configuring unshar
> > * unshar exit status::            exit status
> > * unshar Authors::                Authors
> > * unshar Reporting Bugs::         Reporting Bugs
> > @end menu
> >
> > @node unshar usage
> > @subsection unshar help/usage (--help)
> > @cindex unshar help
> >
> > This is the automatically generated usage text for unshar.
> >
> > The text printed is the same whether selected with the @code{help} option
> > (--help) or the @code{more-help} option (-!).  @code{more-help} will print
>
> The "--help" renders in the menu with both hyphens.
> The ones in the @subsection line and the later text
> are unhelpfully "fixed up" and render with one hyphen.
> How do I tell texi to leave my hyphens alone?
>
> (The document is not hand edited, by the way.  I go
> to a lot of trouble to figure out how the program
> [unshar in this case] requests help and spread that
> information around the document.  Should I just replace
> all hyphens with "@-" for example?)

Via experimentation:

1.  "\-" (the man page way) prints the backslashes
2.  "@-" erases all the hyphens
3.  "----" prints three hyphens
4.  the magic is to put one extra hyphen in some circumstances, but
    not in others.  For example, don't do it in menus, but do do it
    in @section and plain text lines.

Are there any other rules?  I did not derive this from reading the
texi manual.  I had to experiment.