template for writing Emacs manuals in Org

template for writing Emacs manuals in Org

[Eric Abrahamsen]

I remember a while ago there was a discussion (on emacs.devel? I can't
remember) about the format for Emacs manuals, and Org came into it, and
at some point someone (Rasmus? Achim Gratz? I can't remember this
either) posted a template for doing Emacs manuals in Org. It was
particularly useful because it had all the macros set up to create the
texinfo index, and it wasn't simple.

I can't remember enough of the details to find the post anymore, though
I've tried. Does anyone recall this, or know how to find it? Or does
anyone have a good setup for exporting to Emacs manuals, plus index?

Let's add it to Worg once we've got it!

Thanks,
Eric

Re: template for writing Emacs manuals in Org

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 105 bytes --]

Copying Oleh as I believe he uses org to generate Info manual for his ivy
package.
-- 

-- 
Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 152 bytes --]

Re: template for writing Emacs manuals in Org

[John Hendy]

I don't recall it, but these look along similar lines?
- https://www.reddit.com/r/emacs/comments/2bummt/changing_emacs_documentation_system_from_texinfo/
- https://lwn.net/Articles/625072/


John

On Sat, May 14, 2016 at 2:21 AM, Eric Abrahamsen
<eric@ericabrahamsen.net> wrote:
> I remember a while ago there was a discussion (on emacs.devel? I can't
> remember) about the format for Emacs manuals, and Org came into it, and
> at some point someone (Rasmus? Achim Gratz? I can't remember this
> either) posted a template for doing Emacs manuals in Org. It was
> particularly useful because it had all the macros set up to create the
> texinfo index, and it wasn't simple.
>
> I can't remember enough of the details to find the post anymore, though
> I've tried. Does anyone recall this, or know how to find it? Or does
> anyone have a good setup for exporting to Emacs manuals, plus index?
>
> Let's add it to Worg once we've got it!
>
> Thanks,
> Eric
>
>

Re: template for writing Emacs manuals in Org

[Rasmus]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> I remember a while ago there was a discussion (on emacs.devel? I can't
> remember) about the format for Emacs manuals, and Org came into it, and
> at some point someone (Rasmus? Achim Gratz? I can't remember this
> either) posted a template for doing Emacs manuals in Org. It was
> particularly useful because it had all the macros set up to create the
> texinfo index, and it wasn't simple.

Magit is the biggest project that I know of that is using Org for its
manual "in production".

Once upon a time Tom ported the Org manual.  It's on his github, probably
under tsdye.

Hope it helps,
Rasmus

-- 
This is the kind of tedious nonsense up with which I will not put

Re: template for writing Emacs manuals in Org

[Thomas S. Dye]

Rasmus writes:

> Once upon a time Tom ported the Org manual.  It's on his github, probably
> under tsdye.

https://github.com/tsdye/orgmanual
-- 
Thomas S. Dye
http://www.tsdye.com

Re: template for writing Emacs manuals in Org

[Nicolas Goaziou]

Hello,

"Thomas S. Dye" <tsd@tsdye.com> writes:

> Rasmus writes:
>
>> Once upon a time Tom ported the Org manual.  It's on his github, probably
>> under tsdye.
>
> https://github.com/tsdye/orgmanual

What about moving it to "contrib/"? It could help keeping it up-to-date.

Regards,

-- 
Nicolas Goaziou

Re: template for writing Emacs manuals in Org

[Thomas S. Dye]

Aloha Nicolas,

Nicolas Goaziou writes:

> Hello,
>
> "Thomas S. Dye" <tsd@tsdye.com> writes:
>
>> Rasmus writes:
>>
>>> Once upon a time Tom ported the Org manual.  It's on his github, probably
>>> under tsdye.
>>
>> https://github.com/tsdye/orgmanual
>
> What about moving it to "contrib/"? It could help keeping it up-to-date.

I'm happy if someone moves it to contrib/.  Is there anything for me to
do before/after that happens?

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: template for writing Emacs manuals in Org

[Nicolas Goaziou]

Hello,

"Thomas S. Dye" <tsd@tsdye.com> writes:

> I'm happy if someone moves it to contrib/.

Done.

> Is there anything for me to do before/after that happens?

Not really. Of course, feel free to help keeping (making) it up-to-date
if your spare time allows it.

Once the manual is up-to-date, we might consider moving it to doc/ in
main distribution.


Regards,

-- 
Nicolas Goaziou

Re: template for writing Emacs manuals in Org

[Thomas S. Dye]

Aloha Nicolas,

Nicolas Goaziou writes:
>
> Once the manual is up-to-date, we might consider moving it to doc/ in
> main distribution.

IIRC, Bastien doesn't like this idea.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: template for writing Emacs manuals in Org

[Nicolas Goaziou]

"Thomas S. Dye" <tsd@tsdye.com> writes:

> Nicolas Goaziou writes:
>>
>> Once the manual is up-to-date, we might consider moving it to doc/ in
>> main distribution.
>
> IIRC, Bastien doesn't like this idea.

Really? I admit I would be surprised. Do you recall why so, or do you
have any reference about it?

Regards,

Re: template for writing Emacs manuals in Org

[Thomas S. Dye]

Aloha Nicolas,

Nicolas Goaziou writes:

> "Thomas S. Dye" <tsd@tsdye.com> writes:
>
>> Nicolas Goaziou writes:
>>>
>>> Once the manual is up-to-date, we might consider moving it to doc/ in
>>> main distribution.
>>
>> IIRC, Bastien doesn't like this idea.
>
> Really? I admit I would be surprised. Do you recall why so, or do you
> have any reference about it?

That is all I remember from three years ago, but it's not really
important.

Looking ahead, the question is whether or not maintaining the
documentation in Org, rather than texinfo, is a possibility, and, if so,
what are the conditions under which that change will or will not happen?

What are Bastien's expectations and preferences?

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: template for writing Emacs manuals in Org

[Charles C. Berry]

On Tue, 17 May 2016, Thomas S. Dye wrote:

> Aloha Nicolas,
>
> Nicolas Goaziou writes:
>
>> "Thomas S. Dye" <tsd@tsdye.com> writes:
>>
>>> Nicolas Goaziou writes:
>>>>
>>>> Once the manual is up-to-date, we might consider moving it to doc/ in
>>>> main distribution.
>>>
>>> IIRC, Bastien doesn't like this idea.
>>
>> Really? I admit I would be surprised. Do you recall why so, or do you
>> have any reference about it?
>

Maybe this thread:

http://thread.gmane.org/gmane.emacs.orgmode/85574

Where Bastien says: "the day we can export org.org to org.texi with very 
little headache and ad hoc configuration, yes, we will make the move."

which sounds supportive to me.

Chuck

Re: template for writing Emacs manuals in Org

[Nick Dokos]

"Thomas S. Dye" <tsd@tsdye.com> writes:

> Aloha Nicolas,
>
> Nicolas Goaziou writes:
>
>> "Thomas S. Dye" <tsd@tsdye.com> writes:
>>
>>> Nicolas Goaziou writes:
>>>>
>>>> Once the manual is up-to-date, we might consider moving it to doc/ in
>>>> main distribution.
>>>
>>> IIRC, Bastien doesn't like this idea.
>>
>> Really? I admit I would be surprised. Do you recall why so, or do you
>> have any reference about it?
>
> That is all I remember from three years ago, but it's not really
> important.
>
> Looking ahead, the question is whether or not maintaining the
> documentation in Org, rather than texinfo, is a possibility, and, if so,
> what are the conditions under which that change will or will not happen?
>
> What are Bastien's expectations and preferences?
>

I believe the main obstacle is that the emacs policy requires a texinfo
manual for all its component parts. If that can be generated
automatically from the org document, then any objections probably
disappear. Of course, Bastien might object to the extra effort required
to do the conversion, but if the conversion is indeed completely
automatic (or, perhaps more likely, a volunteer can be found to take
care of the conversion and any problems that might arise), then he might
be amenable to it. But it would be an extra step required at release
time and would require some coordination.

--
Nick

Re: template for writing Emacs manuals in Org

[Rasmus]

Hi,

Nick Dokos <ndokos@gmail.com> writes:

> I believe the main obstacle is that the emacs policy requires a texinfo
> manual for all its component parts.

What is the "component parts"?  I couldn't find the definition.

>  If that can be generated automatically from the org document, then any
> objections probably disappear. Of course, Bastien might object to the
> extra effort required to do the conversion, but if the conversion is
> indeed completely automatic (or, perhaps more likely, a volunteer can be
> found to take care of the conversion and any problems that might arise),
> then he might be amenable to it. But it would be an extra step required
> at release time and would require some coordination.

My issue is all the damn macros.  While it displays the flexibility of
Org, it also makes Org-for-texinfo-manuals less appealing.  I don’t want
to learn new mini documentation language for each manual I might send
patches to.

Maybe a "Library-of-Macros" would go some of the way of at least making it
feel less ad-hoc?

Another annoyance.  When I see something like the an index right after a
headline, I really would like to put the index into the properties drawer:

     ** Installation
        :PROPERTIES:
        :DESCRIPTION: How to install a downloaded version of Org-mode
        :END:

     {{{cindex(installation)}}}

Aside: I’ve been wanting a drawer property for inserting text just before
headings (and maybe just after headings) for a while, e.g.

         EXPORT_BACKEND_{BEFORE, AFTER}, or
         INSERT_{BEFORE, AFTER}

It would also be useful for latex, e.g.

    * Proofs
      :PROPERTIES:
      :EXPORT_LATEX_BEFORE: \appendix
      :INSERT_BEFORE: @@latex:\appendix@@
      :END:

Rasmus

-- 
ツ

Re: template for writing Emacs manuals in Org

[Jonathan Leech-Pepin]

Hi,

On May 18, 2016 5:21:06 AM EDT, Rasmus <rasmus@gmx.us> wrote:
>Hi,
>
>Nick Dokos <ndokos@gmail.com> writes:
>
>> I believe the main obstacle is that the emacs policy requires a
>texinfo
>> manual for all its component parts.
>
>What is the "component parts"?  I couldn't find the definition.
>
>>  If that can be generated automatically from the org document, then
>any
>> objections probably disappear. Of course, Bastien might object to the
>> extra effort required to do the conversion, but if the conversion is
>> indeed completely automatic (or, perhaps more likely, a volunteer can
>be
>> found to take care of the conversion and any problems that might
>arise),
>> then he might be amenable to it. But it would be an extra step
>required
>> at release time and would require some coordination.
>
>My issue is all the damn macros.  While it displays the flexibility of
>Org, it also makes Org-for-texinfo-manuals less appealing.  I don’t
>want
>to learn new mini documentation language for each manual I might send
>patches to.
>
>Maybe a "Library-of-Macros" would go some of the way of at least making
>it
>feel less ad-hoc?
>
>Another annoyance.  When I see something like the an index right after
>a
>headline, I really would like to put the index into the properties
>drawer:
>
>     ** Installation
>        :PROPERTIES:
>        :DESCRIPTION: How to install a downloaded version of Org-mode
>        :END:
>
>     {{{cindex(installation)}}}
>

I’m trying to remember why I didn’t implement indexes as properties (it may well have been because I simply didn’t consider it).  Assuming there’s nothing in the exporter to prevent converting properties to text after headlines it could work. Treat comma separated values as separate entries.

Then using the macro would only be needed if indexing at content rather than at a headline (use lower level headlines that do not become nodes and it could still work).

>Aside: I’ve been wanting a drawer property for inserting text just
>before
>headings (and maybe just after headings) for a while, e.g.
>
>         EXPORT_BACKEND_{BEFORE, AFTER}, or
>         INSERT_{BEFORE, AFTER}
>
>It would also be useful for latex, e.g.
>
>    * Proofs
>      :PROPERTIES:
>      :EXPORT_LATEX_BEFORE: \appendix
>      :INSERT_BEFORE: @@latex:\appendix@@
>      :END:
>
>Rasmus

--
Jon

Re: template for writing Emacs manuals in Org

[Nicolas Goaziou]

Hello,

Jonathan Leech-Pepin <jonathan.leechpepin@gmail.com> writes:

> I’m trying to remember why I didn’t implement indexes as properties
> (it may well have been because I simply didn’t consider it). Assuming
> there’s nothing in the exporter to prevent converting properties to
> text after headlines it could work. Treat comma separated values as
> separate entries.

Index entries are not section wide. It doesn't sound right to attach
them to properties drawers.

Besides, the {{{cindex()}}} macro is not used anymore.  There is the
CINDEX keyword, which is slightly better.

I guess we could use #+INDEX instead, but it would require to add an
information specific to Texinfo (index type), which would probably
defeat the simplicity of the solution.

Regards,

-- 
Nicolas Goaziou

Re: template for writing Emacs manuals in Org

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Jonathan Leech-Pepin <jonathan.leechpepin@gmail.com> writes:
>
>> I’m trying to remember why I didn’t implement indexes as properties
>> (it may well have been because I simply didn’t consider it). Assuming
>> there’s nothing in the exporter to prevent converting properties to
>> text after headlines it could work. Treat comma separated values as
>> separate entries.
>
> Index entries are not section wide. It doesn't sound right to attach
> them to properties drawers.

In many cases an index entry is referring explicitly to a specific
heading.  Example:

    ** Installation
       :PROPERTIES:
       :DESCRIPTION: How to install a downloaded version of Org-mode
       :END:

    #+cindex: installation

In such cases I’d prefer to able to attach the index specifically to the
heading.  Much the same way that I prefer to give a heading a custom_id
property rather than putting a <<label>> after a headline.

> Besides, the {{{cindex()}}} macro is not used anymore.  There is the
> CINDEX keyword, which is slightly better.

My bad, I must have accidentally looked at the version before your recent
changes.  The keyword is already better.

> I guess we could use #+INDEX instead, but it would require to add an
> information specific to Texinfo (index type), which would probably
> defeat the simplicity of the solution.

Either is fine.  Though I don’t think it’s less simple to have a key.

   #+index: key :type cindex.

Rasmus

-- 
This is the kind of tedious nonsense up with which I will not put

Re: template for writing Emacs manuals in Org

[Eric Abrahamsen]

"Thomas S. Dye" <tsd@tsdye.com> writes:

> Rasmus writes:
>
>> Once upon a time Tom ported the Org manual.  It's on his github, probably
>> under tsdye.
>
> https://github.com/tsdye/orgmanual

Hey, that's perfect! Dunno if that's what I was remembering, but that's
exactly what I was after. Even better if it ends up in contrib/

Off to copy and paste now...

E

Re: template for writing Emacs manuals in Org

[Thomas S. Dye]

Aloha Eric,

Eric Abrahamsen writes:

> "Thomas S. Dye" <tsd@tsdye.com> writes:
>
>> Rasmus writes:
>>
>>> Once upon a time Tom ported the Org manual.  It's on his github, probably
>>> under tsdye.
>>
>> https://github.com/tsdye/orgmanual
>
> Hey, that's perfect! Dunno if that's what I was remembering, but that's
> exactly what I was after. Even better if it ends up in contrib/
>
> Off to copy and paste now...

I hope you find it useful.  Still, I'd be interested to see Oleh
Krehel's approach.  It is bound to be more sophisticated than mine.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: template for writing Emacs manuals in Org

[Eric Abrahamsen]

"Thomas S. Dye" <tsd@tsdye.com> writes:

> Aloha Eric,
>
> Eric Abrahamsen writes:
>
>> "Thomas S. Dye" <tsd@tsdye.com> writes:
>>
>>> Rasmus writes:
>>>
>>>> Once upon a time Tom ported the Org manual.  It's on his github, probably
>>>> under tsdye.
>>>
>>> https://github.com/tsdye/orgmanual
>>
>> Hey, that's perfect! Dunno if that's what I was remembering, but that's
>> exactly what I was after. Even better if it ends up in contrib/
>>
>> Off to copy and paste now...
>
> I hope you find it useful.  Still, I'd be interested to see Oleh
> Krehel's approach.  It is bound to be more sophisticated than mine.

Well, we can cobble something together :) Mostly I was interested in the
index macros -- Info manuals are far more useful with indexes, and to be
honest I was doing anything to avoid learning how to write texinfo.

What might be nice to have in contrib is an exporter derived from the
current texinfo exporter, but specifically set up for Gnu project
manuals: so it does the copyright header, and index macros, and maybe
even the proper DIR integration (?).

I remember where I originally saw this: it was a long thread on
emacs.devel about moving documentation to HTML, which struck me as a
terrible idea. I think Org was raised as a way of lowering the barrier
to writing texinfo manuals for packages, so that we get the best of both
worlds: write in Org, read in Info. I think it would be a great idea to
facilitate that, if possible.

E

Re: template for writing Emacs manuals in Org

[Rasmus]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> What might be nice to have in contrib is an exporter derived from the
> current texinfo exporter, but specifically set up for Gnu project
> manuals: so it does the copyright header, and index macros, and maybe
> even the proper DIR integration (?).

Maybe a "GNU template" would be enough? (template as in C-e #).

> I remember where I originally saw this: it was a long thread on
> emacs.devel about moving documentation to HTML, which struck me as a
> terrible idea. I think Org was raised as a way of lowering the barrier
> to writing texinfo manuals for packages, so that we get the best of both
> worlds: write in Org, read in Info. I think it would be a great idea to
> facilitate that, if possible.

There's a recap here:

        https://lwn.net/Articles/625072/

Rasmus

-- 
To err is human. To screw up 10⁶ times per second, you need a computer

Re: template for writing Emacs manuals in Org

[Eric Abrahamsen]

Rasmus <rasmus@gmx.us> writes:

> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> What might be nice to have in contrib is an exporter derived from the
>> current texinfo exporter, but specifically set up for Gnu project
>> manuals: so it does the copyright header, and index macros, and maybe
>> even the proper DIR integration (?).
>
> Maybe a "GNU template" would be enough? (template as in C-e #).

Yup, that would do it. I think the main thing is just advertising, in
some way, that Org is a suitable authoring tool for Gnus manuals, and
making it as easy as possible.

>> I remember where I originally saw this: it was a long thread on
>> emacs.devel about moving documentation to HTML, which struck me as a
>> terrible idea. I think Org was raised as a way of lowering the barrier
>> to writing texinfo manuals for packages, so that we get the best of both
>> worlds: write in Org, read in Info. I think it would be a great idea to
>> facilitate that, if possible.
>
> There's a recap here:
>
>         https://lwn.net/Articles/625072/

Oof, that was depressing to revisit.

Re: template for writing Emacs manuals in Org

[Phillip Lord]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> "Thomas S. Dye" <tsd@tsdye.com> writes:
>
>> Aloha Eric,
>>
>> Eric Abrahamsen writes:
>>
>>> "Thomas S. Dye" <tsd@tsdye.com> writes:
>>>
>>>> Rasmus writes:
>>>>
>>>>> Once upon a time Tom ported the Org manual.  It's on his github, probably
>>>>> under tsdye.
>>>>
>>>> https://github.com/tsdye/orgmanual
>>>
> I remember where I originally saw this: it was a long thread on
> emacs.devel about moving documentation to HTML, which struck me as a
> terrible idea. I think Org was raised as a way of lowering the barrier
> to writing texinfo manuals for packages, so that we get the best of both
> worlds: write in Org, read in Info. I think it would be a great idea to
> facilitate that, if possible.


I still have a desire to take this forward, although lack the time to do
so on my own.

Having org generate texinfo that plugs directly into existing manuals
would be nice (as it would allow a piecemeal translation). Helping to
define a new HTML based representation (with adding semantics) that
would add the features of info to HTML (and the features of HTML to
info!) would be the ultimate. org-info.js is some of the way there
already.

Then we could use any kind of source (besides org) to generate the HTML,
and hopefully, have it all work together.

Phil

Re: template for writing Emacs manuals in Org

[Ciaran Mulloy]

I'm coming a little late to this thread so apologies!

Most of the previous thread has focused on analysing the various pros
and cons of the various documentation methods, INFOText/html/org, to
produce the final documentation.

I would like to suggest that whatever method is used that
it also supports the development workflow cycle of emacs. Core features
that are documented should also have corresponding testplans.

John Wiegley makes this point in his in his YouTube talk with Sacha Chua
https://www.youtube.com/watch?v=nUjgKoOYxos.  He concisely
summed up the workflow issue as 'bugs/tests/documentation'. 
It was one of the areas that needed more effort.

The challenge is to elegantly manage the documentation process so that
it caters for the complete workflow development cycle.

I favour the use of org as it has the capability of embedding tests
within the documentation, among other things.

Ciaran