* template for writing Emacs manuals in Org
@ 2016-05-14 7:21 Eric Abrahamsen
2016-05-16 17:37 ` Kaushal Modi
` (2 more replies)
0 siblings, 3 replies; 24+ messages in thread
From: Eric Abrahamsen @ 2016-05-14 7:21 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 24+ messages in thread* Re: template for writing Emacs manuals in Org
2016-05-14 7:21 template for writing Emacs manuals in Org Eric Abrahamsen
@ 2016-05-16 17:37 ` Kaushal Modi
2016-05-16 17:55 ` John Hendy
2016-05-16 18:08 ` Rasmus
2 siblings, 0 replies; 24+ messages in thread
From: Kaushal Modi @ 2016-05-16 17:37 UTC (permalink / raw)
To: Eric Abrahamsen, emacs-org list, Oleh Krehel
[-- 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 --]
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-14 7:21 template for writing Emacs manuals in Org Eric Abrahamsen
2016-05-16 17:37 ` Kaushal Modi
@ 2016-05-16 17:55 ` John Hendy
2016-05-16 18:08 ` Rasmus
2 siblings, 0 replies; 24+ messages in thread
From: John Hendy @ 2016-05-16 17:55 UTC (permalink / raw)
To: Eric Abrahamsen; +Cc: emacs-orgmode
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
>
>
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-14 7:21 template for writing Emacs manuals in Org Eric Abrahamsen
2016-05-16 17:37 ` Kaushal Modi
2016-05-16 17:55 ` John Hendy
@ 2016-05-16 18:08 ` Rasmus
2016-05-16 18:40 ` Thomas S. Dye
2 siblings, 1 reply; 24+ messages in thread
From: Rasmus @ 2016-05-16 18:08 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-16 18:08 ` Rasmus
@ 2016-05-16 18:40 ` Thomas S. Dye
2016-05-16 20:02 ` Nicolas Goaziou
2016-05-17 0:23 ` Eric Abrahamsen
0 siblings, 2 replies; 24+ messages in thread
From: Thomas S. Dye @ 2016-05-16 18:40 UTC (permalink / raw)
To: Rasmus; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-16 18:40 ` Thomas S. Dye
@ 2016-05-16 20:02 ` Nicolas Goaziou
2016-05-16 21:33 ` Thomas S. Dye
2016-05-17 0:23 ` Eric Abrahamsen
1 sibling, 1 reply; 24+ messages in thread
From: Nicolas Goaziou @ 2016-05-16 20:02 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: emacs-orgmode, Rasmus
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-16 20:02 ` Nicolas Goaziou
@ 2016-05-16 21:33 ` Thomas S. Dye
2016-05-17 5:52 ` Nicolas Goaziou
0 siblings, 1 reply; 24+ messages in thread
From: Thomas S. Dye @ 2016-05-16 21:33 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: emacs-orgmode, Rasmus
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-16 21:33 ` Thomas S. Dye
@ 2016-05-17 5:52 ` Nicolas Goaziou
2016-05-17 14:44 ` Thomas S. Dye
0 siblings, 1 reply; 24+ messages in thread
From: Nicolas Goaziou @ 2016-05-17 5:52 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: emacs-orgmode, Rasmus
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-17 5:52 ` Nicolas Goaziou
@ 2016-05-17 14:44 ` Thomas S. Dye
2016-05-17 15:37 ` Nicolas Goaziou
0 siblings, 1 reply; 24+ messages in thread
From: Thomas S. Dye @ 2016-05-17 14:44 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: emacs-orgmode, Rasmus
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-17 14:44 ` Thomas S. Dye
@ 2016-05-17 15:37 ` Nicolas Goaziou
2016-05-17 18:36 ` Thomas S. Dye
0 siblings, 1 reply; 24+ messages in thread
From: Nicolas Goaziou @ 2016-05-17 15:37 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: emacs-orgmode, Rasmus
"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,
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-17 15:37 ` Nicolas Goaziou
@ 2016-05-17 18:36 ` Thomas S. Dye
2016-05-17 18:56 ` Charles C. Berry
2016-05-17 18:56 ` Nick Dokos
0 siblings, 2 replies; 24+ messages in thread
From: Thomas S. Dye @ 2016-05-17 18:36 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: emacs-orgmode, Rasmus
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-17 18:36 ` Thomas S. Dye
@ 2016-05-17 18:56 ` Charles C. Berry
2016-05-17 18:56 ` Nick Dokos
1 sibling, 0 replies; 24+ messages in thread
From: Charles C. Berry @ 2016-05-17 18:56 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: emacs-orgmode, Rasmus, Nicolas Goaziou
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-17 18:36 ` Thomas S. Dye
2016-05-17 18:56 ` Charles C. Berry
@ 2016-05-17 18:56 ` Nick Dokos
2016-05-18 9:21 ` Rasmus
1 sibling, 1 reply; 24+ messages in thread
From: Nick Dokos @ 2016-05-17 18:56 UTC (permalink / raw)
To: emacs-orgmode
"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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-17 18:56 ` Nick Dokos
@ 2016-05-18 9:21 ` Rasmus
2016-05-18 14:56 ` Jonathan Leech-Pepin
0 siblings, 1 reply; 24+ messages in thread
From: Rasmus @ 2016-05-18 9:21 UTC (permalink / raw)
To: emacs-orgmode
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
--
ツ
^ permalink raw reply [flat|nested] 24+ messages in thread* Re: template for writing Emacs manuals in Org
2016-05-18 9:21 ` Rasmus
@ 2016-05-18 14:56 ` Jonathan Leech-Pepin
2016-05-18 16:20 ` Nicolas Goaziou
0 siblings, 1 reply; 24+ messages in thread
From: Jonathan Leech-Pepin @ 2016-05-18 14:56 UTC (permalink / raw)
To: Rasmus, emacs-orgmode
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
^ permalink raw reply [flat|nested] 24+ messages in thread* Re: template for writing Emacs manuals in Org
2016-05-18 14:56 ` Jonathan Leech-Pepin
@ 2016-05-18 16:20 ` Nicolas Goaziou
2016-05-18 16:43 ` Rasmus
0 siblings, 1 reply; 24+ messages in thread
From: Nicolas Goaziou @ 2016-05-18 16:20 UTC (permalink / raw)
To: Jonathan Leech-Pepin; +Cc: emacs-orgmode, Rasmus
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
^ permalink raw reply [flat|nested] 24+ messages in thread* Re: template for writing Emacs manuals in Org
2016-05-18 16:20 ` Nicolas Goaziou
@ 2016-05-18 16:43 ` Rasmus
0 siblings, 0 replies; 24+ messages in thread
From: Rasmus @ 2016-05-18 16:43 UTC (permalink / raw)
To: jonathan.leechpepin; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-16 18:40 ` Thomas S. Dye
2016-05-16 20:02 ` Nicolas Goaziou
@ 2016-05-17 0:23 ` Eric Abrahamsen
2016-05-17 3:32 ` Thomas S. Dye
1 sibling, 1 reply; 24+ messages in thread
From: Eric Abrahamsen @ 2016-05-17 0:23 UTC (permalink / raw)
To: emacs-orgmode
"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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-17 0:23 ` Eric Abrahamsen
@ 2016-05-17 3:32 ` Thomas S. Dye
2016-05-17 4:16 ` Eric Abrahamsen
0 siblings, 1 reply; 24+ messages in thread
From: Thomas S. Dye @ 2016-05-17 3:32 UTC (permalink / raw)
To: Eric Abrahamsen; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-17 3:32 ` Thomas S. Dye
@ 2016-05-17 4:16 ` Eric Abrahamsen
2016-05-17 7:35 ` Rasmus
2016-05-17 13:24 ` Phillip Lord
0 siblings, 2 replies; 24+ messages in thread
From: Eric Abrahamsen @ 2016-05-17 4:16 UTC (permalink / raw)
To: emacs-orgmode
"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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-17 4:16 ` Eric Abrahamsen
@ 2016-05-17 7:35 ` Rasmus
2016-05-17 8:34 ` Eric Abrahamsen
2016-05-17 13:24 ` Phillip Lord
1 sibling, 1 reply; 24+ messages in thread
From: Rasmus @ 2016-05-17 7:35 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 24+ messages in thread* Re: template for writing Emacs manuals in Org
2016-05-17 7:35 ` Rasmus
@ 2016-05-17 8:34 ` Eric Abrahamsen
0 siblings, 0 replies; 24+ messages in thread
From: Eric Abrahamsen @ 2016-05-17 8:34 UTC (permalink / raw)
To: emacs-orgmode
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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-17 4:16 ` Eric Abrahamsen
2016-05-17 7:35 ` Rasmus
@ 2016-05-17 13:24 ` Phillip Lord
2016-05-18 23:59 ` Ciaran Mulloy
1 sibling, 1 reply; 24+ messages in thread
From: Phillip Lord @ 2016-05-17 13:24 UTC (permalink / raw)
To: Eric Abrahamsen; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* Re: template for writing Emacs manuals in Org
2016-05-17 13:24 ` Phillip Lord
@ 2016-05-18 23:59 ` Ciaran Mulloy
0 siblings, 0 replies; 24+ messages in thread
From: Ciaran Mulloy @ 2016-05-18 23:59 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 24+ messages in thread
end of thread, other threads:[~2016-05-18 23:59 UTC | newest]
Thread overview: 24+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-05-14 7:21 template for writing Emacs manuals in Org Eric Abrahamsen
2016-05-16 17:37 ` Kaushal Modi
2016-05-16 17:55 ` John Hendy
2016-05-16 18:08 ` Rasmus
2016-05-16 18:40 ` Thomas S. Dye
2016-05-16 20:02 ` Nicolas Goaziou
2016-05-16 21:33 ` Thomas S. Dye
2016-05-17 5:52 ` Nicolas Goaziou
2016-05-17 14:44 ` Thomas S. Dye
2016-05-17 15:37 ` Nicolas Goaziou
2016-05-17 18:36 ` Thomas S. Dye
2016-05-17 18:56 ` Charles C. Berry
2016-05-17 18:56 ` Nick Dokos
2016-05-18 9:21 ` Rasmus
2016-05-18 14:56 ` Jonathan Leech-Pepin
2016-05-18 16:20 ` Nicolas Goaziou
2016-05-18 16:43 ` Rasmus
2016-05-17 0:23 ` Eric Abrahamsen
2016-05-17 3:32 ` Thomas S. Dye
2016-05-17 4:16 ` Eric Abrahamsen
2016-05-17 7:35 ` Rasmus
2016-05-17 8:34 ` Eric Abrahamsen
2016-05-17 13:24 ` Phillip Lord
2016-05-18 23:59 ` Ciaran Mulloy
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).