Re: setting local variables

[Eric Abrahamsen <eric@ericabrahamsen.net>]

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.

>> Does that sound feasible? It would be great if this was available out of
>> the box.
>
> Even though such specialized back-ends are a good thing, I don't think
> Org needs another Texinfo back-end in core, however.
>
> "ox-texinfo.el" is really getting better. It is very versatile so it can
> bend to almost any convention.
>
> I won't pretend it makes learning Texinfo useless, though, because you
> need to learn it to write good manuals. The devil is in the details, and
> those are sometimes located at the Texinfo level.

I guess what I'm missing is clear guidelines on how to write manuals for
Emacs. I did look around, didn't find anything, and then just decided I
would use the easiest solution to hand, even if it wasn't ideal. If I
had a clear sense of what I was working towards, I'd probably put in the
time to learn the basics of texi and ox-texinfo. I guess I'll ask on
emacs.help.

At any rate, all this was in no way meant to be a criticism of
ox-texinfo, which I obviously haven't taken the time to learn...

Eric