* Re: [RFC] Dog food, anyone?
2017-12-17 10:34 [RFC] Dog food, anyone? Nicolas Goaziou
@ 2017-12-17 11:59 ` Vikas Rawal
2017-12-17 18:41 ` Thomas S. Dye
` (8 subsequent siblings)
9 siblings, 0 replies; 40+ messages in thread
From: Vikas Rawal @ 2017-12-17 11:59 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: org-mode mailing list
>
> The task started by Thomas S. Dye a couple years ago is now complete.
> The "manual.org" file in "contrib/" directory is an up-to-date,
> sometimes enhanced, version of the Org manual. Org can now eat its own
> dog food.
>
This gives us a complex org file written by some of the finest orgers. Much to learn from this file.
Thanks to everyone who contributed to this.
Vikas
^ permalink raw reply [flat|nested] 40+ messages in thread* Re: [RFC] Dog food, anyone?
2017-12-17 10:34 [RFC] Dog food, anyone? Nicolas Goaziou
2017-12-17 11:59 ` Vikas Rawal
@ 2017-12-17 18:41 ` Thomas S. Dye
2017-12-17 19:01 ` Nicolas Goaziou
2017-12-17 18:51 ` Kaushal Modi
` (7 subsequent siblings)
9 siblings, 1 reply; 40+ messages in thread
From: Thomas S. Dye @ 2017-12-17 18:41 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
Aloha Nicolas,
It's a real pleasure to know that Org can now eat its own dog food (and
to see Carsten's memorable phrase on the Org mode list again). Many
thanks for picking up this orphaned project. I look forward to the day
it serves as the source for org.texi.
When I was working on the project several years ago, I didn't notice any
constraints introduced by Jonathan Leech-Pepin's ox-texinfo. For me, the
hard part was trying to synchronize with the on-going changes to
org.texi, which quickly defeated my best efforts. Have you figured out
how to automate that?
All the best,
Tom
Nicolas Goaziou writes:
> Hello,
>
> The task started by Thomas S. Dye a couple years ago is now complete.
> The "manual.org" file in "contrib/" directory is an up-to-date,
> sometimes enhanced, version of the Org manual. Org can now eat its own
> dog food.
>
> During the process, I had to re-organize some parts of the manual (e.g.,
> "Working with source code" section, the concept index...) and improve
> the "texinfo" export back-end, which was not up to the task when Thomas
> started it.
>
> Ultimately, this file is going to serve as the source for a new
> "org.texi". IOW, it could go into "doc/" and "make info" should export
> "manual.org" to "org.texi". First, however, it would be nice to review
> it, either as an Org file, or within the Info viewer, with
>
> (require 'ox-texinfo)
>
> and
>
> `C-c C-e i o' from "manual.org".
>
> Note that Info output is expected to be sometimes different from the
> current manual. This is not a 1:1 conversion.
>
> Feedback welcome!
>
>
> Regards,
--
Thomas S. Dye
http://www.tsdye.com
^ permalink raw reply [flat|nested] 40+ messages in thread* Re: [RFC] Dog food, anyone?
2017-12-17 18:41 ` Thomas S. Dye
@ 2017-12-17 19:01 ` Nicolas Goaziou
2017-12-17 21:58 ` Thomas S. Dye
0 siblings, 1 reply; 40+ messages in thread
From: Nicolas Goaziou @ 2017-12-17 19:01 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: Org Mode List
Hello,
"Thomas S. Dye" <tsd@tsdye.com> writes:
> When I was working on the project several years ago, I didn't notice any
> constraints introduced by Jonathan Leech-Pepin's ox-texinfo. For me, the
> hard part was trying to synchronize with the on-going changes to
> org.texi, which quickly defeated my best efforts. Have you figured out
> how to automate that?
Once manual.org is the official source for org.texi, there is no need to
modify "org.texi" directly. Only the occasional back-port from upstream
requires to do so, which is very manageable.
Do you foresee any difficulty?
Regards,
--
Nicolas Goaziou
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-17 19:01 ` Nicolas Goaziou
@ 2017-12-17 21:58 ` Thomas S. Dye
2017-12-17 23:03 ` Adrian Bradd
2017-12-17 23:44 ` Nicolas Goaziou
0 siblings, 2 replies; 40+ messages in thread
From: Thomas S. Dye @ 2017-12-17 21:58 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
Aloha Nicolas,
Nicolas Goaziou writes:
> Once manual.org is the official source for org.texi, there is no need to
> modify "org.texi" directly. Only the occasional back-port from upstream
> requires to do so, which is very manageable.
>
> Do you foresee any difficulty?
No, once manual.org is the official source for org.texi, there shouldn't
be any difficulty AFAICT.
My concern is with the time between a working manual.org and when it
becomes the official source. IIRC, I wasn't able to get a commitment to
make manual.org the official source, so was looking at an open-ended
future of what I considered arduous maintenance, without any real hope
the project might succeed. Perhaps you have that wrinkle ironed out?
BTW, I wasn't able to export manual.org using Org mode version 9.1.4
(9.1.4-elpaplus @ /Users/dk/.emacs.d/elpa/org-plus-contrib-20171205/).
It fails with this message:
format: Symbol’s value as variable is void: M-x
Does it depend on a more recent Org mode?
All the best,
Tom
--
Thomas S. Dye
http://www.tsdye.com
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-17 21:58 ` Thomas S. Dye
@ 2017-12-17 23:03 ` Adrian Bradd
2017-12-18 1:13 ` Thomas S. Dye
2017-12-17 23:44 ` Nicolas Goaziou
1 sibling, 1 reply; 40+ messages in thread
From: Adrian Bradd @ 2017-12-17 23:03 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: Org Mode List, Nicolas Goaziou
Thanks for this. I think having the manual in org format is a great idea.
Thomas S. Dye <tsd@tsdye.com> writes:
> My concern is with the time between a working manual.org and when it
> becomes the official source. IIRC, I wasn't able to get a commitment to
> make manual.org the official source, so was looking at an open-ended
> future of what I considered arduous maintenance, without any real hope
> the project might succeed. Perhaps you have that wrinkle ironed out?
I support the move to manual.org. If there are concerns about the
quality of the manual.org file and its exported .texi manual that
prevent it from becoming the master source one could ask contributors to
add information to both the .texi and .org file until the final
conversion is made. At the very least this would prevent an individual
from taking all the load.
Was there resistance to the move to manual.org previously? Or was the
issue one of apathy?
> BTW, I wasn't able to export manual.org using Org mode version 9.1.4
> (9.1.4-elpaplus @ /Users/dk/.emacs.d/elpa/org-plus-contrib-20171205/).
> It fails with this message:
>
> format: Symbol’s value as variable is void: M-x
>
> Does it depend on a more recent Org mode?
Export worked for me on Org mode version 9.1.4
(9.1.4-2-g118753-elpaplus).
Cheers,
--
Adrian
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-17 23:03 ` Adrian Bradd
@ 2017-12-18 1:13 ` Thomas S. Dye
0 siblings, 0 replies; 40+ messages in thread
From: Thomas S. Dye @ 2017-12-18 1:13 UTC (permalink / raw)
To: Adrian Bradd; +Cc: Org Mode List, Nicolas Goaziou
Aloha Adrian,
Adrian Bradd writes:
>
> I support the move to manual.org. If there are concerns about the
> quality of the manual.org file and its exported .texi manual that
> prevent it from becoming the master source one could ask contributors to
> add information to both the .texi and .org file until the final
> conversion is made. At the very least this would prevent an individual
> from taking all the load.
>
> Was there resistance to the move to manual.org previously? Or was the
> issue one of apathy?
I don't know exactly. I think there were legitimate concerns at the
time that manual.org required more work to produce a standard org.texi,
and some doubt whether it would indeed be possible.
I don't think apathy was a factor. IIRC, there was a lot of support for
the idea, including Carsten's hope that Org mode could "eat it's own dog
food."
All the best,
Tom
--
Thomas S. Dye
http://www.tsdye.com
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-17 21:58 ` Thomas S. Dye
2017-12-17 23:03 ` Adrian Bradd
@ 2017-12-17 23:44 ` Nicolas Goaziou
2017-12-18 1:15 ` Vikas Rawal
2017-12-18 1:23 ` Thomas S. Dye
1 sibling, 2 replies; 40+ messages in thread
From: Nicolas Goaziou @ 2017-12-17 23:44 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: Org Mode List
"Thomas S. Dye" <tsd@tsdye.com> writes:
> My concern is with the time between a working manual.org and when it
> becomes the official source. IIRC, I wasn't able to get a commitment to
> make manual.org the official source, so was looking at an open-ended
> future of what I considered arduous maintenance, without any real hope
> the project might succeed. Perhaps you have that wrinkle ironed out?
Not really. But the shift is a step forward. It cannot see how that
could fail (famous last words).
> BTW, I wasn't able to export manual.org using Org mode version 9.1.4
> (9.1.4-elpaplus @ /Users/dk/.emacs.d/elpa/org-plus-contrib-20171205/).
> It fails with this message:
>
> format: Symbol’s value as variable is void: M-x
>
> Does it depend on a more recent Org mode?
The file is in master branch. You need to use that to export it.
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-17 23:44 ` Nicolas Goaziou
@ 2017-12-18 1:15 ` Vikas Rawal
2017-12-18 1:23 ` Thomas S. Dye
1 sibling, 0 replies; 40+ messages in thread
From: Vikas Rawal @ 2017-12-18 1:15 UTC (permalink / raw)
To: org-mode mailing list; +Cc: Nicolas Goaziou
[-- Attachment #1: Type: text/plain, Size: 518 bytes --]
>
>> BTW, I wasn't able to export manual.org using Org mode version 9.1.4
>> (9.1.4-elpaplus @ /Users/dk/.emacs.d/elpa/org-plus-contrib-20171205/).
>> It fails with this message:
>>
>> format: Symbol’s value as variable is void: M-x
>>
>> Does it depend on a more recent Org mode?
>
> The file is in master branch. You need to use that to export it.
>
Why do I have orgmanual.org <http://orgmanual.org/> and not manual.org <http://manual.org/>? My git repo is up to date with origin/master.
V.
[-- Attachment #2: Type: text/html, Size: 1133 bytes --]
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-17 23:44 ` Nicolas Goaziou
2017-12-18 1:15 ` Vikas Rawal
@ 2017-12-18 1:23 ` Thomas S. Dye
1 sibling, 0 replies; 40+ messages in thread
From: Thomas S. Dye @ 2017-12-18 1:23 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
Aloha Nicolas,
Nicolas Goaziou writes:
> "Thomas S. Dye" <tsd@tsdye.com> writes:
>
>> My concern is with the time between a working manual.org and when it
>> becomes the official source. IIRC, I wasn't able to get a commitment to
>> make manual.org the official source, so was looking at an open-ended
>> future of what I considered arduous maintenance, without any real hope
>> the project might succeed. Perhaps you have that wrinkle ironed out?
>
> Not really. But the shift is a step forward. It cannot see how that
> could fail (famous last words).
:)
> The file is in master branch. You need to use that to export it.
Thanks.
All the best,
Tom
--
Thomas S. Dye
http://www.tsdye.com
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-17 10:34 [RFC] Dog food, anyone? Nicolas Goaziou
2017-12-17 11:59 ` Vikas Rawal
2017-12-17 18:41 ` Thomas S. Dye
@ 2017-12-17 18:51 ` Kaushal Modi
2017-12-17 19:27 ` Nicolas Goaziou
2017-12-17 18:58 ` [RFC] Official Org manual in Org! (Was: Dog food, anyone?) Kaushal Modi
` (6 subsequent siblings)
9 siblings, 1 reply; 40+ messages in thread
From: Kaushal Modi @ 2017-12-17 18:51 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
[-- Attachment #1: Type: text/plain, Size: 520 bytes --]
On Sun, Dec 17, 2017 at 5:35 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:
> Hello,
>
> The task started by Thomas S. Dye a couple years ago is now complete.
> The "manual.org" file in "contrib/" directory is an up-to-date,
> sometimes enhanced, version of the Org manual. Org can now eat its own
> dog food.
>
There are awesome news!
Would a template Org file be available that package authors can easily use
as a base to write their package manuals?
Many thanks! Will test it out next week.
--
Kaushal Modi
[-- Attachment #2: Type: text/html, Size: 1058 bytes --]
^ permalink raw reply [flat|nested] 40+ messages in thread* Re: [RFC] Dog food, anyone?
2017-12-17 18:51 ` Kaushal Modi
@ 2017-12-17 19:27 ` Nicolas Goaziou
0 siblings, 0 replies; 40+ messages in thread
From: Nicolas Goaziou @ 2017-12-17 19:27 UTC (permalink / raw)
To: Kaushal Modi; +Cc: Org Mode List
Hello,
Kaushal Modi <kaushal.modi@gmail.com> writes:
> Would a template Org file be available that package authors can easily use
> as a base to write their package manuals?
I'm not sure about what you mean by "template". Sure, there are a few
Texinfo specific sections (e.g., GNU Free Documentation License, Concept
index, Key index...) and a fancy macro (kbd), but otherwise it's
a straightforward file using standard Org syntax.
Anyway, time will tell.
Regards,
--
Nicolas Goaziou
^ permalink raw reply [flat|nested] 40+ messages in thread
* [RFC] Official Org manual in Org! (Was: Dog food, anyone?)
2017-12-17 10:34 [RFC] Dog food, anyone? Nicolas Goaziou
` (2 preceding siblings ...)
2017-12-17 18:51 ` Kaushal Modi
@ 2017-12-17 18:58 ` Kaushal Modi
2017-12-21 8:00 ` Marcin Borkowski
2017-12-17 23:10 ` [RFC] Dog food, anyone? Eric Abrahamsen
` (5 subsequent siblings)
9 siblings, 1 reply; 40+ messages in thread
From: Kaushal Modi @ 2017-12-17 18:58 UTC (permalink / raw)
To: emacs-org list
[-- Attachment #1: Type: text/plain, Size: 1868 bytes --]
Hi Nicholas,
Thanks for taking up this humongous project. It was a dream of many like me
to eventually read and maintain the Org manual in Org :)
To be honest, I discarded this email by instinct by just reading the title
"Dog food, anyone?", as I assumed that email to be from my neighborhood
community, with someone giving away their extra dog food (literally).. and
I don't own dogs.. so off the email went.. to my "read bin".. :)
It wasn't until few minutes back that I realized what this email was and
that it was actually on the Org list.. so changing the title for more
visibility.
This arduous task shouldn't go unrecognized.
---------- Forwarded message ---------
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Date: Sun, Dec 17, 2017 at 5:35 AM
Subject: [O] [RFC] Dog food, anyone?
To: Org Mode List <emacs-orgmode@gnu.org>
Hello,
The task started by Thomas S. Dye a couple years ago is now complete.
The "manual.org" file in "contrib/" directory is an up-to-date,
sometimes enhanced, version of the Org manual. Org can now eat its own
dog food.
During the process, I had to re-organize some parts of the manual (e.g.,
"Working with source code" section, the concept index...) and improve
the "texinfo" export back-end, which was not up to the task when Thomas
started it.
Ultimately, this file is going to serve as the source for a new
"org.texi". IOW, it could go into "doc/" and "make info" should export
"manual.org" to "org.texi". First, however, it would be nice to review
it, either as an Org file, or within the Info viewer, with
(require 'ox-texinfo)
and
`C-c C-e i o' from "manual.org".
Note that Info output is expected to be sometimes different from the
current manual. This is not a 1:1 conversion.
Feedback welcome!
Regards,
--
Nicolas Goaziou 0x80A93738
--
Kaushal Modi
[-- Attachment #2: Type: text/html, Size: 2834 bytes --]
^ permalink raw reply [flat|nested] 40+ messages in thread* Re: [RFC] Official Org manual in Org! (Was: Dog food, anyone?)
2017-12-17 18:58 ` [RFC] Official Org manual in Org! (Was: Dog food, anyone?) Kaushal Modi
@ 2017-12-21 8:00 ` Marcin Borkowski
2017-12-21 13:47 ` [RFC] Official Org manual in Org! Nicolas Goaziou
0 siblings, 1 reply; 40+ messages in thread
From: Marcin Borkowski @ 2017-12-21 8:00 UTC (permalink / raw)
To: Kaushal Modi; +Cc: emacs-org list
Hi all,
my 2 cents.
1. Now that we know that it is possible to construct a texi document
from org automatically, whould it be feasible to get back to the topic
of converting the Emacs manual(s) to org? Would it make sense?
2. Re: the style guide: why not ditch em-dashes altogether? Quoting
Robert Brighurst:
,----
| The em dash is the nineteenth-century standard, still prescribed by
| many editorial style books, but the em dash is too long for use with
| the best text faces. Like the oversized space between sentences, it
| belongs to the padded and corseted aesthetic of Victorian
| typography. Use spaced en dashes – rather than em dashes or hyphens –
| to set off phrases.
`----
In case you think this is not something of utmost importance: I quoted
Bringhurst after the article
http://www.denizcemonduygu.com/2009/09/where-to-use-en-and-em-dashes-lupton-vs-bringhurst/,
where this gem can be found:
,----
| The en dash between your birth and death dates on your headstone will
| be representing your whole life. All your joys and sorrows, adventures
| and disappointments, tucked in something slightly longer than a hyphen
| and shorter than an em dash. So go on ignoring them. The dashes will
| have the last word.
`----
Best,
Marcin
On 2017-12-17, at 19:58, Kaushal Modi <kaushal.modi@gmail.com> wrote:
> Hi Nicholas,
>
> Thanks for taking up this humongous project. It was a dream of many like me
> to eventually read and maintain the Org manual in Org :)
>
> To be honest, I discarded this email by instinct by just reading the title
> "Dog food, anyone?", as I assumed that email to be from my neighborhood
> community, with someone giving away their extra dog food (literally).. and
> I don't own dogs.. so off the email went.. to my "read bin".. :)
>
> It wasn't until few minutes back that I realized what this email was and
> that it was actually on the Org list.. so changing the title for more
> visibility.
>
> This arduous task shouldn't go unrecognized.
>
> ---------- Forwarded message ---------
> From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
> Date: Sun, Dec 17, 2017 at 5:35 AM
> Subject: [O] [RFC] Dog food, anyone?
> To: Org Mode List <emacs-orgmode@gnu.org>
>
>
> Hello,
>
> The task started by Thomas S. Dye a couple years ago is now complete.
> The "manual.org" file in "contrib/" directory is an up-to-date,
> sometimes enhanced, version of the Org manual. Org can now eat its own
> dog food.
>
> During the process, I had to re-organize some parts of the manual (e.g.,
> "Working with source code" section, the concept index...) and improve
> the "texinfo" export back-end, which was not up to the task when Thomas
> started it.
>
> Ultimately, this file is going to serve as the source for a new
> "org.texi". IOW, it could go into "doc/" and "make info" should export
> "manual.org" to "org.texi". First, however, it would be nice to review
> it, either as an Org file, or within the Info viewer, with
>
> (require 'ox-texinfo)
>
> and
>
> `C-c C-e i o' from "manual.org".
>
> Note that Info output is expected to be sometimes different from the
> current manual. This is not a 1:1 conversion.
>
> Feedback welcome!
>
>
> Regards,
>
> --
> Nicolas Goaziou 0x80A93738
--
Marcin Borkowski
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Official Org manual in Org!
2017-12-21 8:00 ` Marcin Borkowski
@ 2017-12-21 13:47 ` Nicolas Goaziou
0 siblings, 0 replies; 40+ messages in thread
From: Nicolas Goaziou @ 2017-12-21 13:47 UTC (permalink / raw)
To: Marcin Borkowski; +Cc: emacs-org list, Kaushal Modi
Hello,
Marcin Borkowski <mbork@mbork.pl> writes:
> 1. Now that we know that it is possible to construct a texi document
> from org automatically, whould it be feasible to get back to the topic
> of converting the Emacs manual(s) to org? Would it make sense?
I doubt Org will become the de facto standard for Emacs documentation.
Two co-existing formats imply maintenance burden.
In any case, this should probably be discussed on Emacs-devel ML.
> 2. Re: the style guide: why not ditch em-dashes altogether?
Even though you're preaching to the choir, I think the main argument in
favor of em-dashes is that GNU Emacs manual uses them. There should be
some typographic consistency between GNU manuals.
Regards,
--
Nicolas Goaziou
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-17 10:34 [RFC] Dog food, anyone? Nicolas Goaziou
` (3 preceding siblings ...)
2017-12-17 18:58 ` [RFC] Official Org manual in Org! (Was: Dog food, anyone?) Kaushal Modi
@ 2017-12-17 23:10 ` Eric Abrahamsen
2017-12-18 21:02 ` Thomas S. Dye
` (4 subsequent siblings)
9 siblings, 0 replies; 40+ messages in thread
From: Eric Abrahamsen @ 2017-12-17 23:10 UTC (permalink / raw)
To: emacs-orgmode
Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
> Hello,
>
> The task started by Thomas S. Dye a couple years ago is now complete.
> The "manual.org" file in "contrib/" directory is an up-to-date,
> sometimes enhanced, version of the Org manual. Org can now eat its own
> dog food.
Very cool! I look forward to learning from this, and will see if I can
spot any warts.
Nice work, all.
^ permalink raw reply [flat|nested] 40+ messages in thread* Re: [RFC] Dog food, anyone?
2017-12-17 10:34 [RFC] Dog food, anyone? Nicolas Goaziou
` (4 preceding siblings ...)
2017-12-17 23:10 ` [RFC] Dog food, anyone? Eric Abrahamsen
@ 2017-12-18 21:02 ` Thomas S. Dye
2017-12-18 22:04 ` Nicolas Goaziou
2017-12-19 20:16 ` Jonathan Leech-Pepin
` (3 subsequent siblings)
9 siblings, 1 reply; 40+ messages in thread
From: Thomas S. Dye @ 2017-12-18 21:02 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
[-- Attachment #1: Type: text/plain, Size: 1707 bytes --]
Aloha Nicolas,
Nicolas Goaziou writes:
>
> Ultimately, this file is going to serve as the source for a new
> "org.texi". IOW, it could go into "doc/" and "make info" should export
> "manual.org" to "org.texi". First, however, it would be nice to review
> it, either as an Org file, or within the Info viewer, with
>
> (require 'ox-texinfo)
>
> and
>
> `C-c C-e i o' from "manual.org".
I've spent a few hours with manual.org now and I like it very much. The
info file it produces looks clean to me and it compiled without a hitch
using Org mode from the master branch.
One change that might be made globally is the use of em-dash (---) to
set off text, versus en-dash (--) between numerals, e.g. "the range of
run times is 1--5 seconds". I've spotted several places where the
en-dash is used to set off text. See this web site for the convention
on dashes:
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Conventions.html
I appreciate your work on the chapter "Working with source code". I
think it is a big improvement over the original. The reorganization
seems effective to me, especially the integration of "Specific header
arguments" with the structural overview you provide in the first several
sections of the chapter. Thanks!
Attached, please find a patch with some copy editing to the introductory
section of the "Working with source code" chapter. The patch also
includes a correction for a typo elsewhere in the manual.
Like others on the list, I'm pleased by the prospect of being able to
contribute to the Org manual by editing an Org document. It is so much
easier for me than trying to work on org.texi!
Let me know if you have questions.
All the best,
Tom
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Edits to the introductory section of "Working with source code" --]
[-- Type: text/x-patch, Size: 7758 bytes --]
From dc10dff3adf49783ef82ad43338f04ceb888ebc3 Mon Sep 17 00:00:00 2001
From: tsdye <tsd@tsdye.com>
Date: Mon, 18 Dec 2017 10:21:11 -1000
Subject: [PATCH] Edit the introduction
---
contrib/manual.org | 123 +++++++++++++++++++++++++++--------------------------
1 file changed, 62 insertions(+), 61 deletions(-)
diff --git a/contrib/manual.org b/contrib/manual.org
index c497129e9..3781a57ec 100644
--- a/contrib/manual.org
+++ b/contrib/manual.org
@@ -15939,13 +15939,17 @@ keywords.
:END:
#+cindex: source code, working with
-Source code here refers to any code typed in Org documents. Org can
-manage source code in any Org file once such code is tagged with begin
-and end markers. Working with source code begins with tagging source
-code blocks. Tagged blocks are not restricted to the preamble or the
-end of an Org document; they can go anywhere -- with a few exceptions,
-such as not inside comments and fixed width areas. Here's a sample
-source code block in Emacs Lisp:
+Source code here refers to any plain text collection of computer
+instructions, possibly with comments, written using a human-readable
+programming language. Org can manage source code in an Org document
+when the source code is identified with begin and end markers.
+Working with source code begins with identifying source code blocks.
+A source code block can be placed almost anywhere in an Org document;
+it is not restricted to the preamble or the end of the
+document. However, Org cannot manage a source code block if it is
+placed inside an Org comment or within a fixed width section.
+
+Here is an example source code block in the Emacs Lisp language:
#+begin_example
,#+BEGIN_SRC emacs-lisp
@@ -15955,62 +15959,59 @@ source code block in Emacs Lisp:
,#+END_SRC
#+end_example
-Org can take the code in the block delimited by the =#+BEGIN_SRC=
-... =#+END_SRC= markup, and format, compile, execute, and show the
-results. Org can simplify many housekeeping tasks essential to modern
-code maintenance. That's why these blocks in Org mode literature are
-sometimes referred to as /live code/ blocks -- as compared to the
-static text and documentation around it. Users can control how live
-they want each block by tweaking the headers for compiling, execution,
-extraction.
-
-Org's source code block type is one of many block types, such as
-quote, export, verse, latex, example, and verbatim. This section
-pertains to blocks between =#+BEGIN_SRC= and =#+END_SRC=.
-
-For editing source code blocks, Org provides native Emacs major-modes.
-That leverages the latest Emacs features for that source code language
-mode.
-
-For exporting, Org can then extract source code blocks into compilable
-source files -- in a conversion process known as /tangling/ in
-literate programming terminology.
-
-For publishing, Org's back-ends can handle the code blocks and the
-text for output to a variety of formats with native syntax
-highlighting.
-
-For executing the source code in the code blocks, Org provides
-facilities that glue the tasks of compiling, collecting the results of
-the execution, and inserting them back to the Org file. Besides text
-output, results may include links to other data types that Emacs can
-handle: audio, video, and graphics.
-
-An important feature of Org's execution of the code blocks is passing
-variables, functions, and results between them. Such interoperability
-uses a common syntax even if these blocks are in different source code
-languages. The integration extends to linking the debugger's error
-messages to the line in the source code block in the Org file. That
-should partly explain why this functionality by the original
-contributors, Eric Schulte and Dan Davison, was called /Org Babel/.
-
-In literate programming, the main appeal is code and documentation
-co-existing in one file. Org mode takes this several steps further.
-First by enabling execution, and then by inserting results of that
-execution back into the Org file. Along the way, Org provides
-extensive formatting features, including handling tables. Org handles
-multiple source code languages in one file, and provides a common
-syntax for passing variables, functions, and results between source
-code blocks.
+Org can manage the source code in the block delimited by =#+BEGIN_SRC=
+... =#+END_SRC= in several ways that can simplify housekeeping tasks
+essential to modern source code maintenance. Org can edit, format,
+extract, export, and publish source code blocks. Org can also compile and
+execute a source code block, then capture the results. The Org mode
+literature sometimes refers to source code blocks as /live code/
+blocks because they can alter the content of the Org document or the
+material that it exports. Users can control how live they want each
+source code block by tweaking the [[*Using header arguments][header arguments]] for compiling,
+execution, extraction, and exporting.
+
+Source code blocks are one of many Org block types, which also include
+=quote=, =export=, =verse=, =latex=, =example=, and =verbatim=. This
+section pertains to blocks between =#+BEGIN_SRC= and =#+END_SRC=.
+
+For editing and formatting a source code block, Org uses an
+appropriate Emacs major-mode that includes features specifically
+designed for source code in that language.
+
+Org can extract one or more source code blocks and write them to one
+or more source files --- a process known as /tangling/ in literate
+programming terminology.
+
+For exporting and publishing, Org's back-ends can format a source code
+block appropriately, often with native syntax highlighting.
+
+For executing and compiling a source code block, the user can
+configure Org to select the appropriate compiler. Org provides
+facilities to collect the result of the execution or compiler output,
+insert it into the Org document, and/or export it. In addition to
+text results, Org can insert links to other data types, including
+audio, video, and graphics. Org can also link a compiler error message
+to the appropriate line in the source code block.
+
+An important feature of Org's management of source code blocks is the
+ability to pass variables, functions, and results to one another using
+a common syntax for source code blocks in any language. Although most
+literate programming facilities are restricted to one language or
+another, Org's language-agnostic approach lets the literate programmer
+match each programming task with the appropriate computer language and
+to mix them all together in a single Org document. This
+interoperability among languages explains why Org's source code
+management facility was named /Org Babel/ by its originators, Eric
+Schulte and Dan Davison.
Org mode fulfills the promise of easy verification and maintenance of
-publishing reproducible research by keeping all these in the same
-file: text, data, code, configuration settings of the execution
-environment, the results of the execution, and associated narratives,
-claims, references, and internal and external links.
+publishing reproducible research by keeping text, data, code,
+configuration settings of the execution environment, the results of
+the execution, and associated narratives, claims, references, and
+internal and external links in a single Org document.
-Details of Org's facilities for working with source code are shown
-next.
+Details of Org's facilities for working with source code are described
+in the following sections.
** Structure of code blocks
:PROPERTIES:
@@ -16046,7 +16047,7 @@ An inline code block conforms to this structure:
: src_<language>{<body>}
-#+teinfo: @noindent
+#+texinfo: @noindent
or
: src_<language>[<header arguments>]{<body>}
--
2.14.2
[-- Attachment #3: Type: text/plain, Size: 39 bytes --]
--
Thomas S. Dye
http://www.tsdye.com
^ permalink raw reply related [flat|nested] 40+ messages in thread* Re: [RFC] Dog food, anyone?
2017-12-18 21:02 ` Thomas S. Dye
@ 2017-12-18 22:04 ` Nicolas Goaziou
2017-12-19 0:12 ` Thomas S. Dye
0 siblings, 1 reply; 40+ messages in thread
From: Nicolas Goaziou @ 2017-12-18 22:04 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: Org Mode List
Hello,
"Thomas S. Dye" <tsd@tsdye.com> writes:
> I've spent a few hours with manual.org now and I like it very much. The
> info file it produces looks clean to me and it compiled without a hitch
> using Org mode from the master branch.
Great!
> One change that might be made globally is the use of em-dash (---) to
> set off text, versus en-dash (--) between numerals, e.g. "the range of
> run times is 1--5 seconds". I've spotted several places where the
> en-dash is used to set off text. See this web site for the convention
> on dashes:
>
> https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Conventions.html
I think it is a matter of "American English" vs "British English"
convention. See, e.g., <https://www.gsbe.co.uk/grammar-the-dash.html>.
I consistently used the latter because I find it more aesthetically
pleasing. As a GNU manual, we can switch to the American English
convention everywhere. In this case, however, em-dash are not
spaced-out.
In the same vein, we also need to use title case. This needs some
special care as fuzzy links need to be updated accordingly.
WDYT?
> Attached, please find a patch with some copy editing to the introductory
> section of the "Working with source code" chapter. The patch also
> includes a correction for a typo elsewhere in the manual.
Thank you. I applied it with the changes mentioned below.
> +Users can control how live they want each
> +source code block by tweaking the [[*Using header arguments][header arguments]] for compiling,
> +execution, extraction, and exporting.
I changed it to
... by tweaking the header arguments (see [[* Using header
arguments]]) for compiling...
For more information, see (info "(texinfo) @ref"), last paragraphs.
N.B.: I suggest to read it in regular info viewer, i.e., "info texinfo"
from the command line, instead of Emacs to make sense out of this.
> +Source code blocks are one of many Org block types, which also include
> +=quote=, =export=, =verse=, =latex=, =example=, and =verbatim=. This
> +section pertains to blocks between =#+BEGIN_SRC= and =#+END_SRC=.
> +
> +For editing and formatting a source code block, Org uses an
> +appropriate Emacs major-mode that includes features specifically
> +designed for source code in that language.
> +
> +Org can extract one or more source code blocks and write them to one
> +or more source files --- a process known as /tangling/ in literate
> +programming terminology.
I changed it to
... or more sources files---a process known as...
per above.
Regards,
--
Nicolas Goaziou 0x80A93738
^ permalink raw reply [flat|nested] 40+ messages in thread* Re: [RFC] Dog food, anyone?
2017-12-18 22:04 ` Nicolas Goaziou
@ 2017-12-19 0:12 ` Thomas S. Dye
2017-12-19 19:25 ` Nicolas Goaziou
0 siblings, 1 reply; 40+ messages in thread
From: Thomas S. Dye @ 2017-12-19 0:12 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
Aloha Nicolas,
Nicolas Goaziou writes:
>> One change that might be made globally is the use of em-dash (---) to
>> set off text, versus en-dash (--) between numerals, e.g. "the range of
>> run times is 1--5 seconds". I've spotted several places where the
>> en-dash is used to set off text. See this web site for the convention
>> on dashes:
>>
>> https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Conventions.html
>
> I think it is a matter of "American English" vs "British English"
> convention. See, e.g., <https://www.gsbe.co.uk/grammar-the-dash.html>.
>
> I consistently used the latter because I find it more aesthetically
> pleasing. As a GNU manual, we can switch to the American English
> convention everywhere. In this case, however, em-dash are not
> spaced-out.
I find the en-dash with spaces more aesthetically pleasing, too.
>
> In the same vein, we also need to use title case. This needs some
> special care as fuzzy links need to be updated accordingly.
>
> WDYT?
Agreed. This is one of the first things we might do if manual.org
becomes the official source of the Org manual.
FYI, Phil Rooke's Documentation_Standards.org suggests title case for
chapter heads and sentence case for section and subsection headings.
> I changed it to
>
> ... by tweaking the header arguments (see [[* Using header
> arguments]]) for compiling...
>
> For more information, see (info "(texinfo) @ref"), last paragraphs.
> N.B.: I suggest to read it in regular info viewer, i.e., "info texinfo"
> from the command line, instead of Emacs to make sense out of this.
Yes, much better.
All the best,
Tom
--
Thomas S. Dye
http://www.tsdye.com
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-19 0:12 ` Thomas S. Dye
@ 2017-12-19 19:25 ` Nicolas Goaziou
2017-12-19 20:11 ` Thomas S. Dye
0 siblings, 1 reply; 40+ messages in thread
From: Nicolas Goaziou @ 2017-12-19 19:25 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: Org Mode List
Hello,
"Thomas S. Dye" <tsd@tsdye.com> writes:
> I find the en-dash with spaces more aesthetically pleasing, too.
Unfortunately, Emacs manual thoroughly uses em-dash. We have to bite the
bullet, IMO.
I will change " -- " into "---" if there is no objection.
> Agreed. This is one of the first things we might do if manual.org
> becomes the official source of the Org manual.
>
> FYI, Phil Rooke's Documentation_Standards.org suggests title case for
> chapter heads and sentence case for section and subsection headings.
OTOH, Emacs manual seems to use title case at every level, barring some
exceptions (e.g., "Terminal emulator").
Maybe we should stick to title case to every heading that belong to
a menu, i.e., we can use sentence case for "notoc" headings.
Since Texinfo node names are derived from headlines, it means external
references to Org manual, if such thing exists, are going to break.
WDYT?
Regards,
--
Nicolas Goaziou
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-19 19:25 ` Nicolas Goaziou
@ 2017-12-19 20:11 ` Thomas S. Dye
0 siblings, 0 replies; 40+ messages in thread
From: Thomas S. Dye @ 2017-12-19 20:11 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
Aloha Nicolas,
Nicolas Goaziou writes:
> Hello,
>
> "Thomas S. Dye" <tsd@tsdye.com> writes:
>
>> I find the en-dash with spaces more aesthetically pleasing, too.
>
> Unfortunately, Emacs manual thoroughly uses em-dash. We have to bite the
> bullet, IMO.
>
> I will change " -- " into "---" if there is no objection.
No objection here.
>> Agreed. This is one of the first things we might do if manual.org
>> becomes the official source of the Org manual.
>>
>> FYI, Phil Rooke's Documentation_Standards.org suggests title case for
>> chapter heads and sentence case for section and subsection headings.
>
> OTOH, Emacs manual seems to use title case at every level, barring some
> exceptions (e.g., "Terminal emulator").
>
> Maybe we should stick to title case to every heading that belong to
> a menu, i.e., we can use sentence case for "notoc" headings.
>
> Since Texinfo node names are derived from headlines, it means external
> references to Org manual, if such thing exists, are going to break.
>
> WDYT?
I think we should identify and follow the appropriate style guide, but
I'm confused about what *is* the appropriate style guide.
The style guide for GNU documentation seems more about teaching coders
how to communicate with other humans and less about the nitty-gritty
style issues that send an editor to a guide like the Chicago Manual of
Style. See:
https://www.fsf.org/gnu-press/GNU-Press-styleguide.pdf
Note that the GNU style guide uses sentence case for section heads, and
em-dashes with spaces (" --- ")!
Of course, the TexInfo style guide I cited in an earlier post appears to
have conflicting advice about dashes :(
In the end, the important thing is consistency. A good document
"trains" its readers how to read it by hewing to a consistent standard.
My recommendation at this point is to follow Phil Rooke's style guide
and augment it where possible. If manual.org becomes the official source
for Org documentation, then it would be useful to "translate" Rooke's
guide to show how to achieve its style prescriptions using Org markup.
hth,
Tom
--
Thomas S. Dye
http://www.tsdye.com
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-17 10:34 [RFC] Dog food, anyone? Nicolas Goaziou
` (5 preceding siblings ...)
2017-12-18 21:02 ` Thomas S. Dye
@ 2017-12-19 20:16 ` Jonathan Leech-Pepin
2017-12-19 23:11 ` Nicolas Goaziou
[not found] ` <WM!57dfd1c25b2c2af3021c1294841c916968d326cf362c32864a6fbc9615cf19dba6ceadc1960e4c3ef5578687af476fba!@mailhub-mx1.ncl.ac.uk>
` (2 subsequent siblings)
9 siblings, 1 reply; 40+ messages in thread
From: Jonathan Leech-Pepin @ 2017-12-19 20:16 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
[-- Attachment #1: Type: text/plain, Size: 1113 bytes --]
Hello Nicolas
On 17 December 2017 at 05:34, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:
> Hello,
>
> The task started by Thomas S. Dye a couple years ago is now complete.
> The "manual.org" file in "contrib/" directory is an up-to-date,
> sometimes enhanced, version of the Org manual. Org can now eat its own
> dog food.
>
> During the process, I had to re-organize some parts of the manual (e.g.,
> "Working with source code" section, the concept index...) and improve
> the "texinfo" export back-end, which was not up to the task when Thomas
> started it.
>
As Thomas mentioned I had originally written the exporter. I'd done my best
to get it to work with the majority of the org.texi however there were
certain
features that did not seem to be present at the time in Org (or at least no
convenient method to simulate them without macros).
I haven't had the chance to keep up with the exporter or the export engine
in
general, however I'm glad that the manual now can be entirely written in
Org.
That was part of the motivation behind writing the exporter in the first
place.
Regards,
--
Jonathan
[-- Attachment #2: Type: text/html, Size: 1735 bytes --]
^ permalink raw reply [flat|nested] 40+ messages in thread* Re: [RFC] Dog food, anyone?
2017-12-19 20:16 ` Jonathan Leech-Pepin
@ 2017-12-19 23:11 ` Nicolas Goaziou
2017-12-20 0:05 ` Jonathan Leech-Pepin
0 siblings, 1 reply; 40+ messages in thread
From: Nicolas Goaziou @ 2017-12-19 23:11 UTC (permalink / raw)
To: Jonathan Leech-Pepin; +Cc: Org Mode List
Hello,
Jonathan Leech-Pepin <jonathan.leechpepin@gmail.com> writes:
> As Thomas mentioned I had originally written the exporter.
I know. You are credited as the author of ox-texinfo.el. Did I mention
otherwise?
> I'd done my best to get it to work with the majority of the org.texi
> however there were certain features that did not seem to be present at
> the time in Org (or at least no convenient method to simulate them
> without macros).
Just to prevent miscommunication, I wasn't criticizing your work when
I wrote I had improved the back-end.
Regards,
--
Nicolas Goaziou
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-19 23:11 ` Nicolas Goaziou
@ 2017-12-20 0:05 ` Jonathan Leech-Pepin
2017-12-20 0:59 ` Thomas S. Dye
0 siblings, 1 reply; 40+ messages in thread
From: Jonathan Leech-Pepin @ 2017-12-20 0:05 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
Hello,
On December 19, 2017 6:11:21 PM EST, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>Hello,
>
>Jonathan Leech-Pepin <jonathan.leechpepin@gmail.com> writes:
>
>> As Thomas mentioned I had originally written the exporter.
>
>I know. You are credited as the author of ox-texinfo.el. Did I mention
>otherwise?
>
It had partially sounded like you were saying both the backend and the work on manual.org were his. Might just have been a misinterpretation though.
>> I'd done my best to get it to work with the majority of the org.texi
>> however there were certain features that did not seem to be present
>at
>> the time in Org (or at least no convenient method to simulate them
>> without macros).
>
>Just to prevent miscommunication, I wasn't criticizing your work when
>I wrote I had improved the back-end.
>
I didn’t take it as criticism, when I’d started working on it the new export engine was still in it’s infancy and a lot of the work you’ve done to improve performance and parsing hadn’t occurred yet. I’m glad it was complete enough to let Thomas start his work and give you a basis for improving to allow for a full manual.
>Regards,
--
Jonathan
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-20 0:05 ` Jonathan Leech-Pepin
@ 2017-12-20 0:59 ` Thomas S. Dye
0 siblings, 0 replies; 40+ messages in thread
From: Thomas S. Dye @ 2017-12-20 0:59 UTC (permalink / raw)
To: Jonathan Leech-Pepin; +Cc: Org Mode List, Nicolas Goaziou
Aloha Jonathan,
Jonathan Leech-Pepin writes:
>>
>>Just to prevent miscommunication, I wasn't criticizing your work when
>>I wrote I had improved the back-end.
>>
>
> I didn’t take it as criticism, when I’d started working on it the new export engine was still in it’s infancy and a lot of the work you’ve done to improve performance and parsing hadn’t occurred yet. I’m glad it was complete enough to let Thomas start his work and give you a basis for improving to allow for a full manual.
I remember that working with you, and with your software, was a real
pleasure. Like you, I'm pleased our work provided some basis for
Nicolas' accomplishment.
All the best,
Tom
--
Thomas S. Dye
http://www.tsdye.com
^ permalink raw reply [flat|nested] 40+ messages in thread
[parent not found: <WM!57dfd1c25b2c2af3021c1294841c916968d326cf362c32864a6fbc9615cf19dba6ceadc1960e4c3ef5578687af476fba!@mailhub-mx1.ncl.ac.uk>]
* Re: [RFC] Dog food, anyone?
[not found] ` <WM!57dfd1c25b2c2af3021c1294841c916968d326cf362c32864a6fbc9615cf19dba6ceadc1960e4c3ef5578687af476fba!@mailhub-mx1.ncl.ac.uk>
@ 2017-12-21 12:58 ` Phillip Lord
2017-12-21 13:37 ` Nicolas Goaziou
0 siblings, 1 reply; 40+ messages in thread
From: Phillip Lord @ 2017-12-21 12:58 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
> Hello,
>
> The task started by Thomas S. Dye a couple years ago is now complete.
> The "manual.org" file in "contrib/" directory is an up-to-date,
> sometimes enhanced, version of the Org manual. Org can now eat its own
> dog food.
>
> During the process, I had to re-organize some parts of the manual (e.g.,
> "Working with source code" section, the concept index...) and improve
> the "texinfo" export back-end, which was not up to the task when Thomas
> started it.
Good stuff!
My question about this and your experiences with ox-texinfo, is would it
be possible to integrate this into a workflow where a manual was
converted piece-meal.
So, if a texinfo manual was multi-part (like the Emacs manual for
instance), it could be converted one file at a time, rather than having
to do the whole lot.
Phil
^ permalink raw reply [flat|nested] 40+ messages in thread* Re: [RFC] Dog food, anyone?
2017-12-21 12:58 ` Phillip Lord
@ 2017-12-21 13:37 ` Nicolas Goaziou
2017-12-21 17:26 ` Phillip Lord
0 siblings, 1 reply; 40+ messages in thread
From: Nicolas Goaziou @ 2017-12-21 13:37 UTC (permalink / raw)
To: Phillip Lord; +Cc: Org Mode List
Hello,
phillip.lord@russet.org.uk (Phillip Lord) writes:
> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> Hello,
>>
>> The task started by Thomas S. Dye a couple years ago is now complete.
>> The "manual.org" file in "contrib/" directory is an up-to-date,
>> sometimes enhanced, version of the Org manual. Org can now eat its own
>> dog food.
>>
>> During the process, I had to re-organize some parts of the manual (e.g.,
>> "Working with source code" section, the concept index...) and improve
>> the "texinfo" export back-end, which was not up to the task when Thomas
>> started it.
>
>
> Good stuff!
>
> My question about this and your experiences with ox-texinfo, is would it
> be possible to integrate this into a workflow where a manual was
> converted piece-meal.
>
> So, if a texinfo manual was multi-part (like the Emacs manual for
> instance), it could be converted one file at a time, rather than having
> to do the whole lot.
You can use #+INCLUDE keywords for that.
Regards,
--
Nicolas Goaziou 0x80A93738
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-21 13:37 ` Nicolas Goaziou
@ 2017-12-21 17:26 ` Phillip Lord
2017-12-21 19:53 ` Nicolas Goaziou
0 siblings, 1 reply; 40+ messages in thread
From: Phillip Lord @ 2017-12-21 17:26 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>> Good stuff!
>>
>> My question about this and your experiences with ox-texinfo, is would it
>> be possible to integrate this into a workflow where a manual was
>> converted piece-meal.
>>
>> So, if a texinfo manual was multi-part (like the Emacs manual for
>> instance), it could be converted one file at a time, rather than having
>> to do the whole lot.
>
> You can use #+INCLUDE keywords for that.
I was wondering the other way around. Can org produce .texi that
could be part of a larger existing texinfo. So, something that can be
@include'd.
Phil
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-17 10:34 [RFC] Dog food, anyone? Nicolas Goaziou
` (7 preceding siblings ...)
[not found] ` <WM!57dfd1c25b2c2af3021c1294841c916968d326cf362c32864a6fbc9615cf19dba6ceadc1960e4c3ef5578687af476fba!@mailhub-mx1.ncl.ac.uk>
@ 2017-12-23 6:56 ` Yasushi SHOJI
2017-12-23 14:12 ` Kaushal Modi
2018-04-26 23:34 ` Bastien
9 siblings, 1 reply; 40+ messages in thread
From: Yasushi SHOJI @ 2017-12-23 6:56 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
Hi Nicolas,
On Sun, Dec 17, 2017 at 7:34 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> The task started by Thomas S. Dye a couple years ago is now complete.
> The "manual.org" file in "contrib/" directory is an up-to-date,
> sometimes enhanced, version of the Org manual. Org can now eat its own
> dog food.
This is at great news!!
I remember a thread on the emacs-devel saying that texinfo html exporter doesn't
render as cute as the current standard (whatever that is).
But now we have the manual in org, and we can convert it to many format.
I just tried rst exporter, which I just happen to be using, and it works great,
with the following tiny patch. And the results is this.
http://org-manual.readthedocs.io/en/latest/
Info and orgmode.org/org.html is already super useful so this doesn't
gain much for me. but someone might like the way it renders.
regards,
--
yashi (now on to fix my own exporters ;-p)
--- ox-rst.el~ 2017-11-22 21:01:58.503667382 +0900
+++ ox-rst.el 2017-11-22 21:52:31.213331562 +0900
@@ -1086,7 +1086,7 @@
;; Protect ..
(setq text (replace-regexp-in-string "^[\s-]*\\.\\. [^\\[]" "\\\\.. " text))
;; Protect ^\d+.
- (setq text (replace-regexp-in-string "^\\([[:digit:]]\\)+\\." "\\1\\." text))
+ (setq text (replace-regexp-in-string "^\\([[:digit:]]\\)+\\."
"\\\\\\1." text))
;; Return value.
text)
^ permalink raw reply [flat|nested] 40+ messages in thread* Re: [RFC] Dog food, anyone?
2017-12-23 6:56 ` Yasushi SHOJI
@ 2017-12-23 14:12 ` Kaushal Modi
2017-12-25 1:44 ` Yasushi SHOJI
0 siblings, 1 reply; 40+ messages in thread
From: Kaushal Modi @ 2017-12-23 14:12 UTC (permalink / raw)
To: Yasushi SHOJI; +Cc: Org Mode List, Nicolas Goaziou
[-- Attachment #1: Type: text/plain, Size: 763 bytes --]
On Sat, Dec 23, 2017, 1:57 AM Yasushi SHOJI <yasushi.shoji@gmail.com> wrote:
> I just tried rst exporter, which I just happen to be using, and it works
> great,
> with the following tiny patch. And the results is this.
>
> http://org-manual.readthedocs.io/en/latest/
>
> Info and orgmode.org/org.html is already super useful so this doesn't
> gain much for me. but someone might like the way it renders.
>
Thanks for sharing that! I do like the colors and syntax highlighting on
readthedocs.io.
The only minor issue is that it loads the whole manual as a single HTML
page, so it takes a while to load. Do you know if there's a way to set it
up so that it shows a single page per node as orgmode.org does? Even if
not, this is wonderful :)
> --
Kaushal Modi
[-- Attachment #2: Type: text/html, Size: 1551 bytes --]
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-23 14:12 ` Kaushal Modi
@ 2017-12-25 1:44 ` Yasushi SHOJI
0 siblings, 0 replies; 40+ messages in thread
From: Yasushi SHOJI @ 2017-12-25 1:44 UTC (permalink / raw)
To: Kaushal Modi; +Cc: Org Mode List, Nicolas Goaziou
Hi,
On Sat, Dec 23, 2017 at 11:12 PM, Kaushal Modi <kaushal.modi@gmail.com> wrote:
> The only minor issue is that it loads the whole manual as a single HTML
> page, so it takes a while to load. Do you know if there's a way to set it up
> so that it shows a single page per node as orgmode.org does?
I've looked around the doc but not sure how. They support multi-files with
index, so it might be that we need to export to multi rst files?
Does org support such an export option?
--
yashi
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2017-12-17 10:34 [RFC] Dog food, anyone? Nicolas Goaziou
` (8 preceding siblings ...)
2017-12-23 6:56 ` Yasushi SHOJI
@ 2018-04-26 23:34 ` Bastien
2018-04-28 10:56 ` Nicolas Goaziou
2018-05-09 0:30 ` Nicolas Goaziou
9 siblings, 2 replies; 40+ messages in thread
From: Bastien @ 2018-04-26 23:34 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode List
Hi Nicolas,
it would be nice to make the switch to org-manual.org for Org 9.2,
and to delete org.texi entirely from the master branch.
I guess we need to add some Makefile rules so that "make pdf" first
exports .org => .texi then exports .texi to .pdf... is that so?
I'd rather make the switch now so that users and contributors are
not confused by the presence of two manuals in the repo.
Thanks,
--
Bastien
^ permalink raw reply [flat|nested] 40+ messages in thread* Re: [RFC] Dog food, anyone?
2018-04-26 23:34 ` Bastien
@ 2018-04-28 10:56 ` Nicolas Goaziou
2018-04-28 12:43 ` Bastien
2018-05-09 0:30 ` Nicolas Goaziou
1 sibling, 1 reply; 40+ messages in thread
From: Nicolas Goaziou @ 2018-04-28 10:56 UTC (permalink / raw)
To: Bastien; +Cc: Org Mode List
Hello,
Bastien <bzg@gnu.org> writes:
> it would be nice to make the switch to org-manual.org for Org 9.2,
> and to delete org.texi entirely from the master branch.
We already switched to "org-manual.org" in the sense that current
"org.texi" is generated from "org-manual.org".
> I guess we need to add some Makefile rules so that "make pdf" first
> exports .org => .texi then exports .texi to .pdf... is that so?
I guess we could extend the "info" rule to generate the ".texi" file out
of "org-manual.org" first. For example, in "doc/Makefile", we could
either add a pre-requisite to the following rule:
info: org
e.g.,
info: org.texi org
org.texi: org-manual.org
$(BATCH) \
--eval '(add-to-list '"'"'load-path "../lisp")' \
--eval '(load "org-compat.el")' \
--eval '(load "../mk/org-fixup.el")' \
--eval '(org-generate-texinfo-manual "$<" "@$")'
$(MAKEINFO) --no-split $< -o $@
assuming `org-generate-texinfo-manual' is defined in "org-fixup.el".
However, the above may require to mess with the match-all rule
.SUFFIXES: .texi .tex .txt _letter.tex
%: %.texi org-version.inc
$(MAKEINFO) --no-split $< -o $@
In particular, we might drop the "org-version.inc" file. But the build
system is tricky, I admit I do not understand it totally.
BTW, I wonder why the build system needs to create an "org" file,
without extension, equivalent to "org.info".
Regards,
--
Nicolas Goaziou
^ permalink raw reply [flat|nested] 40+ messages in thread* Re: [RFC] Dog food, anyone?
2018-04-28 10:56 ` Nicolas Goaziou
@ 2018-04-28 12:43 ` Bastien
0 siblings, 0 replies; 40+ messages in thread
From: Bastien @ 2018-04-28 12:43 UTC (permalink / raw)
To: Nicolas Goaziou, Achim Gratz; +Cc: Org Mode List
Hi Nicolas,
I'm cc'ing Achim as I seem to remember he offered to help writing
needed rules for the switch to org-manual.org to be complete.
> I guess we could extend the "info" rule to generate the ".texi" file out
> of "org-manual.org" first. For example, in "doc/Makefile", we could
> either add a pre-requisite to the following rule:
>
> info: org
>
> e.g.,
>
> info: org.texi org
>
> org.texi: org-manual.org
> $(BATCH) \
> --eval '(add-to-list '"'"'load-path "../lisp")' \
> --eval '(load "org-compat.el")' \
> --eval '(load "../mk/org-fixup.el")' \
> --eval '(org-generate-texinfo-manual "$<" "@$")'
> $(MAKEINFO) --no-split $< -o $@
>
> assuming `org-generate-texinfo-manual' is defined in "org-fixup.el".
>
> However, the above may require to mess with the match-all rule
>
> .SUFFIXES: .texi .tex .txt _letter.tex
>
> %: %.texi org-version.inc
> $(MAKEINFO) --no-split $< -o $@
>
> In particular, we might drop the "org-version.inc" file. But the build
> system is tricky, I admit I do not understand it totally.
Achim, what do you think?
If we can drop the org-version.inc, that's even better.
> BTW, I wonder why the build system needs to create an "org" file,
> without extension, equivalent to "org.info".
I guess that's a leftover from old times, when the .info extension on
info files was not systematic.
--
Bastien
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2018-04-26 23:34 ` Bastien
2018-04-28 10:56 ` Nicolas Goaziou
@ 2018-05-09 0:30 ` Nicolas Goaziou
2018-05-09 18:16 ` Gregor Zattler
1 sibling, 1 reply; 40+ messages in thread
From: Nicolas Goaziou @ 2018-05-09 0:30 UTC (permalink / raw)
To: Bastien; +Cc: Org Mode List
Hello,
Bastien <bzg@gnu.org> writes:
> it would be nice to make the switch to org-manual.org for Org 9.2,
> and to delete org.texi entirely from the master branch.
Done.
> I guess we need to add some Makefile rules so that "make pdf" first
> exports .org => .texi then exports .texi to .pdf... is that so?
Done (or so I think).
Regards,
--
Nicolas Goaziou 0x80A93738
^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: [RFC] Dog food, anyone?
2018-05-09 0:30 ` Nicolas Goaziou
@ 2018-05-09 18:16 ` Gregor Zattler
2018-05-09 19:12 ` Nicolas Goaziou
0 siblings, 1 reply; 40+ messages in thread
From: Gregor Zattler @ 2018-05-09 18:16 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 2180 bytes --]
Hi Nicolas, Org mode developers,
* Nicolas Goaziou <mail@nicolasgoaziou.fr> [2018-05-09; 02:30]:
> Bastien <bzg@gnu.org> writes:
>
>> it would be nice to make the switch to org-manual.org for Org 9.2,
>> and to delete org.texi entirely from the master branch.
>
> Done.
>
>> I guess we need to add some Makefile rules so that "make pdf" first
>> exports .org => .texi then exports .texi to .pdf... is that so?
>
> Done (or so I think).
Hurray!
I found that org-float instead of diary-float is documented in
org-manual.org although ORG-NEWS says to use diary-float instead:
~/src/org-mode$ rgrep org-float
etc/ORG-NEWS:** =org-float= is now obsolete, use =diary-float= instead
Binary file lisp/org-compat.elc matches
lisp/org-compat.el:(define-obsolete-function-alias 'org-float-time 'float-time "Org 9.0")
testing/lisp/test-org.el: (org-test-with-temp-text "<%%(org-float t 4 2)>"
testing/lisp/test-org.el: (equal "<%%(org-float t 4 2)>"
testing/lisp/test-org.el: (org-test-with-temp-text "<%%(org-float t 4 2)>"
doc/org.texi: <%%(org-float t 4 2)>
doc/org.texi:<%%(org-float t 42)>
doc/org-manual.org: <%%(org-float t 4 2)>
doc/org-manual.org:: <%%(org-float t 42)>
doc/org: <%%(org-float t 4 2)>
doc/org: <%%(org-float t 42)>
doc/org.html: <%%(org-float t 4 2)>
doc/org.html:<pre class="example"><%%(org-float t 42)>
~/src/org-mode$ rgrep diary-float
etc/ORG-NEWS:** =org-float= is now obsolete, use =diary-float= instead
testing/lisp/test-org-element.el: (should (equal (org-test-parse-and-interpret "<%%diary-float t 4 2>")
testing/lisp/test-org-element.el: "<%%diary-float t 4 2>\n"))
doc/orgguide.texi: <%%(diary-float t 4 2)>
org-guide.texi is already up to date with respect to
diary-float.
I made a very simple patch for org-manual.org but none for
test-org.el or test-org-element.el since I do not understand
them. When reading about documentation standards I found that
Org manuals filename and directory wasn't up to date, so I fixed
this. I assume that the parts of doc/Documentation_Standards.org
which deal with texinfo formatting are also out of date but do
not know how to rewrite them.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Tiny-doc-fixes.patch --]
[-- Type: text/x-diff, Size: 2144 bytes --]
From b45739a23b093e1ee54ae09be8172720fa611628 Mon Sep 17 00:00:00 2001
From: Gregor Zattler <telegraph@gmx.net>
Date: Wed, 9 May 2018 19:51:51 +0200
Subject: [PATCH] ; Tiny doc fixes
* doc/org-manual.org (Dates and Times) (Timestamps, Deadlines and
Scheduling): Document "diary-float" instead of obsolete "org-float".
* doc/Documentation_Standards.org (org-manual.org specific
conventions): Fix file name and directory of Org manual.
Copyright-paperwork-exempt: yes
TINYCHANGE
---
doc/Documentation_Standards.org | 4 ++--
doc/org-manual.org | 4 ++--
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/doc/Documentation_Standards.org b/doc/Documentation_Standards.org
index 9d8f19fe6..c4dd862db 100644
--- a/doc/Documentation_Standards.org
+++ b/doc/Documentation_Standards.org
@@ -94,10 +94,10 @@ I have made them up of course).
- Entries in the concept index are normally all lower case unless some
other rule dictates otherwise.
-* orgmanual.org specific conventions
+* org-manual.org specific conventions
Org git repository comes with an .org version of the manual in the
-=contrib/= directory. Here are indications that are specific to this
+=doc/= directory. Here are indications that are specific to this
version of the manual.
- Five of the standard Texinfo indexes are used in the Org manual:
diff --git a/doc/org-manual.org b/doc/org-manual.org
index eb6c96fb2..d9e95b1ee 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5779,7 +5779,7 @@ the agenda (see [[*Weekly/daily agenda]]). We distinguish:
#+begin_example
,* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
- <%%(org-float t 4 2)>
+ <%%(diary-float t 4 2)>
#+end_example
- Time/Date range ::
@@ -6158,7 +6158,7 @@ entries. Org mode issues early and late warnings based on the
assumption that the timestamp represents the /nearest instance/ of the
repeater. However, the use of diary S-exp entries like
-: <%%(org-float t 42)>
+: <%%(diary-float t 42)>
#+texinfo: @noindent
in scheduling and deadline timestamps is limited. Org mode does not
--
2.11.0
[-- Attachment #3: Type: text/plain, Size: 141 bytes --]
I'm not sure if "org-float" is the right way to quote this kind
of symbol in a commit message. Please fix if not.
HTH a tiny bit, Gregor
^ permalink raw reply related [flat|nested] 40+ messages in thread