Re: [O] template for writing Emacs manuals in Org
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
Re: [O] template for writing Emacs manuals in Org
Nicolas Goaziou writes: > Hello, > > Jonathan Leech-Pepin 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 <> 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: [O] template for writing Emacs manuals in Org
Hello, Jonathan Leech-Pepin 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: [O] template for writing Emacs manuals in Org
Hi, On May 18, 2016 5:21:06 AM EDT, Rasmus wrote: >Hi, > >Nick Dokos 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: [O] template for writing Emacs manuals in Org
Hi, Nick Dokos 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: [O] template for writing Emacs manuals in Org
On Tue, 17 May 2016, Thomas S. Dye wrote: Aloha Nicolas, Nicolas Goaziou writes: "Thomas S. Dye" 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: [O] template for writing Emacs manuals in Org
"Thomas S. Dye" writes: > Aloha Nicolas, > > Nicolas Goaziou writes: > >> "Thomas S. Dye" 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: [O] template for writing Emacs manuals in Org
Aloha Nicolas, Nicolas Goaziou writes: > "Thomas S. Dye" 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: [O] template for writing Emacs manuals in Org
"Thomas S. Dye" 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: [O] template for writing Emacs manuals in Org
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: [O] template for writing Emacs manuals in Org
Eric Abrahamsen writes: > "Thomas S. Dye" writes: > >> Aloha Eric, >> >> Eric Abrahamsen writes: >> >>> "Thomas S. Dye" 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: [O] template for writing Emacs manuals in Org
Rasmus writes: > Eric Abrahamsen 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: [O] template for writing Emacs manuals in Org
Eric Abrahamsen 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: [O] template for writing Emacs manuals in Org
Hello, "Thomas S. Dye" 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: [O] template for writing Emacs manuals in Org
"Thomas S. Dye" writes: > Aloha Eric, > > Eric Abrahamsen writes: > >> "Thomas S. Dye" 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: [O] template for writing Emacs manuals in Org
Aloha Eric, Eric Abrahamsen writes: > "Thomas S. Dye" 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: [O] template for writing Emacs manuals in Org
"Thomas S. Dye" 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: [O] template for writing Emacs manuals in Org
Aloha Nicolas, Nicolas Goaziou writes: > Hello, > > "Thomas S. Dye" 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: [O] template for writing Emacs manuals in Org
Hello, "Thomas S. Dye" 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: [O] template for writing Emacs manuals in Org
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: [O] template for writing Emacs manuals in Org
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 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: [O] template for writing Emacs manuals in Org
Eric Abrahamsen 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: [O] template for writing Emacs manuals in Org
Copying Oleh as I believe he uses org to generate Info manual for his ivy package. -- -- Kaushal Modi
[O] template for writing Emacs manuals in Org
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