Using Org as the source format to generate org.texi

Using Org as the source format to generate org.texi

[Bastien]

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

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

[Stefan Monnier]

Bastien <bzg@gnu.org> 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

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

[Kaushal Modi]

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

On Tue, Mar 6, 2018 at 3:20 PM Stefan Monnier <monnier@iro.umontreal.ca>
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

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

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

[Paul Eggert]

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.

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

[Achim Gratz]

Stefan Monnier writes:
> Bastien <bzg@gnu.org> 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

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

[Bastien]

Hi Paul,

Paul Eggert <eggert@cs.ucla.edu> 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

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

[Bastien]

Hi Stefan,

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Bastien <bzg@gnu.org> 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

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

[Paul Eggert]

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.

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

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

[Glenn Morris]

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.

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

[Glenn Morris]

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.)

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

[Eli Zaretskii]

> From: Bastien <bzg@gnu.org>
> Date: Wed, 07 Mar 2018 01:22:47 +0100
> Cc: emacs-devel@gnu.org
> 
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
> 
> > Bastien <bzg@gnu.org> 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.

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

[Kaushal Modi]

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

On Wed, Mar 7, 2018, 12:43 PM Eli Zaretskii <eliz@gnu.org> 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

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

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

[Richard Stallman]

[[[ 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.

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

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> 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.

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

[Bastien Guerry]

Hi Kaushal,

Kaushal Modi <kaushal.modi@gmail.com> 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

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

[Bastien Guerry]

Hi Michael,

Michael Albinus <michael.albinus@gmx.de> 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

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

[Bastien Guerry]

Eli Zaretskii <eliz@gnu.org> 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

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

[Phillip Lord]

Glenn Morris <rgm@gnu.org> 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

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

[Bastien]

Richard Stallman <rms@gnu.org> 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

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

[Achim Gratz]

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

Well, you could certainly define a separate Emacs instance to be used
for the generation of the documentation unless you do a full greenfield
bootstrap.

> 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.)

I'd say that it just changes the way how the bootstrap is done, I don't
yet see it preventing anything.  The same line of argumentation needs to
be followed for the tarball generation.


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

Factory and User Sound Singles for Waldorf Q+, Q and microQ:
http://Synth.Stromeko.net/Downloads.html#WaldorfSounds

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

[Achim Gratz]

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

Achim Gratz writes:
> Let me dig out the incantation later today (unles Nicolas beats me to it
> of course).

Sorry, I got distracted by a clogged drain pipe.  Here's the Makefile
I've been using:


[-- Attachment #2: Makefile --]
[-- Type: text/plain, Size: 1048 bytes --]

TEXI2PDF+=--tidy
BEXP=$(BATCH) \
	--eval '(add-to-list '"'"'load-path "../lisp")'
EXTEXI=	
EXHTML=	$(BTEST_POST)
ORG2TEXI=-f org-texinfo-export-to-texinfo
ORG2HTML=-f org-html-export-to-html
ORG2INFO=--eval "(org-texinfo-compile \"./$<\")"

.SUFFIXES:	# we don't need default suffix rules
ifeq ($(MAKELEVEL), 0)
  $(error This make needs to be started as a sub-make from the toplevel directory.)
endif
.PHONY:		all info html pdf

all:		$(ORG_MAKE_DOC)

info:		org.info

html:		orgmanual org.html

pdf:		org.pdf

org.texi:	orgmanual.org
	$(BEXP) $(EXTEXI) $< $(ORG2TEXI)
org.info:	org.texi
	$(MAKEINFO)  --no-split $< -o $@
# LANG=C # to work around a bug in texi2dvi
org.pdf:	LC_ALL=C
org.pdf:	LANG=C
org.pdf:	org.texi
	$(TEXI2PDF) $<
orgmanual:	org.texi
	$(TEXI2HTML) $< -o $@
org.html: orgmanual.org
	$(BEXP) $(EXHTML) $< $(ORG2HTML)

clean:
	$(RM) org *.pdf *.html *.texi *.info *~ \
	      *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.pg *.pgs \
	      *.toc *.tp *.tps *.vr *.vrs *.log *.html *.ps
cleanall:	clean
	$(RMR) org.t2d orgmanual


[-- Attachment #3: Type: text/plain, Size: 199 bytes --]



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

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

[Paul Eggert]

On 03/09/2018 09:52 AM, Achim Gratz wrote:
> Sorry, I got distracted by a clogged drain pipe.  Here's the Makefile
> I've been using:

In what context do you use that Makefile? Is it in directory separate 
from the Emacs source tree? That sort of thing.

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

[Achim Gratz]

Paul Eggert writes:
> In what context do you use that Makefile? Is it in directory separate
> from the Emacs source tree? That sort of thing.

I use that in the Org source tree in a separate directory.  I used to
have the manual checked out from Thomas' git repo as a subtree there,
but at the moment it's just linked to the manual in the contrib/
directory.  This file is meant to be used as a sub-make from the main
Makefile.  If it's intended to be used standalone in Emacs you'd have to
re-shuffle a few things quite likely.


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

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

[Phillip Lord]

Achim Gratz <Stromeko@nexgo.de> writes:

> Glenn Morris writes:
>> Note that this will make info generation depend on the existence of
>> src/emacs, when it was previously independent.
>
> Well, you could certainly define a separate Emacs instance to be used
> for the generation of the documentation unless you do a full greenfield
> bootstrap.

I think that's not a good idea, but I don't think it's necessary. Having
info dependent on src/emacs might slow the build somewhat. It's easiest
enough to test.



>> 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.)
>
> I'd say that it just changes the way how the bootstrap is done, I don't
> yet see it preventing anything.  The same line of argumentation needs to
> be followed for the tarball generation.


As it happens I have a version of this now. It would lead to the
slightly strange situation that the build would refer to org-mode
functions which are not actually hosted in the repo. So, it would mean
that you could not build Emacs from a clean clone of the Emacs repo
without access to the ELPA repo (i.e. a local clone).

In practice, I suspect this would not be a huge issue.

Phil

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

[Nicolas Goaziou]

Hello,

Richard Stallman <rms@gnu.org> writes:

> Can Org express all the constructs of Texinfo?

Not out of the box. 

However, it provides mechanisms to extend its syntax. For example,
although there is no equivalent to @kbd{...} in Org, "org-manual.org"
defines a new construct, {{{kbd(...)}}}, which expands to @kbd{...}.

Also, it is possible to write raw Texinfo in an Org buffer.

Regards,

-- 
Nicolas Goaziou

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

[Paul Eggert]

Phillip Lord wrote:
> it would mean
> that you could not build Emacs from a clean clone of the Emacs repo
> without access to the ELPA repo (i.e. a local clone).

I don't have a local clone of the ELPA repo, so this'd mean I couldn't do a 
clean build from Emacs source without going to some extra work. I think I'd feel 
more comfortable if we didn't impose this additional dependency on building 
Emacs. Can we arrange for that by moving the relevant code into Emacs proper? 
How much code are we talking about?

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

[Eli Zaretskii]

> From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
> Date: Sat, 10 Mar 2018 22:26:40 +0100
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> 
> Also, it is possible to write raw Texinfo in an Org buffer.

Yes, but AFAICT doing that is painful, so it should be reserved for
exceptional situations, not as a matter of routine.

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

[Stefan Monnier]

> I don't have a local clone of the ELPA repo, so this'd mean I couldn't
> do a clean build from Emacs source without going to some extra work.

If we move to include ELPA packages in the normal build (as Phillip is
trying to do), then "getting Emacs's Git" will indeed require getting
elpa.git as well.

IOW If we do that, then you will need to have a local clone (and the
extra work should be something similar to "make update-elpa").

> I think I'd feel more comfortable if we didn't impose this additional
> dependency on building Emacs. Can we arrange for that by moving the
> relevant code into Emacs proper?

Some packages don't want to live in emacs.git because they don't want to
be bound by Emacs's release schedule (and/or they want to make it easy
to synchronize changes with some external repository of that package).

For that reason, moving those into Emacs proper is not really desirable.

We could *copy* them into Emacs proper, but then we're stuck with the
problem of sync'ing changes between the copies, making it undesirable
as well.

> How much code are we talking about?

Not decided yet.  I suppose we'll start with just a couple packages, but
it's likely to grow to many packages.  But I think the expectation is
that Emacs's build should not break if ELPA packages are missing.


        Stefan

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

[Michael Albinus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,

Hi Nicolas,

>> Can Org express all the constructs of Texinfo?
>
> Not out of the box.
>
> However, it provides mechanisms to extend its syntax. For example,
> although there is no equivalent to @kbd{...} in Org, "org-manual.org"
> defines a new construct, {{{kbd(...)}}}, which expands to @kbd{...}.

Do you have some (ert) tests for checking the mapping of org constructs
into texinfo?

> Regards,

Best regards, Michael.

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

[Nicolas Goaziou]

Hello,

Michael Albinus <michael.albinus@gmx.de> writes:

> Do you have some (ert) tests for checking the mapping of org constructs
> into texinfo?

No, we do not write tests for export back-ends, like Texinfo, although
the export framework itself is extensively tested.

Regards,

-- 
Nicolas Goaziou

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

[Phillip Lord]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I don't have a local clone of the ELPA repo, so this'd mean I couldn't
>> do a clean build from Emacs source without going to some extra work.
>
> If we move to include ELPA packages in the normal build (as Phillip is
> trying to do), then "getting Emacs's Git" will indeed require getting
> elpa.git as well.
>
> IOW If we do that, then you will need to have a local clone (and the
> extra work should be something similar to "make update-elpa").

In my current version, elpa is cloned automatically on running top
level. It would also be possible to symlink in an existing elpa clone --
this would fit my workflow where I use multiple git worktree's of
different branches.

Indeed, there is an make update-elpa task which would need to be run
manually. Perhaps there is some git cleverness we can do here.

Phil

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

[Richard Stallman]

[[[ 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. ]]]

  > > Can Org express all the constructs of Texinfo?

  > Not out of the box. 

Is there any chance of extending it to make this convenient?

Texinfo has a number of overlapping constructs that look
the same in certain output formats but different in others.
Does Org have constructs 100% equivalent to
@dfn, @emph, @strong, @code, @samp, @var, @kbd, @key?

If not, would people like to add them?


-- 
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.

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

[Nicolas Goaziou]

Hello,

Richard Stallman <rms@gnu.org> writes:

> Texinfo has a number of overlapping constructs that look
> the same in certain output formats but different in others.
> Does Org have constructs 100% equivalent to
> @dfn, @emph, @strong, @code, @samp, @var, @kbd, @key?

Org has lightweight markup for @emph, @strong, @code and @samp out of
the box: /emph/, *strong*, ~code~ and =samp=.

@var, @kbd and @key are defined, in "org-manual.org", through
a one-liner mechanism called a macro. There, @var{foo} becomes
{{{var(foo)}}} and @kbd{M-@key{RET}} becomes {{{kbd(M-RET)}}} (the
"@key" part is automatically deduced from the contents of the macro).

However, "org-manual.org" doesn't define "@dfn" because it doesn't need
it. But if it did, it could use a {{{dfn(...)}}} macro as above.

> If not, would people like to add them?

At one point, I suggested to make the "kbd" macro readily available for
every export back-end. As such, the would be no need to define it in
each document making use of it. However there was little interest in the
Org ML. Also, there are some decisions to make. For example, the macro
needs to be useful in every format supported by Org, and there are
multiple ways to transcribe @kbd+@key in LaTeX parlance. It is not clear
which one we should use and how configurable it should be.

I'm not sure about @dfn. Org has a lightweight markup, i.e., _this_,
which mean "underline" by default. Since it is ignored in the Texinfo
export back-end, we might use it for @dfn. It probably would not be
shocking if the term appeared as underlined in other formats.

Note that this is all for default Texinfo back-end, which needs to be,
as much as possible, compatible with other export back-ends (LaTeX,
ASCII, HTML, ODT...). However, there is always the possibility to write
another, dedicated, Texinfo back-end for Emacs manuals. This one could
ignore compatibility altogether and use more specific constructs. This
is, AFAIK, what the maintainer of Magit did for its manual. This could
be discussed with people that actually write or maintain Emacs manuals.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

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

[Eli Zaretskii]

> From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
> Date: Mon, 12 Mar 2018 15:07:34 +0100
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> @var, @kbd and @key are defined, in "org-manual.org", through
> a one-liner mechanism called a macro. There, @var{foo} becomes
> {{{var(foo)}}} and @kbd{M-@key{RET}} becomes {{{kbd(M-RET)}}} (the
> "@key" part is automatically deduced from the contents of the macro).

As I wrote elsewhere, we need to be able to use @key without losing
it, at least outside @kbd.

> At one point, I suggested to make the "kbd" macro readily available for
> every export back-end. As such, the would be no need to define it in
> each document making use of it. However there was little interest in the
> Org ML. Also, there are some decisions to make. For example, the macro
> needs to be useful in every format supported by Org, and there are
> multiple ways to transcribe @kbd+@key in LaTeX parlance. It is not clear
> which one we should use and how configurable it should be.

How about using what texinfo.tex does?

> I'm not sure about @dfn. Org has a lightweight markup, i.e., _this_,
> which mean "underline" by default. Since it is ignored in the Texinfo
> export back-end, we might use it for @dfn. It probably would not be
> shocking if the term appeared as underlined in other formats.

@dfn produces slanted typeface in printed output and “quoted” string
in Info output.  I'd suggest that Org produces something similar.

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

[Nicolas Goaziou]

Hello,

Eli Zaretskii <eliz@gnu.org> writes:

> As I wrote elsewhere, we need to be able to use @key without losing
> it, at least outside @kbd.

I may have missed the "elsewhere".

Is there any difference between @kbd{@key{...}} and @key{...}? If so, is
there any use of the former? If any question has a negative answer, then
all is good. Org can produce the former but could has well generate the
latter in this special case.

If both have a positive answer, we can generate automatically the most
common one and let users write a macro for the other case. This
situation is probably sufficiently rare it isn't much of a problem
anyway.

>> At one point, I suggested to make the "kbd" macro readily available for
>> every export back-end. As such, the would be no need to define it in
>> each document making use of it. However there was little interest in the
>> Org ML. Also, there are some decisions to make. For example, the macro
>> needs to be useful in every format supported by Org, and there are
>> multiple ways to transcribe @kbd+@key in LaTeX parlance. It is not clear
>> which one we should use and how configurable it should be.
>
> How about using what texinfo.tex does?

My TeX is a bit rusty, but, AFAIU, it defines yet another way to handle
@kbd+@key. This is fine, but LaTeX also provides at least two packages
dealing with keys. I have no preference, but users may disagree about
which way is better as a default. Even if we stick with the
"texinfo.tex" way, we probably need to allow tweaking the LaTeX output
somehow.

> @dfn produces slanted typeface in printed output and “quoted” string
> in Info output.  I'd suggest that Org produces something similar.

Slated typeface is /.../ markup in Org, which becomes @emph{...} when
exported to Texinfo. I'm suggesting to use _..._ markup because it is
free and fall-backs somewhat gracefully when exported to something else
than Texinfo.

Org -> LaTeX and Org -> Texinfo -> LaTeX are going to produce different
results and there is little hope they can converge at some point.
I suggest to not bother too much about this.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

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

[Glenn Morris]

Phillip Lord wrote:

>> 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.

It should just be for org. I imagine an order-only prerequisite for
org.texi on src/emacs (as well as normal prerequisites on all the
relevant org.el source files, sigh).

>> 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?

By "bootstrapping Emacs" I meant "building it from the Emacs repository".
This includes generating the info documentation from whatever the
ultimate source files are, not just creating src/(bootstrap-)emacs.

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

[Eli Zaretskii]

> From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
> Cc: rms@gnu.org,  monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Mon, 12 Mar 2018 17:42:16 +0100
> 
> > As I wrote elsewhere, we need to be able to use @key without losing
> > it, at least outside @kbd.
> 
> I may have missed the "elsewhere".

In my first message in this thread.

> Is there any difference between @kbd{@key{...}} and @key{...}?

I meant @key alone (that's why above I said "outside @kbd").  What
should happen with @kbd{@key{...}} is under debate, and I don't think
it's anywhere as important as supporting @key conveniently.  AFAIK,
currently Org doesn't support @key, or at least all of its instances
in the Org's Texinfo manual were dropped when converting to Org.

> > @dfn produces slanted typeface in printed output and “quoted” string
> > in Info output.  I'd suggest that Org produces something similar.
> 
> Slated typeface is /.../ markup in Org, which becomes @emph{...} when
> exported to Texinfo. I'm suggesting to use _..._ markup because it is
> free and fall-backs somewhat gracefully when exported to something else
> than Texinfo.

It's up to you, but IMO underlining is not really appropriate.  New
terminology should stand out like it does in other typesetting
systems, and slanted typeface does a good job in this case.

> Org -> LaTeX and Org -> Texinfo -> LaTeX are going to produce different
> results and there is little hope they can converge at some point.
> I suggest to not bother too much about this.

That's not what bothers me.

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

[Nicolas Goaziou]

Eli Zaretskii <eliz@gnu.org> writes:

> I meant @key alone (that's why above I said "outside @kbd").  What
> should happen with @kbd{@key{...}} is under debate, and I don't think
> it's anywhere as important as supporting @key conveniently.  AFAIK,
> currently Org doesn't support @key, or at least all of its instances
> in the Org's Texinfo manual were dropped when converting to Org.

{{{kbd(...)}}} is both @kbd{...} and @key{...}.

Anyway, it seems you did not answer to any of my questions. Or I may be
misunderstanding, of course. Currently, {{{kbd(TAB)}}} is translated as
@kbd{@key{TAB}}. Would it be better if it became @key{TAB} instead? Or
is "supporting @key conveniently" something else?

> It's up to you, but IMO underlining is not really appropriate.  New
> terminology should stand out like it does in other typesetting
> systems, and slanted typeface does a good job in this case.
>
>> Org -> LaTeX and Org -> Texinfo -> LaTeX are going to produce different
>> results and there is little hope they can converge at some point.
>> I suggest to not bother too much about this.
>
> That's not what bothers me.

Well, it seems to be, really. _text_ underlines "text" in other export
back-ends than Texinfo. In Texinfo, it would become @dfn{...}. So, what
apparently bothers you is the "Org -> LaTeX" or "Org -> HTML" both
underline text when Texinfo makes it a definition. However _..._ is
a definition only in Texinfo. Therefore, e.g., "Org -> LaTeX" is going
to be different than "Org -> Texinfo -> LaTeX".

In any case, let's forget about this, it was just an idea. One can still
define and use {{{dfn(...)}}} when needed.

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

[Eli Zaretskii]

> From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
> Cc: rms@gnu.org,  monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Mon, 12 Mar 2018 18:57:03 +0100
> 
> {{{kbd(...)}}} is both @kbd{...} and @key{...}.

It can't be both, because then you cannot distinguish between
@kbd{FOO}, which means type the 3 characters F O O, and @key{FOO},
which means press the key labeled "FOO".

> Anyway, it seems you did not answer to any of my questions.

Sorry about that.  I thought I did.  Maybe what I say above clarifies
the issue.

> Currently, {{{kbd(TAB)}}} is translated as @kbd{@key{TAB}}. Would it
> be better if it became @key{TAB} instead? Or is "supporting @key
> conveniently" something else?

Yes, something else: we need a separate {{{key(...)}}} construct, or
something else that will produce @key{...} in Texinfo.

> >> Org -> LaTeX and Org -> Texinfo -> LaTeX are going to produce different
> >> results and there is little hope they can converge at some point.
> >> I suggest to not bother too much about this.
> >
> > That's not what bothers me.
> 
> Well, it seems to be, really. _text_ underlines "text" in other export
> back-ends than Texinfo. In Texinfo, it would become @dfn{...}.

I wouldn't recommend having an underline in Org to be translated into
something entirely different in Texinfo.  This is a mental burden on
the authors we'd better avoid.

> In any case, let's forget about this, it was just an idea. One can still
> define and use {{{dfn(...)}}} when needed.

Fine with me, thanks.

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

[Radon Rosborough]

> As it happens I have a version of this now. It would lead to the
> slightly strange situation that the build would refer to org-mode
> functions which are not actually hosted in the repo. So, it would mean
> that you could not build Emacs from a clean clone of the Emacs repo
> without access to the ELPA repo (i.e. a local clone).

I don't understand why this is the case. Currently, a version of Org
is bundled in Emacs core. Where does ELPA enter into it? Are you
talking about a hypothetical future situation where Org is not bundled
with Emacs? If so, then why would the Org manual even exist in Emacs
core?

Thanks,
Radon

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

[Nicolas Goaziou]

Eli Zaretskii <eliz@gnu.org> writes:

> It can't be both, because then you cannot distinguish between
> @kbd{FOO}, which means type the 3 characters F O O, and @key{FOO},
> which means press the key labeled "FOO".

I understand the difference between @kbd{FOO} and @key{FOO}, but you
probably didn't look at the implementation of {{{kbd(...)}}}. 

There, I hard-code a number of keys (e.g., SPC, RET, LFD, TAB, BS...)
which, when matching case sensitively the macro value, are replaced with
@key{...}. So,

  {{{kbd(FOO)}}}   => @kbd{FOO}
  {{{kbd(spc)}}}   => @kbd{spc}
  {{{kbd(S P C)}}} => @kbd{S P C}

but

  {{{kbd(SPC)}}}       => @kbd{@key{SPC}}
  {{{kbd(R E T M-RET)}}} => @kbd{R E T M-@key{RET}}

> Yes, something else: we need a separate {{{key(...)}}} construct, or
> something else that will produce @key{...} in Texinfo.

I still think we may not need that, as shown above. This works pretty
well for Org manual, actually.

So, if you need @key alone, I was simply suggesting that, for example

    {{{kbd(SPC)}}}   => @key{SPC}
    {{{kbd(S P C)}}} => @kbd{S P C}

It would be very wrong to write @kbd{SPC} if you mean type the
3 characters S P C anyway.

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

[Phillip Lord]

Radon Rosborough <radon.neon@gmail.com> writes:

>> As it happens I have a version of this now. It would lead to the
>> slightly strange situation that the build would refer to org-mode
>> functions which are not actually hosted in the repo. So, it would mean
>> that you could not build Emacs from a clean clone of the Emacs repo
>> without access to the ELPA repo (i.e. a local clone).
>
> I don't understand why this is the case. Currently, a version of Org
> is bundled in Emacs core. Where does ELPA enter into it? Are you
> talking about a hypothetical future situation where Org is not bundled
> with Emacs? If so, then why would the Org manual even exist in Emacs
> core?

Oh dear. I was hoping not to side-track the issue.

Yes, it's a hypothetical Emacs where org is hosted in ELPA not in
emacs.git, but still distributed with the Emacs tar ball. And the
question is, what if packages other than org used org-mode for their
manuals.

It's several steps away.

Phil

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

[Stefan Monnier]

> Oh dear. I was hoping not to side-track the issue.
> Yes, it's a hypothetical Emacs where org is hosted in ELPA not in
> emacs.git, but still distributed with the Emacs tar ball. And the
> question is, what if packages other than org used org-mode for their
> manuals.

Actually, as long as these other manuals are in ELPA packages which have
`org` in their "Package-Requires:", I think it'd still be fine.
So it's probably not something that we need to worry about.


        Stefan

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

[Eli Zaretskii]

> From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
> Cc: emacs-devel@gnu.org,  rms@gnu.org,  monnier@iro.umontreal.ca
> Date: Mon, 12 Mar 2018 22:37:19 +0100
> 
> There, I hard-code a number of keys (e.g., SPC, RET, LFD, TAB, BS...)
> which, when matching case sensitively the macro value, are replaced with
> @key{...}. So,
> 
>   {{{kbd(FOO)}}}   => @kbd{FOO}
>   {{{kbd(spc)}}}   => @kbd{spc}
>   {{{kbd(S P C)}}} => @kbd{S P C}
> 
> but
> 
>   {{{kbd(SPC)}}}       => @kbd{@key{SPC}}
>   {{{kbd(R E T M-RET)}}} => @kbd{R E T M-@key{RET}}

I don't think this can be a reliable solution, because there are many
more keys we use in the manuals, like HOME, END, LEFT, RIGHT, UP,
DOWN, PageUp, PageDown, NEXT, PRIOR, EDIT, F1, etc.  We can never
reliably hard-code any fixed list and hope to get away with it.

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

[Phillip Lord]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Oh dear. I was hoping not to side-track the issue.
>> Yes, it's a hypothetical Emacs where org is hosted in ELPA not in
>> emacs.git, but still distributed with the Emacs tar ball. And the
>> question is, what if packages other than org used org-mode for their
>> manuals.
>
> Actually, as long as these other manuals are in ELPA packages which have
> `org` in their "Package-Requires:", I think it'd still be fine.
> So it's probably not something that we need to worry about.

Yeah, agreed that would be a solution. Given the time scales, we could
also look at adding another heading to ELPA packages, which would,
effectively, specify a build time dependency.

The key point here, is that this is far from a show stopper; there are
clear solutions, and we have lots of time to think about them.

Phil

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

[Nicolas Goaziou]

Hello,

Eli Zaretskii <eliz@gnu.org> writes:

> I don't think this can be a reliable solution, because there are many
> more keys we use in the manuals, like HOME, END, LEFT, RIGHT, UP,
> DOWN, PageUp, PageDown, NEXT, PRIOR, EDIT, F1, etc.  We can never
> reliably hard-code any fixed list and hope to get away with it.

It's enough if we can get away with it 99% of the time. For the other
1%, we can write raw Texinfo in the Org document. I can extract
a reasonable list from the Emacs Texinfo files.

Org is no silver bullet and does not pretend to supersede Texinfo. But
it tries to make editing manuals easier in most cases.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

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

[Eli Zaretskii]

> From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
> Cc: emacs-devel@gnu.org,  rms@gnu.org,  monnier@iro.umontreal.ca
> Date: Tue, 13 Mar 2018 18:24:44 +0100
> 
> > I don't think this can be a reliable solution, because there are many
> > more keys we use in the manuals, like HOME, END, LEFT, RIGHT, UP,
> > DOWN, PageUp, PageDown, NEXT, PRIOR, EDIT, F1, etc.  We can never
> > reliably hard-code any fixed list and hope to get away with it.
> 
> It's enough if we can get away with it 99% of the time. For the other
> 1%, we can write raw Texinfo in the Org document. I can extract
> a reasonable list from the Emacs Texinfo files.

Personally, it would confuse me a lot to have to use kbd for both @kbd
and @key.  But that's me.

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

[Nicolas Goaziou]

Eli Zaretskii <eliz@gnu.org> writes:

> Personally, it would confuse me a lot to have to use kbd for both @kbd
> and @key.  But that's me.

You're coming from the Texinfo world, so you have a clear definition of
@kbd and @key in mind. OTOH, there are no such things in Org. From
there, @key may even appear superfluous, considering a simple macro --
in the Org sense -- can deduce it most of the time. Furthermore,
a DWIM-like "kbd" command is a nice thing to have for users that do not
know very well Texinfo.

However, we can rename the "kbd" macro, if it confuses you. I cannot
think of a good name for it, but feel free to suggest one.

@key{...} mis-use (was: Using Org as the source format to generate org.texi)

[Nicolas Goaziou]

Hello,

Eli Zaretskii <eliz@gnu.org> writes:

> I don't think this can be a reliable solution, because there are many
> more keys we use in the manuals, like HOME, END, LEFT, RIGHT, UP,
> DOWN, PageUp, PageDown, NEXT, PRIOR, EDIT, F1, etc.  We can never
> reliably hard-code any fixed list and hope to get away with it.

Speaking of which, I grepped through the "doc/" directory for
@key{something}, and uniquified the result.

Some of them are typos (e.g., @key{F11>}) and some stems from
a confusion between @kbd and @key (e.g., @key{C-c C-t @key{SPC}}). Some
are missing normalization (e.g., @kbd{arrow-up}) while others look odd
(e.g., @kbd{PNT}).

Here are the 254 values. Someone(c) with write access to repository
might want to fix some of them.

RET
SPC
META
CTL
meta
F3
SUPER
SHIFT
HYPER
CTRL
ALT
BS
DEL
TAB
F1
Alt
F11
mouse-1
foo
PageDown
ESC
UP
DOWN
mouse-2
Meta
EAT
DRINK
PF1
end
C-g
F9
F5
F6
w
c
\
Q
BACKSPACE
Delete
RIGHT
Break
LEFT
AltGr
Compose
F10
Shift
Option
Super
Cmd
Ctrl
Lwindow
ScrLock
start
Apps
NumLock
CapsLock
R
L
Windows
F2
Control
Home
Insert
BREAK
Edit
Hyper
HELP
F11>
up
down
prior
PageUp
next
END
HOME
End
Enter
Return
S-TAB
F4
e
LFD
kp-8
delete
ENTER
F
Open Recent
file
menu-bar
jump
bookmarks
edit
set
x
X
r
ExtendChar
Compose Character
Escape
a
Backspace
%
E
g
h
?
Do
INSERT
T
C-h
PNT
MRK
$
^
*
1
`
C-d
f11
f10
f9
CONTROL
q
SPACE
M-n
M-p
C-c ?
M-@key{TAB}
Tab
Down
Up
DELETE
LF
F13
F12
F8
F7
KP8
KP5
KP4
RETURN
DO
GOLD
F24
,
PF2
KP1
KP0
KP7
Help
V
v
H
ESC C-c
RCL
STO
OVER
RLL4
RLL3
SWAP
PREC
SYMB
POLR
FRAC
DEG
RAD
GRP
INV
FIX
ENG
SCI
FLT
HYP
MAP$
MAP^
MAP*
HYP MAX
HYP PROD
HYP SUM
INV MAX
INV SUM
MAX
PROD
SUM
CROSS
MTRN
MDET
MINV
...
LEN
IDNT
INDX
UNPK
PACK
WSIZ
A
BIN
OCT
HEX
DEC
INV NOT
INV AND
INV LSH
NXTP
PERM
INV FACT
INV GCD
RAGN
RAND
RE
IMAG
CLN2
RND
ABS
EXP
LN
TAN
COS
SIN
INV y^x
y^x
CONJ
SQRT
1/x
EXEC
<-
UNDO
+/-
EEX
/
'
OFF
EXIT
-
2
PI
+
3
@key{RET}
BUTTON-2
BEGIN
PRIOR
NEXT
arrow-down
arrow-up
cursor
Esc
C-x C-s
#
up/down
C-c C-t @key{SPC}
C-c C-x d
M-h
~


Regards,

-- 
Nicolas Goaziou

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

[Joshua Branson]

This is sooo cool!  Awesome!

P.S. Is it appropriate for me to congratulate people for their hard
effort on this list? Or should I keep my nerdy joy to myself?

Bastien <bzg@gnu.org> writes:

> 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!

Re: @key{...} mis-use (was: Using Org as the source format to generate org.texi)

[Eli Zaretskii]

> From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
> Cc: emacs-devel@gnu.org
> Date: Sat, 14 Apr 2018 19:10:29 +0200
> 
> Speaking of which, I grepped through the "doc/" directory for
> @key{something}, and uniquified the result.
> 
> Some of them are typos (e.g., @key{F11>}) and some stems from
> a confusion between @kbd and @key (e.g., @key{C-c C-t @key{SPC}}). Some
> are missing normalization (e.g., @kbd{arrow-up}) while others look odd
> (e.g., @kbd{PNT}).
> 
> Here are the 254 values. Someone(c) with write access to repository
> might want to fix some of them.

Done.