Using Org as the source format to generate org.texi

classic Classic list List threaded Threaded
52 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Using Org as the source format to generate org.texi

Bastien Guerry-5
Hi all,

thanks to Thomas' initiative and Nicolas' efforts, we now have Org's
documentation available as an .org file:

https://code.orgmode.org/bzg/org-mode/raw/master/contrib/manual.org

We plan to use manual.org (or org.org) as the source file for Org's
documentation: editing Org file is easier than to edit .texi files,
and Org's current Texinfo exporter does a very good job at producing
an org.texi file that is equivalent to the one we have right now.

One drawback is that we will have to backport manual changes made in
Emacs' repo to org.texi into Org's manual.org file, but such changes
are rare enough that we think we can handle this.

In the long term, it would be nice to have more cli exporters for Org,
although pandoc already does a good job at converting an .org file to
a .texi file.

In any case, editing such a big manual directly in Org is great and
maybe this proof of concept will inspire other Elisp contributors to
write their documentation directly in Org.

Glenn suggested we'd share this with the list and I think it's a good
idea -- in case you foresee problems that we may not have adressed.

Thanks!

--
 Bastien


Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Stefan Monnier
Bastien <[hidden email]> writes:
> One drawback is that we will have to backport manual changes made in
> Emacs' repo to org.texi into Org's manual.org file, but such changes
> are rare enough that we think we can handle this.

Why wouldn't we use Org's manual.org in Emacs?


        Stefan


Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Kaushal Modi
On Tue, Mar 6, 2018 at 3:20 PM Stefan Monnier <[hidden email]> wrote:

Why wouldn't we use Org's manual.org in Emacs?

If you meant that "why wouldn't one make fixes/edits directly in Org's manual.org".. then that actually is the best way! :)
--

Kaushal Modi

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Paul Eggert
In reply to this post by Bastien Guerry-5
On 03/06/2018 10:04 AM, Bastien wrote:
> One drawback is that we will have to backport manual changes made in
> Emacs' repo to org.texi into Org's manual.org file

Let's fix this by adding a Makefile rule to Emacs master, a rule that
generates org.texi automatically from manual.org. Then we can remove
org.texi from the master source tree, and replace it with manual.org.


Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Achim Gratz
In reply to this post by Stefan Monnier
Stefan Monnier writes:
> Bastien <[hidden email]> writes:
>> One drawback is that we will have to backport manual changes made in
>> Emacs' repo to org.texi into Org's manual.org file, but such changes
>> are rare enough that we think we can handle this.
>
> Why wouldn't we use Org's manual.org in Emacs?

Well, that was the question, but I personally think it's good you can't
think of a reason to edit an intermediate file in order for Emacs to
have an Org manual.  But for some phase-over period it's possible and
even likely that both an Org file and an intermediate org.texi file
exist until Emacs' build system can deal with the Org file by itself.


Regards,
Achim.
--
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Waldorf MIDI Implementation & additional documentation:
http://Synth.Stromeko.net/Downloads.html#WaldorfDocs


Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Bastien Guerry-5
In reply to this post by Paul Eggert
Hi Paul,

Paul Eggert <[hidden email]> writes:

> On 03/06/2018 10:04 AM, Bastien wrote:
>> One drawback is that we will have to backport manual changes made in
>> Emacs' repo to org.texi into Org's manual.org file
>
> Let's fix this by adding a Makefile rule to Emacs master, a rule that
> generates org.texi automatically from manual.org. Then we can remove
> org.texi from the master source tree, and replace it with manual.org.

It would be great!

I don't know where to start for doing this: can you give us some
direction?

Thanks,

--
 Bastien

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Bastien Guerry-5
In reply to this post by Stefan Monnier
Hi Stefan,

Stefan Monnier <[hidden email]> writes:

> Bastien <[hidden email]> writes:
>> One drawback is that we will have to backport manual changes made in
>> Emacs' repo to org.texi into Org's manual.org file, but such changes
>> are rare enough that we think we can handle this.
>
> Why wouldn't we use Org's manual.org in Emacs?

I thought the rule was for Emacs manuals to be written in Texinfo.

But if we can sync org-manual.org in Emacs branch, it will make our
lives easier, for sure!

--
 Bastien

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Paul Eggert
In reply to this post by Bastien Guerry-5
On 03/06/2018 04:19 PM, Bastien wrote:
> I don't know where to start for doing this: can you give us some
> direction?

I assume that we'd add something like this to doc/misc/Makefile.in:

EXEEXT = @EXEEXT@
EMACS = ../src/emacs$(EXEEXT)
EMACSOPT = -batch --no-site-file --no-site-lisp
emacs = EMACSLOADPATH= '$(EMACS)' $(EMACSOPT)

$(srcdir)/org.texi: $(srcdir)/org-manual.org
     $(AM_V_GEN)$(emacs) -l something --eval '(something)' something

Some other tweaking will be needed, but the crucial thing is to get that
last line right.

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Achim Gratz
Paul Eggert writes:
> $(srcdir)/org.texi: $(srcdir)/org-manual.org
>     $(AM_V_GEN)$(emacs) -l something --eval '(something)' something
>
> Some other tweaking will be needed, but the crucial thing is to get
> that last line right.

Let me dig out the incantation later today (unles Nicolas beats me to it
of course).


Regards,
Achim.
--
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptations for Waldorf Q V3.00R3 and Q+ V3.54R2:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada


Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Glenn Morris-3
In reply to this post by Stefan Monnier
Stefan Monnier wrote:

> Why wouldn't we use Org's manual.org in Emacs?

Surely you must, if it becomes the preferred form for modification.

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Glenn Morris-3
In reply to this post by Paul Eggert
Paul Eggert wrote:

> I assume that we'd add something like this to doc/misc/Makefile.in:
>
> EXEEXT = @EXEEXT@
> EMACS = ../src/emacs$(EXEEXT)
> EMACSOPT = -batch --no-site-file --no-site-lisp
> emacs = EMACSLOADPATH= '$(EMACS)' $(EMACSOPT)
>
> $(srcdir)/org.texi: $(srcdir)/org-manual.org
>     $(AM_V_GEN)$(emacs) -l something --eval '(something)' something
>
> Some other tweaking will be needed, but the crucial thing is to get
> that last line right.

Note that this will make info generation depend on the existence of
src/emacs, when it was previously independent.

Also, if any other manual made the same change, it would prevent
bootstrapping Emacs without Org present (eg if the idea to include elpa
packages in Emacs releases ever goes anywhere, and it's desired to stop
duplicating Org in the Emacs repo; an idea which still makes complete
sense to me).

(Just trying to list some items relevant to the "other tweaking" part.)

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Eli Zaretskii
In reply to this post by Bastien Guerry-5
> From: Bastien <[hidden email]>
> Date: Wed, 07 Mar 2018 01:22:47 +0100
> Cc: [hidden email]
>
> Stefan Monnier <[hidden email]> writes:
>
> > Bastien <[hidden email]> writes:
> >> One drawback is that we will have to backport manual changes made in
> >> Emacs' repo to org.texi into Org's manual.org file, but such changes
> >> are rare enough that we think we can handle this.
> >
> > Why wouldn't we use Org's manual.org in Emacs?
>
> I thought the rule was for Emacs manuals to be written in Texinfo.
>
> But if we can sync org-manual.org in Emacs branch, it will make our
> lives easier, for sure!

I had a look at manual.org in the Org repository.  If we are going to
maintain the Org manual in that form, would it be possible to come up
with a "cheat sheet" for die-hard Texinfo users, that would give them
enough tips for writing manuals-to-be-converted-to-Texinfo?  (Or maybe
such a document already exists, and I just overlooked it?)  The
mechanics of writing a manual in Org is sufficiently different that
would leave me challenged enough without such a cookbook.  For
example, how does one insert all those {{{kbd(foo bar)}}} -- I presume
you don't type that literally, but I couldn't find a command similar
to texinfo-insert-@kbd.  (If there's no such command, I think it
should be added, as well as commands to insert other kinds of markup
that is more than one or two characters long.  For example, the
code-block delimiters "#+begin_src emacs-lisp", cross-references,
@noindent, etc.  The equivalent commands in texinfo-mode are
significant time-savers.)

Also, I see some omissions in converting the Texinfo manual to
manual.org: all the uses of @key disappeared (expect Michael Albinus
to be very unhappy ;-), and likewise with @command -- is that
intentional?

And what is the difference between cross-references that begin with an
asterisk and those that don't?  I couldn't find that in the manual.

Thanks.

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Kaushal Modi
On Wed, Mar 7, 2018, 12:43 PM Eli Zaretskii <[hidden email]> wrote:

I had a look at manual.org in the Org repository.  If we are going to
maintain the Org manual in that form, would it be possible to come up
with a "cheat sheet" for die-hard Texinfo users, that would give them
enough tips for writing manuals-to-be-converted-to-Texinfo? 

I'd be up to help write up such a document. I'm copying Nicolas as he'd be the best person to answer the Org->texi conversion questions. 
--

Kaushal Modi

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Richard Stallman
In reply to this post by Stefan Monnier
[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > One drawback is that we will have to backport manual changes made in
  > > Emacs' repo to org.texi into Org's manual.org file, but such changes
  > > are rare enough that we think we can handle this.

  > Why wouldn't we use Org's manual.org in Emacs?

Our standard format for manuals is Texinfo.
However, it is ok to use another format if it can
be converted into good Texinfo.  That means
the conversion produces a Texinfo file which
uses all the constructs according to our style.

If Org can convert manual.org into that,
then it is ok as a source file.

Can Org express all the constructs of Texinfo?

But I think 'manual.org' is the wrong name for it.
It isn't the one and only manual we distribute, and it
may not be the only one written in org.  So
it should be 'org-manual.org', right?

--
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
Skype: No way! See https://stallman.org/skype.html.


Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Michael Albinus
In reply to this post by Eli Zaretskii
Eli Zaretskii <[hidden email]> writes:

> Also, I see some omissions in converting the Texinfo manual to
> manual.org: all the uses of @key disappeared (expect Michael Albinus
> to be very unhappy ;-), and likewise with @command -- is that
> intentional?

In order to prevent my unhappiness, next weeks I'll check manual.org and
how it is converted into texinfo. But don't expect too much from me; I'm
not a hard-core org user.

And proofreading the Emacs 26 manual comes first.

> Thanks.

Best regards, Michael.

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Bastien Guerry-5
In reply to this post by Kaushal Modi
Hi Kaushal,

Kaushal Modi <[hidden email]> writes:

> I'd be up to help write up such a document.

Thanks!

Can you start this document on Worg?

For those who don't know, Worg is the community-driven documentation:

  https://code.orgmode.org/bzg/worg/

We also started a draft for org-manual.org conventions:

  https://code.orgmode.org/bzg/org-mode/src/master/doc/Documentation_Standards.org#orgmanualorg-specific-conventions

--
 Bastien

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Bastien Guerry-5
In reply to this post by Michael Albinus
Hi Michael,

Michael Albinus <[hidden email]> writes:

> In order to prevent my unhappiness, next weeks I'll check manual.org and
> how it is converted into texinfo. But don't expect too much from me; I'm
> not a hard-core org user.

The goal is to make editing manual.org feasible even for non-hard-core
users.  So every "naive" request or report will be useful.

> And proofreading the Emacs 26 manual comes first.

Of course.

--
 Bastien

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Bastien Guerry-5
In reply to this post by Eli Zaretskii
Eli Zaretskii <[hidden email]> writes:

> For example, how does one insert all those {{{kbd(foo bar)}}} -- I
> presume you don't type that literally, but I couldn't find a command
> similar to texinfo-insert-@kbd.

I don't know if having an org-insert-macro command in org.el would be
useful, we may consider it.

In the meantime I suggest we add this in a new section of the manual:

#+begin_src emacs-lisp
(define-skeleton var-macro-skeleton
  "Insert a {{{var(...)}}} macro."
  "Variable: "
  "{{{var(" str ")}}}")
(define-skeleton cite-macro-skeleton
  "Insert a {{{cite(...)}}} macro."
  "Cite: "
  "{{{cite(" str ")}}}")
(define-skeleton kbd-macro-skeleton
  "Insert a {{{kbd(...)}}} macro."
  "Keybinding: "
  "{{{kbd(" str ")}}}")

(define-key org-mode-map "\C-c\C-xv" #'var-macro-skeleton)
(define-key org-mode-map "\C-c\C-xc" #'cite-macro-skeleton)
(define-key org-mode-map "\C-c\C-xk" #'kbd-macro-skeleton)
#+end_src

Hitting C-c C-c on the #+begin_src line will evaluated the code,
and then C-c C-x v will help inserting a {{{var(...)}}} macro.

> (If there's no such command, I
> think it should be added, as well as commands to insert other kinds
> of markup that is more than one or two characters long.  For
> example, the code-block delimiters "#+begin_src emacs-lisp",
> cross-references, @noindent, etc.  The equivalent commands in
> texinfo-mode are significant time-savers.)

For this you need (require 'org-tempo), which loads templates.
Then, hitting "< s TAB" (without the spaces) will expand into
a #+begin_src ... #+end_src block.

> Also, I see some omissions in converting the Texinfo manual to
> manual.org: all the uses of @key disappeared (expect Michael Albinus
> to be very unhappy ;-), and likewise with @command -- is that
> intentional?

I guess it needs to be fixed.

> And what is the difference between cross-references that begin with an
> asterisk and those that don't?  I couldn't find that in the manual.

I don't know -- I'll let Nicolas explain.

Thanks for your questions and feedback!

--
 Bastien

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Phillip Lord-3
In reply to this post by Glenn Morris-3
Glenn Morris <[hidden email]> writes:

> Paul Eggert wrote:
>
>> I assume that we'd add something like this to doc/misc/Makefile.in:
>>
>> EXEEXT = @EXEEXT@
>> EMACS = ../src/emacs$(EXEEXT)
>> EMACSOPT = -batch --no-site-file --no-site-lisp
>> emacs = EMACSLOADPATH= '$(EMACS)' $(EMACSOPT)
>>
>> $(srcdir)/org.texi: $(srcdir)/org-manual.org
>>     $(AM_V_GEN)$(emacs) -l something --eval '(something)' something
>>
>> Some other tweaking will be needed, but the crucial thing is to get
>> that last line right.
>
> Note that this will make info generation depend on the existence of
> src/emacs, when it was previously independent.

Which would shove generation of the documentation till after dumping. I
don't know enough about make to work out whether this would be for just
org.org or for all the texi.


> Also, if any other manual made the same change, it would prevent
> bootstrapping Emacs without Org present (eg if the idea to include elpa
> packages in Emacs releases ever goes anywhere, and it's desired to stop
> duplicating Org in the Emacs repo; an idea which still makes complete
> sense to me).

Confused on this one. bootstrapping needs the documentation to be complete?

Phil

Reply | Threaded
Open this post in threaded view
|

Re: Using Org as the source format to generate org.texi

Bastien Guerry-5
In reply to this post by Richard Stallman
Richard Stallman <[hidden email]> writes:

> If Org can convert manual.org into that,
> then it is ok as a source file.

Good.

> Can Org express all the constructs of Texinfo?

As far as I know, yes -- but we need to check this.

> But I think 'manual.org' is the wrong name for it.
> It isn't the one and only manual we distribute, and it
> may not be the only one written in org.  So
> it should be 'org-manual.org', right?

Agreed.  I'm in favor of renaming it to org.org to stick
to convention currently in use: [package-name].texi.

If more manuals are to be written in Org, then having
calc-manual.org, emacs-manual.org, etc. is redundant.

--
 Bastien

123