Re: setting local variables

[Eric Abrahamsen <eric@ericabrahamsen.net>]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>> Oh I don't think it's about shortcomings, just about having a version
>>> that's tweaked specifically for writing Emacs manuals. I _really_ want
>>> my packages to have info manuals, and I _really_ don't want to learn how
>>> to write texinfo. I saw Rasmus' Org manual in org, and it looked like a
>>> lot of work. Then I noticed that the Magit manuals used this
>>> texinfo-plus thing, and it seemed good enough.
>>
>> I think "ox-texinfo" is (almost) able to write Emacs manuals.
>>
>> IMO, you are comparing oranges and apples. Org's manual is historically
>> written as a (very convoluted) pure Texinfo document, with many macros
>> and different authors. Trying to convert it to Org for an Org to Texinfo
>> process is bound to be painful. OTOH, Magit's manual is probably more
>> straightforward, i.e., written as an Org document from the beginning,
>> with simpler requirements.
>>
>> In both cases, you cannot eschew learning a bit of Texinfo, if only for
>> the various indices commands and the installation part in the Info
>> directory.
>
> Well, I'll admit laziness has been my major motivation throughout the
> whole process.
>
>>> I think what might be nice would be to have another exporter, derived
>>> from ox-texinfo, specifically for writing Emacs manuals, that helps
>>> authors conform to the Emacs manual conventions. The way texinfo-plus
>>> handles lists of keybindings/user options/etc is nice, and it appears to
>>> set up the indexes for you, you only have to add concept index entries
>>> manually.
>>
>> AFAIU, the way texinfo-plus handles lists of ... is certainly nice, but
>> it's unrelated to Emacs manual conventions. It helps authors conform
>> Magit's author conventions. Those are fine, but I'm pretty sure not all
>> Emacs manuals follow them (Org doesn't, obviously).
>
> The main thing I was after was semi-automated indexing (obviously some
> of it you have to do yourself). I just looked more closely at the texi
> output that texinfo-plus produced, and it seems to only be doing concept
> and key indexing, not function or variable indexing. So that's not as
> helpful as I thought.

And regarding the lists of commands and keys, what would be the
recommended way of making a list of @deffns and corresponding index
entries? Perhaps it would be enough to expand the example document in
the texinfo section of the Org manual.

Eric