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!

[Stefan Monnier]

Post by Bastien
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

[Kaushal Modi]

Post by Stefan Monnier
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! :)

[Achim Gratz]

Post by Stefan Monnier

Post by Bastien
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.

[Bastien]

Hi Stefan,

Post by Stefan Monnier

Post by Bastien
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!

[Eli Zaretskii]

Date: Wed, 07 Mar 2018 01:22:47 +0100

Post by Stefan Monnier

Post by Bastien
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.

[Kaushal Modi]

Post by Eli Zaretskii
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.

[Bastien Guerry]

Hi Kaushal,

Post by Kaushal Modi
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

[Michael Albinus]

Post by Eli Zaretskii
Also, I see some omissions in converting the Texinfo manual to
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.

Post by Eli Zaretskii
Thanks.

Best regards, Michael.

[Bastien Guerry]

Hi Michael,

Post by Michael Albinus
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.

Post by Michael Albinus
And proofreading the Emacs 26 manual comes first.

Of course.

[Bastien Guerry]

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

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

[Glenn Morris]

Post by Stefan Monnier
Why wouldn't we use Org's manual.org in Emacs?

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

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

Post by Stefan Monnier

Post by Bastien
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?

[Bastien]

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

Good.

Post by Richard Stallman
Can Org express all the constructs of Texinfo?

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

Post by Richard Stallman
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.

[Nicolas Goaziou]

Hello,

Post by Richard Stallman
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,

[Eli Zaretskii]

Date: Sat, 10 Mar 2018 22:26:40 +0100
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.

[Michael Albinus]

Post by Nicolas Goaziou
Hello,

Hi Nicolas,

Post by Nicolas Goaziou

Post by Richard Stallman
Can Org express all the constructs of Texinfo?

Not out of the box.
However, it provides mechanisms to extend its syntax. For example,

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

Post by Nicolas Goaziou
Regards,

Best regards, Michael.

[Nicolas Goaziou]

Hello,

Post by Michael Albinus
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,

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

Post by Nicolas Goaziou

Post by Richard Stallman
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?

[Nicolas Goaziou]

Hello,

Post by Richard Stallman
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.

Post by Richard Stallman
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,

[Eli Zaretskii]

Date: Mon, 12 Mar 2018 15:07:34 +0100
@var, @kbd and @key are defined, in "org-manual.org", through
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
which one we should use and how configurable it should be.

How about using what texinfo.tex does?

which mean "underline" by default. Since it is ignored in the Texinfo
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.

[Nicolas Goaziou]

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

Post by Eli Zaretskii

Post by Nicolas Goaziou
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
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.

Post by Eli Zaretskii
@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,

[Eli Zaretskii]

Date: Mon, 12 Mar 2018 17:42:16 +0100
I may have missed the "elsewhere".

In my first message in this thread.
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.

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

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.

[Nicolas Goaziou]

Post by Eli Zaretskii
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

Post by Eli Zaretskii
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.

Post by Nicolas Goaziou
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.

[Eli Zaretskii]

Date: Mon, 12 Mar 2018 18:57:03 +0100

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.

conveniently" something else?

Yes, something else: we need a separate {{{key(...)}}} construct, or

Post by Eli Zaretskii

Post by Nicolas Goaziou
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

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.

[Nicolas Goaziou]

Post by Eli Zaretskii
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

Post by Eli Zaretskii
Yes, something else: we need a separate {{{key(...)}}} construct, or

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.

[Eli Zaretskii]

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,
but

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.

[Nicolas Goaziou]

Hello,

Post by Eli Zaretskii
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,

[Eli Zaretskii]

Date: Tue, 13 Mar 2018 18:24:44 +0100

Post by Eli Zaretskii
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.

[Nicolas Goaziou]

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.

[Nicolas Goaziou]

Hello,

Post by Eli Zaretskii
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,

[Eli Zaretskii]

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.
Here are the 254 values. Someone(c) with write access to repository
might want to fix some of them.

Done.

[Paul Eggert]

Post by Bastien
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.

[Bastien]

Hi Paul,

Post by Paul Eggert

Post by Bastien
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,

[Paul Eggert]

Post by Bastien
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.

[Achim Gratz]

Post by Paul Eggert
$(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.

[Achim Gratz]

Post by Achim Gratz
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:

[Paul Eggert]

Post by Achim Gratz
Sorry, I got distracted by a clogged drain pipe. Here's the Makefile

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

[Achim Gratz]

Post by Paul Eggert
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.

[Glenn Morris]

Post by Paul Eggert
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.)

[Phillip Lord]

Post by Glenn Morris

Post by Paul Eggert
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.

Post by Glenn Morris
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

[Glenn Morris]

Post by Phillip Lord

Post by Glenn Morris
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).

Post by Phillip Lord

Post by Glenn Morris
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.

[Achim Gratz]

Post by Glenn Morris
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.

Post by Glenn Morris
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.

[Phillip Lord]

Post by Achim Gratz

Post by Glenn Morris
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.

Post by Achim Gratz

Post by Glenn Morris
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

[Paul Eggert]

Post by Phillip Lord
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?

[Stefan Monnier]

Post by Paul Eggert
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").

Post by Paul Eggert
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.

Post by Paul Eggert
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

[Phillip Lord]

Post by Stefan Monnier

Post by Paul Eggert
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

[Radon Rosborough]

Post by Phillip Lord
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

[Phillip Lord]

Post by Radon Rosborough

Post by Phillip Lord
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

[Stefan Monnier]

Post by Phillip Lord
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

[Phillip Lord]

Post by Stefan Monnier

Post by Phillip Lord
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

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

Post by Bastien
Hi all,
thanks to Thomas' initiative and Nicolas' efforts, we now have Org's
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!