Re: setting local variables

[Eric Abrahamsen <eric@ericabrahamsen.net>]

Rasmus <rasmus@gmx.us> writes:

> Hi,
>
> (Sorry for replying to this old thread which I am only reading now)
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>>>> I'm writing an Emacs manual in Org, using
>>>> https://github.com/tarsius/ox-texinfo-plus to make things a bit
>>>> easier.
>>>
>>> I don't know that library, but as a biased POV, it would be nice to use
>>> "ox-texinfo" and let us know about its shortcomings. Just saying.
>>
>> 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.
>
> It was Thomas S. Dye who ported the Org manual in Org
>
>     https://github.com/tsdye/orgmanual
>
> FWIW I like to see general tweaks added directly to ox-texinfo to the
> extend it’s feasible.

Oops, sorry about that.

Later I removed my manual's dependency on ox-texinfo+, and went with
plain Org export functionality. It looks a lot better now, and is more
correct, but it took me a good half day to learn texinfo and do the
work. I knew I'd have to do that at some point, so that's fine, I was
just putting it off.

The only real problem I encountered was that links to external Info
manuals did not export correctly, and couldn't be followed. I gave up on
learning the exact syntax of texinfo's @[px]ref commands because it was
dinnertime, but I can figure out what went wrong and maybe provide a
patch.

The other thing I'd like to know is how to "inline" sections (ie output
several sections on a single page), but still have links to those
sections work correctly.

That problem and most others could probably be "solved" by expanding the
docs. For instance, regarding the sectioning problem, "12.14.6 Headings
and sectioning structure" in the Org manual says:

  If an Org headline’s level has no associated Texinfo structuring
  command, or is below a certain threshold (*note Export settings), then
  the Texinfo export back-end makes it into a list item.

Why a list item? Plenty of Info manuals have multiple sub-headings on a
single page, how do we do that?

In general, I think the texinfo part of the Org manual could benefit
from some beefing up, and I'd be happy to provide suggestions.

Eric