[RFC] Moving "manual.org" into core

[RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

"manual.org" was updated a month ago, and, so far, nobody complained
about it. So, I think it's a good time to discuss about what could be
done next.

The first obvious step is to move the file into "doc/" directory. Then
I assume we could delete "org.texi" and "org.info" there and generate
new ones from the Org file. For example, the following command, called
from the "manual.org" file,

    (let ((org-texinfo-logfiles-extensions
           (cons "texi" org-texinfo-logfiles-extensions)))
      (org-texinfo-export-to-info))

produces an "org.info" file without an "org.texi". It thus prevents
direct editing of "org.texi". I assume this could be called by "make
info" target.

So basically, the idea would be to not provide anymore an "org.texi"
file. Only "manual.org" and "org.info". Emacs developers already apply
fixes to ORG-NEWS, which is a plain Org file, so I guess it would not
make their life harder if "manual.org" replaces "org.texi".

WDYT?

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: [RFC] Moving "manual.org" into core

[Achim Gratz]

Nicolas Goaziou writes:
> "manual.org" was updated a month ago, and, so far, nobody complained
> about it. So, I think it's a good time to discuss about what could be
> done next.

The lack of complaints is unlikely to mean that everybody tried it and
found nothing to complain about.  I haven't had much time to do anything
with it so far, but I did at least check that I could use the build
system extension that I created while Tom was working on his version
with it.  The export to texi is still relatively slow, but since I have
a much faster machine now it works OK for me.  I have not yet tried how
long it would take on my old machine.

> The first obvious step is to move the file into "doc/" directory. Then
> I assume we could delete "org.texi" and "org.info" there and generate
> new ones from the Org file. For example, the following command, called
> from the "manual.org" file,
>
>     (let ((org-texinfo-logfiles-extensions
>            (cons "texi" org-texinfo-logfiles-extensions)))
>       (org-texinfo-export-to-info))
>
> produces an "org.info" file without an "org.texi". It thus prevents
> direct editing of "org.texi". I assume this could be called by "make
> info" target.

Maybe not directly in the way you show it here, but yes. 

For the record, the build system extension from years ago involves
creating a directory orgmanual, then you should symlink orgmanual.org to
the actual file in contrib/, then put the follwing Makefile there:

--8<---------------cut here---------------start------------->8---
TEXI2PDF+=--tidy
BEXP=$(BATCH) \
	--eval '(add-to-list '"'"'load-path "../lisp")' \
	--eval '(setq org-footnote-auto-adjust nil)'
EXTEXI=	-l ox-texinfo \
	--eval '(add-to-list '"'"'org-export-snippet-translation-alist '"'"'("info" . "texinfo"))'
EXHTML=	-l ox-html \
	$(BTEST_POST) \
	--eval '(add-to-list '"'"'org-export-snippet-translation-alist '"'"'("info" . "texinfo"))'
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 org.t2d *.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

--8<---------------cut here---------------start------------->8---

Then add the following to local.mk

--8<---------------cut here---------------end--------------->8---
.PHONY: orgmanual
EXTRADIRS=orgmanual
orgmanual:
	$(MAKE) -C $@
manclean:
	$(MAKE) -C orgmanual clean
mancleanall:
	$(MAKE) -C orgmanual cleanall
clean:	manclean
cleanall:	mancleanall
--8<---------------cut here---------------end--------------->8---

You can now say "make orgmanual" and have it do the right thing.  YOu
could even further extend local.mk so that the "doc" target includes the
new manual by adding this line:

--8<---------------cut here---------------end--------------->8---
doc:	orgmanual
--8<---------------cut here---------------end--------------->8---

The whole thing can easily be adapted to work in doc/ if it gets decided
that we should switch to manual.org (or better org.org maybe) as our
primary source file.

> So basically, the idea would be to not provide anymore an "org.texi"
> file. Only "manual.org" and "org.info". Emacs developers already apply
> fixes to ORG-NEWS, which is a plain Org file, so I guess it would not
> make their life harder if "manual.org" replaces "org.texi".

Yes, once the org file is our primary source we should stop provding the
texi file in Git at least.  I don't have any preference w.r.t. whether
an Org release tarball should still contain an org.texi or not, but
that's a separate decision.  I suspect that not delivering it would
inconvenience at least the Debian folks somewhat since they keep
insisting to use their own build recipes last I looked.  Last but not
least we'll have to check if we need any modifications for the ELPA
distributions.


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

Wavetables for the Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#BlofeldUserWavetables

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Achim Gratz <Stromeko@nexgo.de> writes:

Thank you for your answer. Some comments follow.

> The lack of complaints is unlikely to mean that everybody tried it and
> found nothing to complain about.

I didn't imply anything like that.

> The export to texi is still relatively slow,

I don't think it is much of a concern, since generating the texi file
only happens once in a while.

>> The first obvious step is to move the file into "doc/" directory. Then
>> I assume we could delete "org.texi" and "org.info" there and generate
>> new ones from the Org file. For example, the following command, called
>> from the "manual.org" file,
>>
>>     (let ((org-texinfo-logfiles-extensions
>>            (cons "texi" org-texinfo-logfiles-extensions)))
>>       (org-texinfo-export-to-info))
>>
>> produces an "org.info" file without an "org.texi". It thus prevents
>> direct editing of "org.texi". I assume this could be called by "make
>> info" target.
>
> Maybe not directly in the way you show it here, but yes. 
>
> For the record, the build system extension from years ago involves
> creating a directory orgmanual, then you should symlink orgmanual.org to
> the actual file in contrib/, then put the follwing Makefile there:
>
> TEXI2PDF+=--tidy
> BEXP=$(BATCH) \
> 	--eval '(add-to-list '"'"'load-path "../lisp")' \
> 	--eval '(setq org-footnote-auto-adjust nil)'

The second "--eval" is not needed.

> EXTEXI=	-l ox-texinfo \
> 	--eval '(add-to-list '"'"'org-export-snippet-translation-alist '"'"'("info" . "texinfo"))'
> EXHTML=	-l ox-html \
> 	$(BTEST_POST) \
> 	--eval '(add-to-list '"'"'org-export-snippet-translation-alist
> 	'"'"'("info" . "texinfo"))'

Both EXTEXI and EXHTML are not needed either.

> ORG2TEXI=-f org-texinfo-export-to-texinfo

Actually, I have another idea. We could implement a function generating
the manual, right in Org core. It can be useful for both packaging, like
the above, and for developers, who can update the manual on the fly.

Assuming the function above is called `org-generate-manuals', and
manual.org is located in doc/, what changes would be needed? I assume
they would be minimal.

> ORG2HTML=-f org-html-export-to-html

I think HTML should still be generated from the texi file. I assume
there is some compatibility to preserve among GNU manuals.

> ORG2INFO=--eval "(org-texinfo-compile \"./$<\")"

See above.

> I don't have any preference w.r.t. whether an Org release tarball
> should still contain an org.texi or not, but that's a separate
> decision. I suspect that not delivering it would inconvenience at
> least the Debian folks somewhat since they keep insisting to use their
> own build recipes last I looked. Last but not least we'll have to
> check if we need any modifications for the ELPA distributions.

What kind of modifications do you have in mind?

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Moving "manual.org" into core

[Achim Gratz]

Nicolas Goaziou writes:
> Actually, I have another idea. We could implement a function generating
> the manual, right in Org core. It can be useful for both packaging, like
> the above, and for developers, who can update the manual on the fly.

That should go into mk/org-fixup.el then.  I am not aware that any
packagers have actually picked those helper functions up, so the primary
aim should still be that "make doc" keeps things updated.

> Assuming the function above is called `org-generate-manuals', and
> manual.org is located in doc/, what changes would be needed? I assume
> they would be minimal.
>
>> ORG2HTML=-f org-html-export-to-html
>
> I think HTML should still be generated from the texi file. I assume
> there is some compatibility to preserve among GNU manuals.

We could and probably should provide an option for doing it both ways.
The intent back when was that sometimes one of the export paths did work
while the other didn't, so it was quite useful to have both available.

>> ORG2INFO=--eval "(org-texinfo-compile \"./$<\")"
>
> See above.

As I said, all of this is several years old and still working.

> What kind of modifications do you have in mind?

Nothing, unless we find something missing or wrong.  But at least we
need to check that it works as intended.


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

SD adaptation for Waldorf rackAttack V1.04R1:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Achim Gratz <Stromeko@nexgo.de> writes:

> Nicolas Goaziou writes:
>> Actually, I have another idea. We could implement a function generating
>> the manual, right in Org core. It can be useful for both packaging, like
>> the above, and for developers, who can update the manual on the fly.
>
> That should go into mk/org-fixup.el then.  I am not aware that any
> packagers have actually picked those helper functions up, so the primary
> aim should still be that "make doc" keeps things updated.

To be clear, I meant that "make doc" would call `org-generate-manuals'.
Isn't it enough?

> As I said, all of this is several years old and still working.

Probably, but that's a bit complicated.

Re: [RFC] Moving "manual.org" into core

[Thomas S. Dye]

Nicolas Goaziou writes:

> Hello,
>
> "manual.org" was updated a month ago, and, so far, nobody 
> complained
> about it. So, I think it's a good time to discuss about what 
> could be
> done next.
>
> The first obvious step is to move the file into "doc/" 
> directory. Then
> I assume we could delete "org.texi" and "org.info" there and 
> generate
> new ones from the Org file. For example, the following command, 
> called
> from the "manual.org" file,
>
>     (let ((org-texinfo-logfiles-extensions
>            (cons "texi" org-texinfo-logfiles-extensions)))
>       (org-texinfo-export-to-info))
>
> produces an "org.info" file without an "org.texi". It thus 
> prevents
> direct editing of "org.texi". I assume this could be called by 
> "make
> info" target.
>
> So basically, the idea would be to not provide anymore an 
> "org.texi"
> file. Only "manual.org" and "org.info". Emacs developers already 
> apply
> fixes to ORG-NEWS, which is a plain Org file, so I guess it 
> would not
> make their life harder if "manual.org" replaces "org.texi".
>
> WDYT?

+1

--
Thomas S. Dye
http://www.tsdye.com

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Nicolas,

> "manual.org" was updated a month ago, and, so far, nobody complained
> about it. So, I think it's a good time to discuss about what could be
> done next.

Having the manual in .org is a great achievement, congrats to anyone
who worked on this titanic task!

I'm all for editing manual.org instead of org.texi in the long run.

Before moving manual.org into doc/, I'd suggest we agree on editing
variables like `fill-column' and the like:

fill-column: 70
org-list-description-max-indent: 5
org-edit-src-content-indentation: ?
org-src-preserve-indentation: ?

This is necessary so that contributors don't mess up accidentally with
the desired format.

Can we grow a list here:
https://bimestriel.framapad.org/p/22KTn231su

Also, why are :PROPERTIES: drawers at the beginning of the line?  I
have them aligned with the headline in my configuration, which I find
much more readable. Can we fix this?

IMO the above questions should be resolved before exposing manual.org
to collaboration.

Some other micro-reports/requests, not blocking anything:

- Line 1013: Why an orphan dash?  Because of #+vindex entries?

- Line 1077: Why indenting this list ?

- It would be nice to have #+[kvc]index with multiple entries per line.

- Line 1303 : Why "- =[fn:NAME]= ::" lives on a single line here?

- Line 21228 ("possible, including the version"): a macro spanning
  over multiple lines is not fontified.

- Footnotes: it would be nice to get an overview of a footnote when
  the pointer is hovering on some [fn:x] reference.

> The first obvious step is to move the file into "doc/" directory. Then
> I assume we could delete "org.texi" and "org.info" there and generate
> new ones from the Org file. For example, the following command, called
> from the "manual.org" file,
>
>     (let ((org-texinfo-logfiles-extensions
>            (cons "texi" org-texinfo-logfiles-extensions)))
>       (org-texinfo-export-to-info))
>
> produces an "org.info" file without an "org.texi". It thus prevents
> direct editing of "org.texi". I assume this could be called by "make
> info" target.

We still need to create org.texi for inclusion into Emacs repository.

> So basically, the idea would be to not provide anymore an "org.texi"
> file. Only "manual.org" and "org.info". Emacs developers already apply
> fixes to ORG-NEWS, which is a plain Org file, so I guess it would not
> make their life harder if "manual.org" replaces "org.texi".
>
> WDYT?

I think it's a great step forward but a big one, so let's move
carefully here.

Thanks!

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Bastien Guerry <bzg@gnu.org> writes:

> Before moving manual.org into doc/, I'd suggest we agree on editing
> variables like `fill-column' and the like:
>
> fill-column: 70

This is already the case.

> org-list-description-max-indent: 5
> org-edit-src-content-indentation: ?

It is 2. I'd favor 0, but I don't care much.

> org-src-preserve-indentation: ?

nil.

> This is necessary so that contributors don't mess up accidentally with
> the desired format.

Why does it matter? We just put them in ".dir-locals.el" and be done
with it. They override user's preferences anyway.

> Can we grow a list here:
> https://bimestriel.framapad.org/p/22KTn231su
>
> Also, why are :PROPERTIES: drawers at the beginning of the line?

I set `org-adapt-indentation' to nil in the file above. It gives more
columns in a line, which I find more comfortable (e.g., text always
starts at the same column).

> I have them aligned with the headline in my configuration, which
> I find much more readable. Can we fix this?

There is nothing to "fix": this is a configuration option, per above.

> IMO the above questions should be resolved before exposing manual.org
> to collaboration.
>
> Some other micro-reports/requests, not blocking anything:
>
> - Line 1013: Why an orphan dash?  Because of #+vindex entries?

Yes.

> - Line 1077: Why indenting this list ?

Fixed. Note that it didn't change output.

> - It would be nice to have #+[kvc]index with multiple entries per
> line.

I'm not sure I'd like it. The current state eases reviewing all index
entries associated to a location.

> - Line 1303 : Why "- =[fn:NAME]= ::" lives on a single line here?

It is on a single line like almost every item definition in the file. Am
I missing something?

> - Line 21228 ("possible, including the version"): a macro spanning
>   over multiple lines is not fontified.

This is a fontification bug, unrelated to "manual.org". I suggest to
discuss about it in another thread.

> - Footnotes: it would be nice to get an overview of a footnote when
>   the pointer is hovering on some [fn:x] reference.

You can use C-c ' on a footnote reference.

> We still need to create org.texi for inclusion into Emacs repository.

Why do we need it? If it is mandatory (I fail to see why, since we
provide the source of the info file), can we include it read-only?

Note that I made a few design choices I didn't write about, e.g.,:

  - use fixed-width area for one-line examples,
  - use example blocks for Org syntax instead of "begin_src org",
  - internal links to headlines always start with a star,
  - tags, node properties, are not shown with the surrounding columns,
  - when to use =...= or ~...~ markup: 
    - files or extensions use =...=,
    - anything that is meant to be written in the Org buffer uses =...=,
    - any meaningful token in a programming language uses ~...~.

I used {{{var(...)}}} for meta-syntactic names, but we may simply use
capitals instead, depending on the output of HTML export. It doesn't
change anything in Info format.

Thank you for the review.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: [RFC] Moving "manual.org" into core

[Kaushal Modi]

[-- Attachment #1.1: Type: text/plain, Size: 1715 bytes --]

On Mon, Jan 22, 2018 at 8:51 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> > org-edit-src-content-indentation: ?
>
> It is 2. I'd favor 0, but I don't care much.
>

I also favor 0, less white space noise, the better.


> > This is necessary so that contributors don't mess up accidentally with
> > the desired format.
>
> Why does it matter? We just put them in ".dir-locals.el" and be done
> with it. They override user's preferences anyway.
>

+1


> > Also, why are :PROPERTIES: drawers at the beginning of the line?
>
> I set `org-adapt-indentation' to nil in the file above. It gives more
> columns in a line, which I find more comfortable (e.g., text always
> starts at the same column).
>

Another place where we can prevent unnecessary white space.

I have always started PROPERTIES at col 0. With org-indent-mode enabled, it
doesn't matter.. looks pretty (PROPERTY drawer in below screenshot actually
starts at col 0):

[image: image.png]


>   - use example blocks for Org syntax instead of "begin_src org",
>

I'd prefer "begin_src org". When these manuals are converted to HTML, we
can use syntax highlighting to format comments, etc in Org snippets. I
think it's good to retain the meta data that that is not an arbitrary block
of text, but Org data. Can you please revert to "begin_src org"?


>   - internal links to headlines always start with a star,
>

Nice.

  - tags, node properties, are not shown with the surrounding columns,
>   - when to use =...= or ~...~ markup:
>     - files or extensions use =...=,
>     - anything that is meant to be written in the Org buffer uses =...=,
>     - any meaningful token in a programming language uses ~...~.
>

Sounds good.


-- 

Kaushal Modi

[-- Attachment #1.2: Type: text/html, Size: 3150 bytes --]

[-- Attachment #2: image.png --]
[-- Type: image/png, Size: 9882 bytes --]

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> I'd prefer "begin_src org". When these manuals are converted to HTML, we
> can use syntax highlighting to format comments, etc in Org snippets. I
> think it's good to retain the meta data that that is not an arbitrary block
> of text, but Org data. Can you please revert to "begin_src org"?

"manual.org" is not meant to be exported to HTML through "ox-html", but
using Texinfo itself. AFAIK, Texinfo does not highlight specially Org
syntax, so using "begin_src org" is not very important for export.

Moreover, the advantage of using "begin_example" instead is:
1. we can use fixed-width for one-liners,
2. Org fontification for source blocks can be sometimes misleading,
   as you sometimes cannot what is an example and what is not.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: [RFC] Moving "manual.org" into core

[Kaushal Modi]

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

On Mon, Jan 22, 2018 at 11:02 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> "manual.org" is not meant to be exported to HTML through "ox-html", but
> using Texinfo itself. AFAIK, Texinfo does not highlight specially Org
> syntax, so using "begin_src org" is not very important for export.
>

I am hoping that using "begin_src org" preserves the meta data that a code
block is an Org snippet when the Org manual HTML pages are published on
orgmode.org.

Moreover, the advantage of using "begin_example" instead is:
> 1. we can use fixed-width for one-liners,
>

I personally don't see that as a big advantage. Whether the snippet is a
single line or more, one can just select those and use the Org structural
template insertion to wrap that with "#+begin_src org" .. "#+end_src".


> 2. Org fontification for source blocks can be sometimes misleading,
>    as you sometimes cannot what is an example and what is not.
>

I didn't understand that limitation. I use Org src blocks quite liberally
in this Org document[1], some even with nested non-Org src blocks.

#+BEGIN_SRC org :noweb-ref src-block-n-default-continue
,#+BEGIN_SRC emacs-lisp +n
;; This will be listed as line 22
(message "This is line 23")
,#+END_SRC
#+END_SRC

I haven't found any issue.

While pasting that example, I realized, that you don't even need to
specially made an Org snippet an src block just because you want to use it
as a noweb ref in the manual. Making Org snippets, src blocks, always, just
feels like the right thing.

[1]:
https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/all-posts.org


-- 

Kaushal Modi

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

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> I am hoping that using "begin_src org" preserves the meta data that a code
> block is an Org snippet when the Org manual HTML pages are published on
> orgmode.org.

Again, Org manual, as published in "orgmode.org", is generated through
Texinfo, which treats "begin_src org" exactly as "begin_example". So,
switching to "begin_src org" will not give us Org fontification in HTML
output.

> Moreover, the advantage of using "begin_example" instead is:
>> 1. we can use fixed-width for one-liners,
>>
>
> I personally don't see that as a big advantage. Whether the snippet is a
> single line or more, one can just select those and use the Org structural
> template insertion to wrap that with "#+begin_src org" .. "#+end_src".

This is not about typing. When the markup is more visible than the
contents, it is visual clutter.

>> 2. Org fontification for source blocks can be sometimes misleading,
>>    as you sometimes cannot what is an example and what is not.

> I didn't understand that limitation. I use Org src blocks quite liberally
> in this Org document[1], some even with nested non-Org src blocks.
>
> #+BEGIN_SRC org :noweb-ref src-block-n-default-continue
> ,#+BEGIN_SRC emacs-lisp +n
> ;; This will be listed as line 22
> (message "This is line 23")
> ,#+END_SRC
> #+END_SRC
>
> I haven't found any issue.

It is a matter of taste. I tested both when updating the manual, and
eventually settled for example blocks.

In any case, I have no strong opinion about it. I just lean towards
simplicity.

> While pasting that example, I realized, that you don't even need to
> specially made an Org snippet an src block just because you want to use it
> as a noweb ref in the manual. Making Org snippets, src blocks, always, just
> feels like the right thing.

I didn't understand this part.

Re: [RFC] Moving "manual.org" into core

[Kaushal Modi]

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

On Mon, Jan 22, 2018 at 12:20 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

>
> Again, Org manual, as published in "orgmode.org", is generated through
> Texinfo, which treats "begin_src org" exactly as "begin_example". So,
> switching to "begin_src org" will not give us Org fontification in HTML
> output.
>

Ah, OK. Understood now. I didn't know that.. would have been nice if that
meta data was somehow retained.


> This is not about typing. When the markup is more visible than the
> contents, it is visual clutter.
>

OK.

It is a matter of taste. I tested both when updating the manual, and
> eventually settled for example blocks.
>
> In any case, I have no strong opinion about it. I just lean towards
> simplicity.
>

Thank you. I'd like to see Org snippets in src blocks as they are not any
"raw" monospace text blocks. But if no one else has a strong opinion for
using src blocks for Org snippets, then I guess I'll have to concede.

> While pasting that example, I realized, that you don't even need to
> > specially made an Org snippet an src block just because you want to use
> it
> > as a noweb ref in the manual. Making Org snippets, src blocks, always,
> just
> > feels like the right thing.
>
> I didn't understand this part.
>

AFAIK noweb-ref can be used only for src blocks. So in the case you need to
use Org snippets as noweb refs, you would then need to make those Org
snippets src blocks instead of example blocks. I was just trying to make
that point.

Overall, I am glad to see consistency edits being made in the manual.. will
make it easier to contribute to it by just following by example.

Thanks.


-- 

Kaushal Modi

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

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> Thank you. I'd like to see Org snippets in src blocks as they are not any
> "raw" monospace text blocks. But if no one else has a strong opinion for
> using src blocks for Org snippets, then I guess I'll have to concede.

There is another issue with "begin_src org" blocks. If your example
contains a link, you only see the description part, not the whole
syntax. Thus

    #+begin_src org
      [[path][description]]
    #+end_src

is seen as

    #+begin_src org
      description
    #+end_src

which can be very confusing. There is no such issue with example blocks
and fixed-width areas.

Re: [RFC] Moving "manual.org" into core

[Kaushal Modi]

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

On Mon, Jan 22, 2018 at 2:52 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Kaushal Modi <kaushal.modi@gmail.com> writes:
>


> There is another issue with "begin_src org" blocks. If your example
> contains a link, you only see the description part, not the whole
> syntax. Thus
>
>     #+begin_src org
>       [[path][description]]
>     #+end_src
>
> is seen as
>
>     #+begin_src org
>       description
>     #+end_src
>
> which can be very confusing.
>

Wouldn't that qualify as a bug? Shouldn't text in src blocks always be
shown verbatim without any overlays? Use of example block instead of src
block using this as one of the reasons looks like a workaround.


-- 

Kaushal Modi

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

Re: [RFC] Moving "manual.org" into core

[Julius Dittmar]

Am 23.01.2018 um 16:19 schrieb Kaushal Modi:
>     There is another issue with "begin_src org" blocks. If your example
>     contains a link, you only see the description part, not the whole
>     syntax. Thus
> 
>         #+begin_src org
>           [[path][description]]
>         #+end_src
> 
>     is seen as
> 
>         #+begin_src org
>           description
>         #+end_src
> 
>     which can be very confusing.
> 
> 
> Wouldn't that qualify as a bug? Shouldn't text in src blocks always be
> shown verbatim without any overlays? Use of example block instead of src
> block using this as one of the reasons looks like a workaround.

I think not.

As far as I understood, a src block is tagged with a style information
so the appropriate emacs mode for displaying this kind of code is used.
So the second display is exactly what I'd expect.

Julius

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> On Mon, Jan 22, 2018 at 2:52 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
>> There is another issue with "begin_src org" blocks. If your example
>> contains a link, you only see the description part, not the whole
>> syntax. Thus
>>
>>     #+begin_src org
>>       [[path][description]]
>>     #+end_src
>>
>> is seen as
>>
>>     #+begin_src org
>>       description
>>     #+end_src
>>
>> which can be very confusing.
>>
>
> Wouldn't that qualify as a bug? Shouldn't text in src blocks always be
> shown verbatim without any overlays?

If `org-src-fontify-natively' is non-nil, contents of source blocks is
not shown verbatim. In this particular case, contents are displayed as
in an Org buffer, which means links are partly invisible.

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Moving "manual.org" into core

[Kaushal Modi]

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

On Tue, Jan 23, 2018 at 11:33 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

>
> If `org-src-fontify-natively' is non-nil, contents of source blocks is
> not shown verbatim. In this particular case, contents are displayed as
> in an Org buffer, which means links are partly invisible.
>

Thanks. That makes sense. It's almost as if fontification should be
separated from overlay application (or whichever technique is used to make
the links invisible).

But with how the things are, looks like example blocks is the way to go to
prevent the link hiding in Org snippets.


-- 

Kaushal Modi

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

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Kaushal,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> I have always started PROPERTIES at col 0. With org-indent-mode
> enabled, it doesn't matter.. looks pretty (PROPERTY drawer in below
> screenshot actually starts at col 0):

what do you think of the proposal to have

  (setq org-adapt-indentation 'content)

set :PROPERTIES: aligned with the beginning of the headline,
while leaving content unindented?

I'd also like to have the better of both worlds without the
need to use `org-indent-mode'.

Thanks for your feedback!

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Kaushal Modi]

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

On Mon, Jan 22, 2018 at 11:35 AM Bastien Guerry <bzg@gnu.org> wrote:

> what do you think of the proposal to have
>
>   (setq org-adapt-indentation 'content)
>
> set :PROPERTIES: aligned with the beginning of the headline,
> while leaving content unindented?
>
> I'd also like to have the better of both worlds without the
> need to use `org-indent-mode'.
>

I cannot draw an opinion on that, as I have used org-indent-mode for many
years.. it "just works".

With the default value of org-indent-mode-turns-off-org-adapt-indentation
being non-nil, org-adapt-indention is auto-set to nil with org-indent-mode
enabled. So for all my use cases, org-adapt-indentation has always been nil
(which I learn today :) ).

In summary, I prefer to have no indentation anywhere (PROPERTIES, content,
src blocks (I set org-edit-src-content-indentation to 0 in my config.. I
never understood why the 2-space indentation was there by default))..
org-indent-mode simply takes care of everything.


-- 

Kaushal Modi

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

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Kaushal Modi <kaushal.modi@gmail.com> writes:

>       - use example blocks for Org syntax instead of "begin_src org",
>
>
> I'd prefer "begin_src org". When these manuals are converted to HTML,
> we can use syntax highlighting to format comments, etc in Org
> snippets. I think it's good to retain the meta data that that is not
> an arbitrary block of text, but Org data. Can you please revert to
> "begin_src org"?

I agree this makes sense.

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Nicolas,

thanks for your answer.

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> fill-column: 70
>
> This is already the case.

Okay, I've found .dir-locals.el.

>> org-list-description-max-indent: 5
>> org-edit-src-content-indentation: ?
>
> It is 2. I'd favor 0, but I don't care much.

I've added (org-list-description-max-indent . 5)

>> org-src-preserve-indentation: ?
>
> nil.

OK.

>> This is necessary so that contributors don't mess up accidentally with
>> the desired format.
>
> Why does it matter? We just put them in ".dir-locals.el" and be done
> with it. They override user's preferences anyway.

I meant: it matters to have .dir-locals.el, so we're all set.

>> Can we grow a list here:
>> https://bimestriel.framapad.org/p/22KTn231su
>>
>> Also, why are :PROPERTIES: drawers at the beginning of the line?
>
> I set `org-adapt-indentation' to nil in the file above. It gives more
> columns in a line, which I find more comfortable (e.g., text always
> starts at the same column).

Me too, for the same argument.  But this points to a strong limitation
to `org-adapt-indentation' for which I'd like to propose this change.

       (setq org-adapt-indentation t) => current behavior
     (setq org-adapt-indentation nil) => current behavior
(setq org-adapt-indentation 'content) => only adapt content's
     indentation, not that of the property drawer.

Having the property drawer at the beginning of the line while all
other metadata (e.g. SCHEDULED etc.) are aligned with the beginning
of the headline's content feels wrong.

Would anyone else use (setq org-adapt-indentation 'content) ?

>> - Line 1013: Why an orphan dash?  Because of #+vindex entries?
>
> Yes.

This is definitely a corner-case, but can we imagine another way of
adding #+vindex entries here?

>> - Line 1077: Why indenting this list ?
>
> Fixed. Note that it didn't change output.

Thanks.  Noted.

>> - It would be nice to have #+[kvc]index with multiple entries per
>> line.
>
> I'm not sure I'd like it. The current state eases reviewing all index
> entries associated to a location.

Not that important anyway.

>> - Line 1303 : Why "- =[fn:NAME]= ::" lives on a single line here?
>
> It is on a single line like almost every item definition in the file. Am
> I missing something?

I was noticing different styles, just wondering if there was a
favorite one, as contributors may ask themselves.

>> - Line 21228 ("possible, including the version"): a macro spanning
>>   over multiple lines is not fontified.
>
> This is a fontification bug, unrelated to "manual.org". I suggest to
> discuss about it in another thread.

Sure.

>> - Footnotes: it would be nice to get an overview of a footnote when
>>   the pointer is hovering on some [fn:x] reference.
>
> You can use C-c ' on a footnote reference.

An "electric" display would also be good IMO.

>> We still need to create org.texi for inclusion into Emacs repository.
>
> Why do we need it? If it is mandatory (I fail to see why, since we
> provide the source of the info file), can we include it read-only?

It is mandatory, as long as the GNU standard for documentation is to
provide it as a .texi file.

I don't think providing it read-only is a good idea: people should be
able to edit it and provide patches against it, even though we prefer
to encourage patches against manual.org.

> Note that I made a few design choices I didn't write about, e.g.,:
>
>   - use fixed-width area for one-line examples,

Agreed.

>   - use example blocks for Org syntax instead of "begin_src org",

Agreed.

>   - internal links to headlines always start with a star,

No problem.  Is the leading star optional?

>   - tags, node properties, are not shown with the surrounding columns,
>   - when to use =...= or ~...~ markup: 
>     - files or extensions use =...=,
>     - anything that is meant to be written in the Org buffer uses =...=,
>     - any meaningful token in a programming language uses ~...~.
>
> I used {{{var(...)}}} for meta-syntactic names, but we may simply use
> capitals instead, depending on the output of HTML export. It doesn't
> change anything in Info format.

I guess the above should be part of a guideline on how to contribute
to manual.org - which btw should better be named org.org.

To be continued,

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Bastien Guerry <bzg@gnu.org> writes:

> I've added (org-list-description-max-indent . 5)

OK.

> Me too, for the same argument.  But this points to a strong limitation
> to `org-adapt-indentation' for which I'd like to propose this change.
>
>        (setq org-adapt-indentation t) => current behavior
>      (setq org-adapt-indentation nil) => current behavior
> (setq org-adapt-indentation 'content) => only adapt content's
>      indentation, not that of the property drawer.

I proposed this very change some years ago, but it didn't get much
traction and wasn't implemented in the end.

>>> - Line 1013: Why an orphan dash?  Because of #+vindex entries?
>>
>> Yes.
>
> This is definitely a corner-case, but can we imagine another way of
> adding #+vindex entries here?

You can add the #+vindex entries at the end of the paragraph instead of
its beginning. However, cross references then point to the end of the
paragraph. I think the current state is better.

> I was noticing different styles, just wondering if there was a
> favorite one, as contributors may ask themselves.

Tag alone on its line is the favorite one because you cannot always
achieve the other option, i.e., contents on the same line as the tag.

> An "electric" display would also be good IMO.

Not sure what you mean here.

> It is mandatory, as long as the GNU standard for documentation is to
> provide it as a .texi file.

Too bad.

> I don't think providing it read-only is a good idea: people should be
> able to edit it and provide patches against it, even though we prefer
> to encourage patches against manual.org.

Is it really a bad idea to discourage people from editing an
auto-generated file? In any case, I have no strong opinion about this.

>>   - internal links to headlines always start with a star,
>
> No problem.  Is the leading star optional?

Of course. Without it, however, the internal link tries to match
a #+name keyword or a target first.

>>   - tags, node properties, are not shown with the surrounding columns,
>>   - when to use =...= or ~...~ markup: 
>>     - files or extensions use =...=,
>>     - anything that is meant to be written in the Org buffer uses =...=,
>>     - any meaningful token in a programming language uses ~...~.
>>
>> I used {{{var(...)}}} for meta-syntactic names, but we may simply use
>> capitals instead, depending on the output of HTML export. It doesn't
>> change anything in Info format.
>
> I guess the above should be part of a guideline on how to contribute
> to manual.org

Probably, but this is not important as long as manual.org has not moved
to core, IMO.

> - which btw should better be named org.org.

Why is that? "manual.org" is a lot more explicit. What is better in
"org.org"? Note that "manual.org" already exports to "org.texi".

org-adapt-indentation 'content (was Re: [RFC] Moving "manual.org" into core)

[Christian Moe]

Nicolas Goaziou writes:

> Bastien Guerry <bzg@gnu.org> writes:
>
>> I've added (org-list-description-max-indent . 5)
>
> OK.
>
>> Me too, for the same argument.  But this points to a strong limitation
>> to `org-adapt-indentation' for which I'd like to propose this change.
>>
>>        (setq org-adapt-indentation t) => current behavior
>>      (setq org-adapt-indentation nil) => current behavior
>> (setq org-adapt-indentation 'content) => only adapt content's
>>      indentation, not that of the property drawer.
>
> I proposed this very change some years ago, but it didn't get much
> traction and wasn't implemented in the end.

FWIW, I'd like this.

Yours,
Christian

Re: org-adapt-indentation 'content (was Re: [RFC] Moving "manual.org" into core)

[Bastien Guerry]

Hi Nicolas,

Christian Moe <mail@christianmoe.com> writes:

>>> Me too, for the same argument.  But this points to a strong limitation
>>> to `org-adapt-indentation' for which I'd like to propose this change.
>>>
>>>        (setq org-adapt-indentation t) => current behavior
>>>      (setq org-adapt-indentation nil) => current behavior
>>> (setq org-adapt-indentation 'content) => only adapt content's
>>>      indentation, not that of the property drawer.
>>
>> I proposed this very change some years ago, but it didn't get much
>> traction and wasn't implemented in the end.
>
> FWIW, I'd like this.

Just to make sure we don't lose this idea: do you have code for this?

If not, I'll put a stab at it, I think it would be nice.

Thanks!

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Achim Gratz]

Bastien Guerry writes:
>> Why do we need it? If it is mandatory (I fail to see why, since we
>> provide the source of the info file), can we include it read-only?
>
> It is mandatory, as long as the GNU standard for documentation is to
> provide it as a .texi file.

It can always be generated for the Emacs export.  But it should cease to
exist in the Git repo since it becomes a derivative of manual.org.

> I don't think providing it read-only is a good idea: people should be
> able to edit it and provide patches against it, even though we prefer
> to encourage patches against manual.org.

No, I'd strongly discourage that and accept such edits only in
exceptional cases.  If the source file is manual.org, all patches or
other changes need to be against the source.  You wouldn't accept
patches to the PDF of the manual or any such thing, do you?


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

Samples for the Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#BlofeldSamplesExtra

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Bastien Guerry <bzg@gnu.org> writes:

> To be continued,

I'm bumping the thread. What is still needed for that to move forward?
Again, the first step could be to move manual.org to core and have it
generate a new org.texi, overwriting the previous one.

I would also be nice to think about what can be done to automatically
generate org.texi upon releases, and remove it from the repository. But
that can come later.


Regards,

-- 
Nicolas Goaziou

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Nicolas,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> I'm bumping the thread. What is still needed for that to move
> forward?

Nothing, please move ahead.

I suggest to rename the file org.org, which will produce org.texi.

Or org-manual.org, which seems more readable.

It would be great to have org-guide.org too, but I guess that's a
lot of work.

> Again, the first step could be to move manual.org to core and have
> it generate a new org.texi, overwriting the previous one.

Yes, let's do that manually for now.

> I would also be nice to think about what can be done to automatically
> generate org.texi upon releases, and remove it from the repository. But
> that can come later.

Indeed.

Sorry it took me long to give the green light on this, I was trying
to anticipate all possible outcomes.

One of my worries was that moving toward editing a manual in .org
does not match GNU developers good practices and habits, which are
to edit .texi files.  But as long as the .texi file exists I guess
we can shake the habits by allowing to edit .org files, which are
more convenient to read and write.

Hopefully this step forward will help create a useful precedent
amont GNU developers.

Thanks to you and to anyone who has been involved in making this
possible!

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Bastien Guerry <bzg@gnu.org> writes:

> Nothing, please move ahead.

Great.

> I suggest to rename the file org.org, which will produce org.texi.

I don't understand this part. Currently, "manual.org" is exported as
"org.texi" per

  #+export_file_name: org.texi

So we are getting the best of both worlds. Am I missing something?

> Or org-manual.org, which seems more readable.

I think "manual.org" is simpler, but I do not mind renaming it to
"org-manual.org". However, I find "org.org" silly.

In any case, I let you decide the name before moving forward.

> It would be great to have org-guide.org too, but I guess that's a
> lot of work.

It's a joke compared to manual.org. However, we first need to agree on
a style guide for "manual.org".

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Nicolas,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> I don't understand this part. Currently, "manual.org" is exported as
> "org.texi" per
>
>   #+export_file_name: org.texi
>
> So we are getting the best of both worlds. Am I missing something?

No, I was missing the "#+export_file_name: org.texi" part.

>> Or org-manual.org, which seems more readable.
>
> I think "manual.org" is simpler, but I do not mind renaming it to
> "org-manual.org". However, I find "org.org" silly.
>
> In any case, I let you decide the name before moving forward.

I don't have a strong opinion on this.

The rationale for using org.org (which, I agree, sounds a bit
childish) is that this is the current convention for naming GNU
manual is [package-name].[extension].

See emacs.texi, gnus.texi, calc.texi, etc.

If using Org becomes popular, it makes sense to have emacs.org,
gnus.org, calc.org but I find emacs-manual.org, gnus-manual.org
calc-manual.org to be cumbersome.

Ok, we're not there yet, I know :)

But still: RMS recently raised the question on emacs-devel of
whether using .rst for the GNU documentation would be better,
so using .org for this purpose is not entirely hypothetical.

What people think?  Let's just collect votes on this.

+1 for org.org

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Joseph Vidal-Rosset]

Le sam. 03 mars 2018 à  04:57:33 , Bastien Guerry <bzg@gnu.org> a envoyé
ce message:
> The rationale for using org.org (which, I agree, sounds a bit
> childish) is that this is the current convention for naming GNU
> manual is [package-name].[extension].
>
> See emacs.texi, gnus.texi, calc.texi, etc.
>
> If using Org becomes popular, it makes sense to have emacs.org,
> gnus.org, calc.org but I find emacs-manual.org, gnus-manual.org
> calc-manual.org to be cumbersome.
>
> Ok, we're not there yet, I know :)
>
> But still: RMS recently raised the question on emacs-devel of
> whether using .rst for the GNU documentation would be better,
> so using .org for this purpose is not entirely hypothetical.
>
> What people think?  Let's just collect votes on this.
>
> +1 for org.org

I agree. An  expression that is both justified by  a convention and that
sounds silly  or childish, is  like a slogan  that everybody has  fun to
repeat: "org.org" is terrific !

+1 for org.org

Jo. 

Re: [RFC] Moving "manual.org" into core

[Glenn Morris]

I'm sure this is an impressive technical achievement, but can I urge you
to raise this on emacs-devel first, because I think it's potentially
problematic.

I'm not entirely sure what you are proposing here. If the .org version
will become the "preferred form" for modification, it would eg need to
be in the Emacs repository (when the time comes), with suitable Makefile
rules for generating the final products from it, and distributed
correctly in releases. Emacs has got into trouble before in this area.

Bastien Guerry wrote:

> One of my worries was that moving toward editing a manual in .org
> does not match GNU developers good practices and habits, which are
> to edit .texi files.  But as long as the .texi file exists I guess
> we can shake the habits by allowing to edit .org files, which are
> more convenient to read and write.

Speaking for myself, I don't want to learn yet another markup syntax for
one single Emacs manual. I find it unlikely that GNU projects will start
requiring Emacs to build their documentation. Although the GNU coding
standards do say:

https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html#GNU-Manuals

    Nowadays some other formats such as Docbook and Sgmltexi can be
    converted automatically into Texinfo. It is ok to produce the Texinfo
    documentation by conversion this way, as long as it gives good results. 

so there's no problem from that aspect.

> But still: RMS recently raised the question on emacs-devel of
> whether using .rst for the GNU documentation would be better,
> so using .org for this purpose is not entirely hypothetical.

On the subject of rst, I can only find a topic two years ago that went
nowhere, and note in particular this:

http://lists.gnu.org/archive/html/emacs-devel/2016-02/msg00667.html

   "We don't want to replace Texinfo as the source language"


Maybe I'm worried about nothing, but I do suggest asking on emacs-devel.

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Glenn,

Glenn Morris <rgm@gnu.org> writes:

> Maybe I'm worried about nothing, but I do suggest asking on emacs-devel.

Thanks for your feedback.

You are definitely not worried about nothing.  I share some of your
worries.

To speak the truth, I first thought migrating to org as the preferred
format for editing the manual was just a bad idea.

More precisely: we went from "Oh, it would be nice to have the Org
manual in org" from "Hey, we have it now, why not make the switch?"

But in the process, we didn't define what were the problems we were
tryig to solve.  At least ones that core contributors agreed on.  Or
maybe I missed this discussion.  But no contributor complained about
.texi being such an horrible format for documentation.  I, for one,
feel like it's a very good format, with its apparent rigidity making
for careful contributions, while .org flexibility will bring us new
problems.

That said, why do I accept now?

It is *not* to honor people's work - although that kind of move is
very tempting, because I'm impressed by this achievement and don't
want to waste people's time.

I would define the problem we are trying to solve like this:

  We don't have enough manual contributors.  Many Org users report
  problems in the manual without proposing a patch, probably they
  afraid of making mistakes against a .texi file, so let's make it
  easier for them.

So I do accept to make the switch as a 1-year experiment.

During this year, the process of updating org.texi in Emacs branch
will not change: we will produce org.texi in org-mode/doc/ and then
sync it with Emacs as we do now.

There are very few direct edits of org.texi within Emacs, so we can
handle those changes by hand for now.

The switch will help us move forward like this:

- Let's stabilize editing standards around the org.org file.

- Let's test org capabilities against a giant .org file.

- Let's make `C-x 4 a' do something useful in an .org section.

- Let's write more non-emacs parsers and exporters.

- Let's see if we have more contributions to the manual and if
  we really solved a problem here.

If, in one year, we don't have more contributors and don't feel
the switch made us progress on anything above, and instead is a
blocker to get Org code directly edited from within Emacs, then
we can simply go back to editing org.texi directly.

So thanks for suggesting to bring this to emacs-devel: I will
do it later today, and we won't make the switch before getting
more feedback.  But let's not get blocked by false alarms!

Best,

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Thomas S. Dye]

Aloha all,

Nicolas Goaziou writes:

>
> Note that I made a few design choices I didn't write about, 
> e.g.,:
>
>   - use fixed-width area for one-line examples,
>   - use example blocks for Org syntax instead of "begin_src 
>   org",
>   - internal links to headlines always start with a star,
>   - tags, node properties, are not shown with the surrounding 
>   columns,
>   - when to use =...= or ~...~ markup:
>     - files or extensions use =...=,
>     - anything that is meant to be written in the Org buffer 
>     uses =...=,
>     - any meaningful token in a programming language uses ~...~.

I'd like to follow up on an earlier suggestion to put together a 
style guide for manual.org based on Phil Rooke's 
Documentation_Standards.org.  The idea was to "translate" Phil's 
document to follow the change from .texi source to .org source.

I think it will prove useful to have design choices described 
together in one place.

I've copied Phil in case he objects to having his "Notes to myself 
..." document used in this way.

Any comments welcome.

All the best,
Tom

--
Thomas S. Dye
http://www.tsdye.com

Re: [RFC] Moving "manual.org" into core

[Rasmus]

Bastien Guerry <bzg@gnu.org> writes:

> I'm all for editing manual.org instead of org.texi in the long run.
>
> Before moving manual.org into doc/, I'd suggest we agree on editing
> variables like `fill-column' and the like:
>
> fill-column: 70
> org-list-description-max-indent: 5
> org-edit-src-content-indentation: ?
> org-src-preserve-indentation: ?
>
> This is necessary so that contributors don't mess up accidentally with
> the desired format.

Could we use .dir-locals.el to ensure that the correct settings are
loaded?

As for their values, I have no strong preferences, but I’d prefer settings
are either automatically loaded or that they are like the default settings
so that one can just use "emacs -q".

Rasmus

-- 
Not everything that goes around comes back around, you know

Re: [RFC] Moving "manual.org" into core

[Kaushal Modi]

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

On Mon, Jan 22, 2018 at 8:56 AM Rasmus <rasmus@gmx.us> wrote:

>
> Could we use .dir-locals.el to ensure that the correct settings are
> loaded?
>

+1

As for their values, I have no strong preferences, but I’d prefer settings
> are either automatically loaded or that they are like the default settings
> so that one can just use "emacs -q".
>

+1


-- 

Kaushal Modi

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

Re: [RFC] Moving "manual.org" into core

[Yasushi SHOJI]

Hi,

On Mon, Jan 22, 2018 at 10:54 PM, Rasmus <rasmus@gmx.us> wrote:
> Bastien Guerry <bzg@gnu.org> writes:
>
>> I'm all for editing manual.org instead of org.texi in the long run.
>>
>> Before moving manual.org into doc/, I'd suggest we agree on editing
>> variables like `fill-column' and the like:
>>
>> fill-column: 70
>> org-list-description-max-indent: 5
>> org-edit-src-content-indentation: ?
>> org-src-preserve-indentation: ?
>>
>> This is necessary so that contributors don't mess up accidentally with
>> the desired format.
>
> Could we use .dir-locals.el to ensure that the correct settings are
> loaded?

How about using org-lint or some other formatter on git commit hook?
after go lang introduced gofmt, many projects adapted the method to
keep the code constant.

too much / slow?
-- 
              yashi

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Yasushi SHOJI <yasushi.shoji@gmail.com> writes:

> How about using org-lint or some other formatter on git commit hook?
> after go lang introduced gofmt, many projects adapted the method to
> keep the code constant.

Org Lint is not a formatter. It detects common mistakes or hypothetical
mistakes in an Org document, e.g., invalid links. In particular, it
doesn't detect stylistic issues like those discussed above.

It doesn't mean we couldn't run it automatically. However, it also emits
warnings (see `trust' property) on perfectly valid syntax.

As a side note, writing an Org formatter is trivial:

    (when (yes-or-no-p "Really format current buffer ? ")
      (let ((document (org-element-interpret-data (org-element-parse-buffer))))
        (erase-buffer)
        (insert document)
        (goto-char (point-min))))

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Moving "manual.org" into core

[Yasushi SHOJI]

Hi Nicolas,

On Wed, Jan 24, 2018 at 8:28 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> Org Lint is not a formatter. It detects common mistakes or hypothetical
> mistakes in an Org document, e.g., invalid links. In particular, it
> doesn't detect stylistic issues like those discussed above.

Oh, OK.

> It doesn't mean we couldn't run it automatically. However, it also emits
> warnings (see `trust' property) on perfectly valid syntax.
>
> As a side note, writing an Org formatter is trivial:
>
>     (when (yes-or-no-p "Really format current buffer ? ")
>       (let ((document (org-element-interpret-data (org-element-parse-buffer))))
>         (erase-buffer)
>         (insert document)
>         (goto-char (point-min))))

You know, this is a mind-blowing.  Org already has everything it needs ;-)

Anyway, I tried the code and it took 2.4 second to reformat the whole document
on my i5-3360M 2.80GHz CPU.  It's a bit long for every commit, i guess.
But, could be installed on received hook, perhaps?

Also, the code converts all lower case "#+title",  "+begin_src" and
other "#+"s to
the UPCASE.  Is this intended?  I thought we are moving away from CAP to lower?
-- 
             yashi

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Yasushi SHOJI <yasushi.shoji@gmail.com> writes:

> Also, the code converts all lower case "#+title",  "+begin_src" and
> other "#+"s to
> the UPCASE.  Is this intended?  I thought we are moving away from CAP
> to lower?

This was changed a few days ago. See commit
13424336a6f30c50952d291e7a82906c1210daf0.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: [RFC] Moving "manual.org" into core

[Yasushi SHOJI]

Hi Nicolas,

On Fri, Jan 26, 2018 at 7:32 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> Yasushi SHOJI <yasushi.shoji@gmail.com> writes:
>
>> Also, the code converts all lower case "#+title",  "+begin_src" and
>> other "#+"s to
>> the UPCASE.  Is this intended?  I thought we are moving away from CAP
>> to lower?
>
> This was changed a few days ago. See commit
> 13424336a6f30c50952d291e7a82906c1210daf0.

Thanks.  I pulled the head and read that.

I still see quite a lot of changes when I reformat the
manual.org.

A big one seems to be the indentation of description lists.
The formatter seems to prefer aligning the begging of a description
to the begging of a term.  But manual.org has some indentation.

The other big one is indentation of begin_example.  I'm not sure
this one is my setting or not.

Some minor diff is caused by links.  The formatter doesn't fold a
paragraph when link is at the end of the line. That is, if a paragraph
has a [[link like this]], the line goes on and on till the next fold
point.
-- 
             yashi

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Yasushi SHOJI <yasushi.shoji@gmail.com> writes:

> A big one seems to be the indentation of description lists.
> The formatter seems to prefer aligning the begging of a description
> to the begging of a term.  But manual.org has some indentation.

Somewhat fixed. The indentation of description items is weird.

> The other big one is indentation of begin_example.  I'm not sure
> this one is my setting or not.

Have you set `org-src-preserve-indentation' or
`org-edit-src-content-indentation'?

> Some minor diff is caused by links.  The formatter doesn't fold a
> paragraph when link is at the end of the line. That is, if a paragraph
> has a [[link like this]], the line goes on and on till the next fold
> point.

Not sure how to fix this, or even if that should be fixed.

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Moving "manual.org" into core

[Yasushi SHOJI]

Hi,

On Mon, Jan 29, 2018 at 12:17 AM, Nicolas Goaziou
<mail@nicolasgoaziou.fr> wrote:
> Yasushi SHOJI <yasushi.shoji@gmail.com> writes:
>
>> A big one seems to be the indentation of description lists.
>> The formatter seems to prefer aligning the begging of a description
>> to the begging of a term.  But manual.org has some indentation.
>
> Somewhat fixed. The indentation of description items is weird.

I confirm that.

Thank you, always, for your great work!

>> The other big one is indentation of begin_example.  I'm not sure
>> this one is my setting or not.
>
> Have you set `org-src-preserve-indentation' or
> `org-edit-src-content-indentation'?

Nop.

`org-src-preserve-indentation'  is nil.
`org-edit-src-content-indentation' is 2.

But, formatter still align the contents to 0.

Do you see this on your env?  Or, is it just me?

>> Some minor diff is caused by links.  The formatter doesn't fold a
>> paragraph when link is at the end of the line. That is, if a paragraph
>> has a [[link like this]], the line goes on and on till the next fold
>> point.
>
> Not sure how to fix this, or even if that should be fixed.

I'd like to have the formatter and `fill-paragraph` work in a coherent way.
But, if you, who know org much better than me, don't know, I don't think
I can help.  Though, just in case, can you elaborate a bit?


Since you fixed the big ones, I can see another issue.  This is also indentation
issue, but with a macro replacement .  Somehow, macro replacement
gets extra indentation.  Like this:

@@ -6226,7 +6200,7 @@ schedule an item:[fn:65]
      or which will become due within ~org-deadline-warning-days~.
      With {{{kbd(C-u)}}} prefix, show all deadlines in the file.  With
      a numeric prefix, check that many days.  For example, {{{kbd(C-1
-     C-c / d)}}} shows all deadlines due tomorrow.
+          C-c / d)}}} shows all deadlines due tomorrow.
-- 
             yashi

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Yasushi SHOJI <yasushi.shoji@gmail.com> writes:

> Do you see this on your env?  Or, is it just me?

I don't see anything like this.

> I'd like to have the formatter and `fill-paragraph` work in a coherent way.
> But, if you, who know org much better than me, don't know, I don't think
> I can help.  Though, just in case, can you elaborate a bit?

The formatter doesn't call `fill-paragraph' at all. No wonder both do
not work in a way you would expect. 

The newline characters introduced in the output of the formatter were
present already in the original text. However, some objects ignore white
spaces on purpose. For example, [[foo bar]] and [[foo bar]] and [[foo\n
bar]] are equivalent, so the parser does not retain the distinction
between them. Hence links are always formatted on a single line.

Now, I'm not sure the formatter should call `fill-paragraph', for some
reasons:

- the original document could be using `visual-line-mode' so there's
  could be nothing to fill without Org knowing about it;

- Calling `fill-paragraph' requires full fontification, so `org-mode'
  would be initialised at every paragraph to fill;

- `fill-paragraph' depends heavily on user's configuration (custom link
  types, `org-fontify-emphasized-text', `org-hide-emphasis-markers',
  `org-pretty-entities'...) whereas the formatter is expected to be more
  neutral.

We could however, un-fill everything. But the output would be very
different. So, TRTD is not obvious.

> Since you fixed the big ones, I can see another issue.  This is also indentation
> issue, but with a macro replacement .  Somehow, macro replacement
> gets extra indentation.  Like this:

>       a numeric prefix, check that many days.  For example, {{{kbd(C-1
> -     C-c / d)}}} shows all deadlines due tomorrow.
> +          C-c / d)}}} shows all deadlines due tomorrow.

This is related to the explanation above. Macros did the opposite of
links. The parser didn't remove meaningless spaces upon parsing macros.
So those would be inserted twice. I fixed this. Now macros show the same
behaviour as links: even multi-lines macros are inserted as a single
line.

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Moving "manual.org" into core

[Yasushi SHOJI]

Hi,

On Mon, Jan 29, 2018 at 11:41 PM, Nicolas Goaziou
<mail@nicolasgoaziou.fr> wrote:
> Yasushi SHOJI <yasushi.shoji@gmail.com> writes:
>
>> Do you see this on your env?  Or, is it just me?
>
> I don't see anything like this.

Hmm... I don't know how to fix this.

>> I'd like to have the formatter and `fill-paragraph` work in a coherent way.
>> But, if you, who know org much better than me, don't know, I don't think
>> I can help.  Though, just in case, can you elaborate a bit?
>
> The formatter doesn't call `fill-paragraph' at all. No wonder both do
> not work in a way you would expect.

ah, ok.

> The newline characters introduced in the output of the formatter were
> present already in the original text. However, some objects ignore white
> spaces on purpose. For example, [[foo bar]] and [[foo bar]] and [[foo\n
> bar]] are equivalent, so the parser does not retain the distinction
> between them. Hence links are always formatted on a single line.

I see.

> Now, I'm not sure the formatter should call `fill-paragraph', for some
> reasons:
>
> - the original document could be using `visual-line-mode' so there's
>   could be nothing to fill without Org knowing about it;
>
> - Calling `fill-paragraph' requires full fontification, so `org-mode'
>   would be initialised at every paragraph to fill;
>
> - `fill-paragraph' depends heavily on user's configuration (custom link
>   types, `org-fontify-emphasized-text', `org-hide-emphasis-markers',
>   `org-pretty-entities'...) whereas the formatter is expected to be more
>   neutral.

Being neutral is good.

What if _I_, for my own project, want to customize the formatter and like to
call fill-paragraph, can I still do this?

I don't know how `fill-paragraph` works and the second point you listed
above worries me.

With my ignorance, I thought just call org-fill-paragraph. Or, do you
mean that "`org-mode' will be initialized" in `org-fill-paragraph`?

BTW, while reading `org-fill-paragraph`, I found a bug.

#+begin_src emacs-lisp
  (add-to-list 'load-path "~/path/to/orgdir/lisp")
#+end_src

activate the region for the src block above, and do `M-x org-fill-paragraph`.
It will inf-loop because `M-q` moves the cursor back to the beginning of
the middle line.

> We could however, un-fill everything. But the output would be very
> different. So, TRTD is not obvious.

For the default behavior, I don't think that a good idea.

>> Since you fixed the big ones, I can see another issue.  This is also indentation
>> issue, but with a macro replacement .  Somehow, macro replacement
>> gets extra indentation.  Like this:
>
>>       a numeric prefix, check that many days.  For example, {{{kbd(C-1
>> -     C-c / d)}}} shows all deadlines due tomorrow.
>> +          C-c / d)}}} shows all deadlines due tomorrow.
>
> This is related to the explanation above. Macros did the opposite of
> links. The parser didn't remove meaningless spaces upon parsing macros.
> So those would be inserted twice. I fixed this. Now macros show the same
> behaviour as links: even multi-lines macros are inserted as a single
> line.

Thank you for fixing this, too.
-- 
            yashi

Re: [RFC] Moving "manual.org" into core

[Yasushi SHOJI]

On Thu, Feb 1, 2018 at 8:43 PM, Yasushi SHOJI <yasushi.shoji@gmail.com> wrote:
> On Mon, Jan 29, 2018 at 11:41 PM, Nicolas Goaziou
> <mail@nicolasgoaziou.fr> wrote:
>> Yasushi SHOJI <yasushi.shoji@gmail.com> writes:
>>
>>> Do you see this on your env?  Or, is it just me?
>>
>> I don't see anything like this.
>
> Hmm... I don't know how to fix this.

I mean, I run `emacs -q`,
eval only the following code in the `*scratch*` buffer,
open `manual.org` and do `M-x org-reformat`.

and I see:

---- >8 ---- >8 ----
@@ -134,9 +133,9 @@
 You can clone Org's repository and install Org like this:

 #+begin_example
-  $ cd ~/src/
-  $ git clone git@code.orgmode.org:bzg/org-mode.git
-  $ make autoloads
+$ cd ~/src/
+$ git clone git@code.orgmode.org:bzg/org-mode.git
+$ make autoloads
 #+end_example

 Note that in this case, ~make autoloads~ is mandatory: it defines
---- >8 ---- >8 ----

I checked `org-src-preserve-indentation` is nil and
org-edit-src-content-indentation is 2.
I even `list-load-path-shadows` and check that git version of org is used.

What am I missing?


(add-to-list 'load-path "~/src/org-mode/lisp")
(defun org-reformat ()
    (interactive)
    (let ((result
           (benchmark-run 1
             (let ((document (org-element-interpret-data
(org-element-parse-buffer))))
               (erase-buffer)
               (insert document)
               (goto-char (point-min))))))
      (if (zerop (nth 1 result))
          (message "Org Re-format took %.2f seconds" (car result))
        (message "Org Re-format took %.2f second (%.2fs in %d GCs)"
                 (car result)
                 (nth 2 result)
                 (nth 1 result)))))
-- 
              yashi

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Yasushi SHOJI <yasushi.shoji@gmail.com> writes:

> I mean, I run `emacs -q`,
> eval only the following code in the `*scratch*` buffer,
> open `manual.org` and do `M-x org-reformat`.
>
> and I see:
>
> ---- >8 ---- >8 ----
> @@ -134,9 +133,9 @@
>  You can clone Org's repository and install Org like this:
>
>  #+begin_example
> -  $ cd ~/src/
> -  $ git clone git@code.orgmode.org:bzg/org-mode.git
> -  $ make autoloads
> +$ cd ~/src/
> +$ git clone git@code.orgmode.org:bzg/org-mode.git
> +$ make autoloads
>  #+end_example
>
>  Note that in this case, ~make autoloads~ is mandatory: it defines
> ---- >8 ---- >8 ----
>
> I checked `org-src-preserve-indentation` is nil and
> org-edit-src-content-indentation is 2.
> I even `list-load-path-shadows` and check that git version of org is used.
>
> What am I missing?
>
>
> (add-to-list 'load-path "~/src/org-mode/lisp")
> (defun org-reformat ()
>     (interactive)
>     (let ((result
>            (benchmark-run 1
>              (let ((document (org-element-interpret-data
> (org-element-parse-buffer))))
>                (erase-buffer)
>                (insert document)
>                (goto-char (point-min))))))
>       (if (zerop (nth 1 result))
>           (message "Org Re-format took %.2f seconds" (car result))
>         (message "Org Re-format took %.2f second (%.2fs in %d GCs)"
>                  (car result)
>                  (nth 2 result)
>                  (nth 1 result)))))

Fixed. Thank you.

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Yasushi SHOJI <yasushi.shoji@gmail.com> writes:

> What if _I_, for my own project, want to customize the formatter and like to
> call fill-paragraph, can I still do this?

No need to tweak the formatter. You can post-process its output to your
liking, e.g., with `org-fill-paragraph' called on the whole buffer.

> I don't know how `fill-paragraph` works and the second point you listed
> above worries me.
>
> With my ignorance, I thought just call org-fill-paragraph. Or, do you
> mean that "`org-mode' will be initialized" in `org-fill-paragraph`?

The formatter produces strings, concatened together. At each produced
string, we would need to create a temporary buffer, activate Org mode,
insert the string and fill the whole buffer, with `org-fill-paragraph'.

> BTW, while reading `org-fill-paragraph`, I found a bug.
>
> #+begin_src emacs-lisp
>   (add-to-list 'load-path "~/path/to/orgdir/lisp")
> #+end_src
>
> activate the region for the src block above, and do `M-x org-fill-paragraph`.
> It will inf-loop because `M-q` moves the cursor back to the beginning of
> the middle line.

Fixed. Thank you.

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Moving "manual.org" into core

[Yasushi SHOJI]

Hi,

On Thu, Feb 1, 2018 at 11:55 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> Yasushi SHOJI <yasushi.shoji@gmail.com> writes:
>
>> What if _I_, for my own project, want to customize the formatter and like to
>> call fill-paragraph, can I still do this?
>
> No need to tweak the formatter. You can post-process its output to your
> liking, e.g., with `org-fill-paragraph' called on the whole buffer.

Thanks.  That's what I did and found this bug.

>> BTW, while reading `org-fill-paragraph`, I found a bug.
>>
>> #+begin_src emacs-lisp
>>   (add-to-list 'load-path "~/path/to/orgdir/lisp")
>> #+end_src
>>
>> activate the region for the src block above, and do `M-x org-fill-paragraph`.
>> It will inf-loop because `M-q` moves the cursor back to the beginning of
>> the middle line.
>
> Fixed. Thank you.

Hmm... I'm using 4b2006db3d04, which includes b4cc12fc32a771 but
it still inf-loops.  `key-binding` returns `fill-paragraph`.  I tried
it `toggle-fill-unfill`,
which I set to `M-q` in general, and `org-fill-paragraph`, but nothing
works here.

I see that `org-babel-do-in-edit-buffer` is a macro.  and my limited skill with
edebug doesn't reveal anything. :-<

Thanks,
-- 
           yashi

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Yasushi SHOJI <yasushi.shoji@gmail.com> writes:

> Hmm... I'm using 4b2006db3d04, which includes b4cc12fc32a771 but
> it still inf-loops.  `key-binding` returns `fill-paragraph`.  I tried
> it `toggle-fill-unfill`,
> which I set to `M-q` in general, and `org-fill-paragraph`, but nothing
> works here.
>
> I see that `org-babel-do-in-edit-buffer` is a macro.  and my limited skill with
> edebug doesn't reveal anything. :-<

You may try to restart Emacs.

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Moving "manual.org" into core

[Yasushi SHOJI]

Hi,

On Sun, Feb 4, 2018 at 6:40 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> Yasushi SHOJI <yasushi.shoji@gmail.com> writes:
>
>> Hmm... I'm using 4b2006db3d04, which includes b4cc12fc32a771 but
>> it still inf-loops.  `key-binding` returns `fill-paragraph`.  I tried
>> it `toggle-fill-unfill`,
>> which I set to `M-q` in general, and `org-fill-paragraph`, but nothing
>> works here.
>>
>> I see that `org-babel-do-in-edit-buffer` is a macro.  and my limited skill with
>> edebug doesn't reveal anything. :-<
>
> You may try to restart Emacs.

I did.  It inf-loops.  Does anyone else see this?  Is it just me?
Oh, well.  I'll try to debug when I have time.

BTW, I'm all for moving manual.org to the core.
I'm sorry I've hijacked the thread.
-- 
         yashi

Re: [RFC] Moving "manual.org" into core

[Thomas S. Dye]

Aloha Bastien,

Bastien Guerry writes:

> Hi Nicolas,
>
>> "manual.org" was updated a month ago, and, so far, nobody 
>> complained
>> about it. So, I think it's a good time to discuss about what 
>> could be
>> done next.
>
> Having the manual in .org is a great achievement, congrats to 
> anyone
> who worked on this titanic task!
>
> I'm all for editing manual.org instead of org.texi in the long 
> run.

This is wonderful news.  Thank you!

All the best,
Tom

--
Thomas S. Dye
http://www.tsdye.com

Re: [RFC] Moving "manual.org" into core

[Christian Moe]

Bastien Guerry writes:

> Hi Nicolas,
>
>> "manual.org" was updated a month ago, and, so far, nobody complained
>> about it. So, I think it's a good time to discuss about what could be
>> done next.
>
> Having the manual in .org is a great achievement, congrats to anyone
> who worked on this titanic task!

+1 !!

Yours,
Christian

Re: [RFC] Moving "manual.org" into core

[Samuel Wales]

i will leave style decisions to the bike shed manufacturer [those who
do the work].  but i will opine anyway.  i'm with the no indentation
people.  [except -- not implemented -- plain lists indented by 2.  :]]

but my reason for posting is that as a default for org, i think (setq
org-src-preserve-indentation t) would surprise users less.  and to
congratulate for dogfooding.  :]

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Nicolas,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> "manual.org" was updated a month ago, and, so far, nobody complained
> about it. So, I think it's a good time to discuss about what could be
> done next.

Is the current contrib/orgmanual.org in sync with doc/org.texi in both
master and maint?

How difficult is it to keep it in sync in both branches?

Would it be okay to hold on for one week before we make the switch,
just to collect more feedback on this?

Thanks,

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Bastien Guerry <bzg@gnu.org> writes:

> Is the current contrib/orgmanual.org in sync with doc/org.texi in both
> master and maint?

Not at all. It is in sync (and a bit above) in master only.

> How difficult is it to keep it in sync in both branches?

"manual.org" relies on improvements made to the Texinfo exporter in
master branch only, and probably to some smaller parts of the export
framework. I wouldn't try to sync the manual in maint branch.

> Would it be okay to hold on for one week before we make the switch,
> just to collect more feedback on this?

For the record, and as a first feedback, I totally disagree with the FUD
(".org flexibility will bring us new problems", seriously) spread about
the Org manual. I spent months on the Org file. If it was a pain to do
so ("Let's test org capabilities against a giant .org file."), I think
I would have noticed. The difficult part was to define editing
conventions and stick to them. This is now done, and unrelated to the
problem at hand.

I find it much easier to handle and edit than its Texinfo counterpart,
even though I have a good command of the Texinfo syntax. This allowed me
to do a large number of improvements to it (structure, index,
typography, overall consistency...), still not integrated in our
official manual.

I would be surprised, to say the least, if anyone browsing in parallel
"org.texi" and "manual.org" told me in good faith the former is clearer.

That being said, we can hold as many number of weeks as you see fit.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: [RFC] Moving "manual.org" into core

[Bastien]

Hi Nicolas,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> For the record, and as a first feedback, I totally disagree with the
> FUD (".org flexibility will bring us new problems", seriously)
> spread about the Org manual.

Maybe I used the wrong word: let's call them "challenges", not
"problems".

But I'm sure there will be some.

And that's fine.  In any case, I did not want to spread FUD and I
don't have strong opinions on this issue.

> I spent months on the Org file. If it was a pain to do
> so ("Let's test org capabilities against a giant .org file."), I think
> I would have noticed.

When I said "Let's test org capabilities against a giant .org file."
I was not just thinking about editing it, but also e.g. exporting.

Testing the .texi exporter (and maybe .html and .pdf) against this big
file will be interesting.

Testing the process of running "make pdf" while emacs will in charge
of producing a PDF file (.org => .texi => .pdf) will be interesting,
and potentially more error-prone than the current .texi=>.pdf process.

But again, that's fine.

> The difficult part was to define editing
> conventions and stick to them. This is now done, and unrelated to the
> problem at hand.

I have not read the conventions yet, and other contributors may not
have read them, so this those conventions are just a proposal for now.
Core contributors need to formally discuss them and explicitely agree.

Again, the question is: what problem are we trying to solve?

Do you agree with the one I suggested?  Do you see others?

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Hello,

Bastien <bzg@gnu.org> writes:

> But I'm sure there will be some.

True, as I'm sure there are some "challenges" with the current Texinfo
manual. Therefore, I do not see the point of insisting on the fact that
a new paradigm brings new problems.

> I don't have strong opinions on this issue.

I read it otherwise.

> When I said "Let's test org capabilities against a giant .org file."
> I was not just thinking about editing it, but also e.g. exporting.

Spending time on the Org version of the manual included exporting it on
a regular basis.

> Testing the .texi exporter (and maybe .html and .pdf) against this big
> file will be interesting.

This is what I am asking for since I announced the Org manual was ready.
Have you tried to export it? Have you looked at the generated Info
manual? Does it look so unsatisfying to you?

> Testing the process of running "make pdf" while emacs will in charge
> of producing a PDF file (.org => .texi => .pdf) will be interesting,
> and potentially more error-prone than the current .texi=>.pdf process.

I didn't invest time in the Makefile, so I don't know.

> I have not read the conventions yet, and other contributors may not
> have read them, so this those conventions are just a proposal for now.
> Core contributors need to formally discuss them and explicitely agree.

If you want to actually do something, you need to make choices. I made
them. Some are arbitrary, other are a result of trial and error, some
are even the result of a thinking process.

You can of course spend energy and time to discuss every single
convention I used, although I suggest to spend them elsewhere. Moreover,
if you have better conventions, feel free to apply them thoroughly and
document them. Let's just move forward, really.

> Again, the question is: what problem are we trying to solve?

Org boasts itself as a format to write, among other things,
documentation. Do you think it is confidence-inspiring if we do not
write our own documentation in our format? See also
<https://en.wikipedia.org/wiki/Eating_your_own_dog_food>. This problem
is now solved.

Also, no matter how you look at it, doing any non-trivial edit in
"org.texi" is painful. I want to ease that pain for current contributors
(at least me), too.

> Do you agree with the one I suggested?

I disagree. My motivation is not to attract more contributors. I don't
think this was Thomas and Jonathan's motivation when they started the
project either, but I may be wrong. 

Having more manual contributors would be a nice side-effect. However,
I'm opposed to consider it as a good measurement for the switch.

Also, I'm not suggesting to get rid of "org.texi". I'm suggesting to
generate it from "manual.org" and to avoid as much as possible editing
it manually thereafter. In practice, this change is so small that I do
not understand what all this fuss is about. This should be simple: move
"manual.org" to doc/, overwrite "org.texi", and, when we feel confident
enough, if it ever happens, remove "org.texi" altogether from the
repository, generating it only before bundling a new Org release or
merging it with Emacs.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: [RFC] Moving "manual.org" into core

[Kaushal Modi]

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

On Mon, Mar 5, 2018 at 9:21 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

>
> > Again, the question is: what problem are we trying to solve?
>
> Org boasts itself as a format to write, among other things,
> documentation. Do you think it is confidence-inspiring if we do not
> write our own documentation in our format? See also
> <https://en.wikipedia.org/wiki/Eating_your_own_dog_food>. This problem
> is now solved.
>
> Also, no matter how you look at it, doing any non-trivial edit in
> "org.texi" is painful. I want to ease that pain for current contributors
> (at least me), too.
>

+1 Editing Org is so much natural than .texi. And by this flow, we are not
obsoleting .texi, just having it generate automatically instead of
manually. It like writing a higher level language like C or Python instead
of tinkering in Assembly.


> Also, I'm not suggesting to get rid of "org.texi". I'm suggesting to
> generate it from "manual.org" and to avoid as much as possible editing
> it manually thereafter. In practice, this change is so small that I do
> not understand what all this fuss is about. This should be simple: move
> "manual.org" to doc/, overwrite "org.texi", and, when we feel confident
> enough, if it ever happens, remove "org.texi" altogether from the
> repository, generating it only before bundling a new Org release or
> merging it with Emacs.
>

Exactly. Emacs will anyways ship with org.texi. So moving the manual source
to Org in the Org repo shouldn't concern the Emacs repo.
-- 

Kaushal Modi

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

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Kaushal,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> Exactly. Emacs will anyways ship with org.texi. So moving the manual
> source to Org in the Org repo shouldn't concern the Emacs repo.

Yes, but it is still a concern for Emacs contributors like Glenn and
others who occasionnally make corrections in Emacs' org.texi.  I'm
fine if we can backport these corrections by hand for the time being.

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Achim Gratz]

Bastien Guerry writes:
>> Exactly. Emacs will anyways ship with org.texi. So moving the manual
>> source to Org in the Org repo shouldn't concern the Emacs repo.
>
> Yes, but it is still a concern for Emacs contributors like Glenn and
> others who occasionnally make corrections in Emacs' org.texi.  I'm
> fine if we can backport these corrections by hand for the time being.

We'll have to deal with them just like we deal with all other
backporting from Emacs.  It's no secret that Emacs like to do things in
a slightly different way and that had to be accepted when Org was moved
into Emacs, but development kept going seperately from it.

I haven't looked at how often changes to Org's manual actually originate
on the Emacs side in one development cycle of Emacs (which is generally
a year or more, but it can't be that much.


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

DIY Stuff:
http://Synth.Stromeko.net/DIY.html

Re: [RFC] Moving "manual.org" into core

[Thomas S. Dye]

Nicolas Goaziou writes:

>> I don't have strong opinions on this issue.
>
> I read it otherwise.

So do I.

Some history.  When I worked on this project several years ago, I 
concluded that Bastien was hostile to it, but there was nothing in 
his communication that was particularly negative.  When I 
suggested on the list recently that Bastien did not like the 
project, I was scolded a bit by others who found mildly supportive 
statements from him in the archives.  Yesterday, in Bastien's 
response to Glenn Morris, was the first time I read that he 
thought the project was a "bad idea".  I wish I'd known that at 
the time!

I'm fine with Bastien holding an opinion different from mine.  My 
point is that he did not speak his mind when I worked on the 
project, so it is valid today to disagree with his statement about 
the strength of his opinions.

>> Do you agree with the one I suggested?
>
> I disagree. My motivation is not to attract more contributors. I 
> don't
> think this was Thomas and Jonathan's motivation when they 
> started the
> project either, but I may be wrong.

I can only speak for myself here.  At the time, I thought the Org 
manual was a stylistic mess and I thought I could use my 
experience as a writer and editor to improve the situation.  I had 
lots of experience writing in LaTeX, but found texinfo clunky and 
obtrusive.  When I discovered Jonathan's texinfo exporter and 
found that it worked nicely, I thought I had an opportunity to 
contribute two ways to Org: 1) I could create a document that 
would challenge the texinfo exporter and lead to its development 
and improvement, and 2) I could edit the manual using the same 
lightweight markup language that I was now using in my academic 
work, having switched from LaTeX to Org mode for its reproducible 
research capabilities.

Of course, I figured the Org mode developers who write the manual 
would also appreciate the switch, and was pleased that Carsten 
pitched in with the memorable comment about Org eating its own dog 
food.

Many thanks to Nicolas for his efforts on this project.

All the best,
Tom

--
Thomas S. Dye
http://www.tsdye.com

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Thomas and all,

please, let's take a deep breath and let me try to explain myself as
clearly as possible.  And remember english is not my first language,
so sometimes I may not express myself in the most adequate manner.

First, let me just restate this clearly: I am in favor of editing the
manual.org version instead of org.texi and I am in favor of doing it
as a 1-year experiment, to see how it goes, and I'm in favor of moving
forward as quickly as reasonable here.

But Org is not an island: Org is part of Emacs and Emacs documentation
is written in Texinfo.  This move is not a small one and I agree with
Glenn that it is worth discussing it to the Emacs mailing list before
we make the switch.  I assume the delay it may take.

"Discussing it" is not a hidden plan for not doing it :) It is just a
way of collecting thoughts from the Emacs community.

Also, please accept my apologies if I hurt your feelings when I said:

   "To speak the truth, I first thought migrating to org as the
   preferred format for editing the manual was just a bad idea."

"Bad" was too harsh and too simplistic.

What I thought was more this: editing manual.org instead of org.texi
can be very nice indeed, but it goes in the opposite direction of one
of the goals I've set for Org's code, which is to be directly edited
from within Emacs repo at some point, as Gnus does today.

If we make the switch -- and I want to make it! -- we won't be able
to merge Org's code into Emacs repo anytime soon.

So, to put things in perspective:

- You started the project in 2013:
  https://github.com/tsdye/orgmanual
  
- Someone resurrected it on the list in 2016:
  http://article.gmane.org/gmane.emacs.orgmode/107141
  
- Nicolas made a giant leap forward and announced it was ready last
  December.

I never expressed myself negatively about this experiment because this
is how I saw it: a very nice experiment!  I was amazed at what you did
in 2013 the same way I'm amazed at what Nicolas did last year, because
this is truly a great achievement.

Maybe this is where some misunderstanding arose: to me, there was no
_project_ to migrate to manual.org -- it was an idea in the air after
you made your experiment and we now have the decision at hand because
the project is, well, DONE.

We could have done it another way: we could have discussed it as a
project, then anticipated that it will prevent Org's code to migrate
to Emacs repository, then discussed the pros and cons before investing
more time.

Anyway, here we are, I think it is safe to assume that editing an .org
version of the manual will help us write better documentation within a
year than to assume that Org's code will migrate into Emacs repository
within a year -- so let's celebrate the achievement by moving forward!

Let's just mention this on emacs-devel first.

And I hope my point of view is a bit more clear.

Thanks!

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Thomas S. Dye]

Aloha Bastien,

Bastien Guerry writes:
> Maybe this is where some misunderstanding arose: to me, there 
> was no
> _project_ to migrate to manual.org -- it was an idea in the air 
> after
> you made your experiment and we now have the decision at hand 
> because
> the project is, well, DONE.
>
> We could have done it another way: we could have discussed it as 
> a
> project, then anticipated that it will prevent Org's code to 
> migrate
> to Emacs repository, then discussed the pros and cons before 
> investing
> more time.

Thanks for pointing out this alternative.

Several of us working on the manual did recently discuss various 
issues on the list. Nicolas had several messages, I responded to 
most of them, and others chimed in on particular parts: Achim 
Gratz, Kyle Meyer, and Kaushal Modi come to mind immediately, but 
there may have been others.

In the past, we could have been assured Carsten would join the 
discussion in one way or another as maintainer, working to keep us 
on track and guide us to the most productive use of our time.

However, you have chosen to fulfill the duties of maintainer in a 
different way, one that does not involve day-to-day interaction 
with the volunteers who are themselves choosing to spend time 
trying to augment and improve Org mode.  I don't argue with this 
decision of yours, but to my mind, this is why we are where we are 
today.

Certainly, if I had understood in 2013 that my efforts would 
eventually work against Org mode by preventing migration of its 
code to Emacs repository (an issue that I don't understand fully 
but accept as valid), then I would have saved that time for other 
pursuits.  But, you did not say this at the time, as far as I 
remember.  My memory is that you were mostly silent.

Similarly, it was clear to me from lurking on the list last year 
that Nicolas was going to revive the project.  I believe it was 
also clear to the others who participated in the conversation on 
list, but I don't want to speak for them.  You either did not read 
that discussion or you did read it and chose not to participate. 
Work on the manual project wasn't a secret.

From my point of view, your involvement has come at the 11th hour, 
well after much effort has been expended on what several of our 
colleagues believe is a contribution to Org mode.  I'm pleased 
that you are willing to give the project a try, but I want to 
insist that you take some responsibility for where we are in this 
discussion.  I cannot accept that the maintainer scolds me and 
others who worked on the project that "we could have done it 
another way."  This is exactly the responsibility I want to insist 
the maintainer accept.

We look to the maintainer for guidance.  Please give it to us in a 
timely manner.

All the best,
Tom

--
Thomas S. Dye
http://www.tsdye.com

Re: [RFC] Moving "manual.org" into core

[Eric S Fraga]

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

My 2¢ on this topic:

1. org is an excellent tool for writing.  I cannot consider writing with
   any other tool these days.
2. texi is an excellent tool for reading/browsing
   documentation.  Likewise, I cannot imagine doing so in another tool
   (in the Emacs sphere).

We should find a way to allow the manual to be written in org with the
manual ready to read in info.

As a user (and sometime contributor in small ways) of emacs over the
past 35 (!) years, I would hate to see it ossify again as it did during
the 90s.  We must move forward and nothing should be cast in stone in
terms of development, whether for code or documentation.

If this means, as suggested by somebody along the way, that the result
is an increase in the building time for Emacs, I think this is a small
price to pay.  I would venture to guess that >99% of Emacs's users are
not building their own version but simply installing the binary for
their systems.  And I'm sure that even for those that build Emacs from
source, when testing new code, could be given the choice to build
documentation or not.  That's what makefiles are for...

In any case, thanks to all involved.  The effort that *all* of you in
this thread put in day in day out is highly welcome and much
appreciated!

Thanks for listening.
-- 
Eric S Fraga via Emacs 27.0.50, Org release_9.1.6-191-g90607d

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 194 bytes --]

Re: [RFC] Moving "manual.org" into core

[Bastien]

Hello Thomas,

as a preamble, let me say that I appreciate the directness of your
message and the civil tone of this conversation.  I understand there
are frustrations lingering around, I have my own too, so let's keep
this thread as constructive as possible, because we all deserve it
as a community.

Let me separate two questions: one is my attitude in dealing with this
migration; another one is my general ability as a maintainer.

The first question naturally leads to the other one, but the last one
exists per se and I'll take this opportunity to say a few words.

So, about this manual migration.

Here is a quick timeline:

  In 2013, I said it was a nice experiment.

  In 2014, I said I would be "more than happy" if you and others could
  progress on this: http://thread.gmane.org/gmane.emacs.orgmode/85574

  In 2016, Charles quoted me saying: "Where Bastien says: "the day we
  can export org.org to org.texi with very little headache and ad hoc
  configuration, yes, we will make the move.""

  In January 2018, I said: "Having the manual in .org is a great
  achievement, congrats to anyone who worked on this titanic task!
  I'm all for editing manual.org instead of org.texi in the long run."

  In March 2018, I said there was no blocker, "please move ahead".

So I don't think I have been scolding you or anyone working on this,
quite on the contrary.  In my message from 2014, I said I won't have
time to dedicate to the project.  And while I was kind of skeptical
about the idea, I have been consistent in sending encouragements and
in not blocking it.

Maybe I should have explained why I was skeptical: but in 2013-2015,
it was just a gut feeling, and expressing it would probably have been
unproductive; then when I had this project to develop Org from within
Emacs, I was not so sure about it either, so I was first cautious not
to raise premature objections.

When Nicolas sollicited the list again in january, I tried to make a
few inputs: not as constructive as I'd wish they were, but still.

Now, my main input is this: LET'S GO!

So...  I completely recognize my general lack of responsiveness is a
problem and it may have been a problem in this case, but I hope you
see that I carefully tried not to block anyone's work on this.  Again:
asking inputs from emacs-devel@ is not a way of delaying or blocking,
it is just something normal to do considering the move.

So now let's close this issue, I'll write to emacs-devel@ and we will
make the switch.


Now, about my general experience and attitude as a maintainer.

I started to take care of Org-mode in 2011, on January 1st.

Seven years ago... time flies :)

I've been involved in code and communication on the list on a daily
basis until septembre 2012, the day my daughter was born.  Stats may
prove my memory is wrong here, but I think I stayed closely committed
until septembre 2014.  Enters life: I had a burn out, a break up and
I was broke.  Like in: completely broke, no job, no place to stay.

I asked Nicolas whether he would considered to be the maintainer on
several occasions -- the first one dating back to november 2011.  We
always had a frank conversation about this.  Nicolas declined, but we
managed to find a balanced way of collaborating and I confidently
moved from being proactive to being more of a release manager.

Despite not being the "official" maintainer, Nicolas is the de facto
one since 2015.  And again, I cannot express how much I owe to Nicolas
and his consistency for the last three years.

But believe me: I wish I could continue to spend one or two hours per
day coding and communicating on the mailing list: because, it's kind
of a home for me.  But I could not.  And I cannot.


So here is my plan:

- We make the switch to using manual.org.

- We release Org 9.2.

- I extract the contrib/ directory from org-mode.git into a separate
  org-contrib.git to live on code.orgmode.org (something I've wanted
  for long).

- I go down my org-mode TODO list to see if there are importants bugs
  and features I wish to work on.

- In the meantime, I find a new maintainer.

- We release Org 10 and the new maintainer takes on.

I think the whole process can take from 2 to 3 months, and I'm ready
to dedicate more time to Org during these months.

WDYT?

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Thomas S. Dye]

Aloha Bastien,

I disagree that the manual project should move into a one year 
probation where success is measured by the number of contributors. 
So, my response to LETS GO! is NOT THERE!

Instead, let's move the project forward with the understanding 
that if it proves to be a bad idea, then the Org mode community 
will have Nicolas' very nice .texi file (with backports by Kyle 
Meyer) to fall back on.

On the issue of your work on Org mode, I'm hoping your 
circumstances will allow you to be more involved, not less.

All the best,
Tom

Bastien writes:

> Hello Thomas,
>
> as a preamble, let me say that I appreciate the directness of 
> your
> message and the civil tone of this conversation.  I understand 
> there
> are frustrations lingering around, I have my own too, so let's 
> keep
> this thread as constructive as possible, because we all deserve 
> it
> as a community.
>
> Let me separate two questions: one is my attitude in dealing 
> with this
> migration; another one is my general ability as a maintainer.
>
> The first question naturally leads to the other one, but the 
> last one
> exists per se and I'll take this opportunity to say a few words.
>
> So, about this manual migration.
>
> Here is a quick timeline:
>
>   In 2013, I said it was a nice experiment.
>
>   In 2014, I said I would be "more than happy" if you and others 
>   could
>   progress on this: 
>   http://thread.gmane.org/gmane.emacs.orgmode/85574
>
>   In 2016, Charles quoted me saying: "Where Bastien says: "the 
>   day we
>   can export org.org to org.texi with very little headache and 
>   ad hoc
>   configuration, yes, we will make the move.""
>
>   In January 2018, I said: "Having the manual in .org is a great
>   achievement, congrats to anyone who worked on this titanic 
>   task!
>   I'm all for editing manual.org instead of org.texi in the long 
>   run."
>
>   In March 2018, I said there was no blocker, "please move 
>   ahead".
>
> So I don't think I have been scolding you or anyone working on 
> this,
> quite on the contrary.  In my message from 2014, I said I won't 
> have
> time to dedicate to the project.  And while I was kind of 
> skeptical
> about the idea, I have been consistent in sending encouragements 
> and
> in not blocking it.
>
> Maybe I should have explained why I was skeptical: but in 
> 2013-2015,
> it was just a gut feeling, and expressing it would probably have 
> been
> unproductive; then when I had this project to develop Org from 
> within
> Emacs, I was not so sure about it either, so I was first 
> cautious not
> to raise premature objections.
>
> When Nicolas sollicited the list again in january, I tried to 
> make a
> few inputs: not as constructive as I'd wish they were, but 
> still.
>
> Now, my main input is this: LET'S GO!
>
> So...  I completely recognize my general lack of responsiveness 
> is a
> problem and it may have been a problem in this case, but I hope 
> you
> see that I carefully tried not to block anyone's work on this. 
> Again:
> asking inputs from emacs-devel@ is not a way of delaying or 
> blocking,
> it is just something normal to do considering the move.
>
> So now let's close this issue, I'll write to emacs-devel@ and we 
> will
> make the switch.
>
>
> Now, about my general experience and attitude as a maintainer.
>
> I started to take care of Org-mode in 2011, on January 1st.
>
> Seven years ago... time flies :)
>
> I've been involved in code and communication on the list on a 
> daily
> basis until septembre 2012, the day my daughter was born.  Stats 
> may
> prove my memory is wrong here, but I think I stayed closely 
> committed
> until septembre 2014.  Enters life: I had a burn out, a break up 
> and
> I was broke.  Like in: completely broke, no job, no place to 
> stay.
>
> I asked Nicolas whether he would considered to be the maintainer 
> on
> several occasions -- the first one dating back to november 2011. 
> We
> always had a frank conversation about this.  Nicolas declined, 
> but we
> managed to find a balanced way of collaborating and I 
> confidently
> moved from being proactive to being more of a release manager.
>
> Despite not being the "official" maintainer, Nicolas is the de 
> facto
> one since 2015.  And again, I cannot express how much I owe to 
> Nicolas
> and his consistency for the last three years.
>
> But believe me: I wish I could continue to spend one or two 
> hours per
> day coding and communicating on the mailing list: because, it's 
> kind
> of a home for me.  But I could not.  And I cannot.
>
>
> So here is my plan:
>
> - We make the switch to using manual.org.
>
> - We release Org 9.2.
>
> - I extract the contrib/ directory from org-mode.git into a 
> separate
>   org-contrib.git to live on code.orgmode.org (something I've 
>   wanted
>   for long).
>
> - I go down my org-mode TODO list to see if there are importants 
> bugs
>   and features I wish to work on.
>
> - In the meantime, I find a new maintainer.
>
> - We release Org 10 and the new maintainer takes on.
>
> I think the whole process can take from 2 to 3 months, and I'm 
> ready
> to dedicate more time to Org during these months.
>
> WDYT?


--
Thomas S. Dye
http://www.tsdye.com

Re: [RFC] Moving "manual.org" into core

[Bastien]

Hi Thomas,

"Thomas S. Dye" <tsd@tsdye.com> writes:

> Instead, let's move the project forward with the understanding that
> if it proves to be a bad idea, then the Org mode community will have
> Nicolas' very nice .texi file (with backports by Kyle Meyer) to fall
> back on.

Maybe we are miscommunicating, because that's exactly what I suggest!

I just want to make sure we have *at least* one year to prove this to
be a good idea.  I will probably not be the maintainer by then, so the
decision will be in the hands of the maintainer and the community.

> On the issue of your work on Org mode, I'm hoping your circumstances
> will allow you to be more involved, not less.

I hope having a new maintainer would help me to be more in control of
what I can focus on.  And it's not as if would leave the list :)

All best,

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Thomas S. Dye]

Aloha Bastien,

Bastien writes:

> Hi Thomas,
>
> "Thomas S. Dye" <tsd@tsdye.com> writes:
>
>> Instead, let's move the project forward with the understanding 
>> that
>> if it proves to be a bad idea, then the Org mode community will 
>> have
>> Nicolas' very nice .texi file (with backports by Kyle Meyer) to 
>> fall
>> back on.
>
> Maybe we are miscommunicating, because that's exactly what I 
> suggest!

Good news.  Thanks!

All the best,
Tom

--
Thomas S. Dye
http://www.tsdye.com

Re: [RFC] Moving "manual.org" into core

[Achim Gratz]

Nicolas Goaziou writes:
>> Testing the process of running "make pdf" while emacs will in charge
>> of producing a PDF file (.org => .texi => .pdf) will be interesting,
>> and potentially more error-prone than the current .texi=>.pdf process.
>
> I didn't invest time in the Makefile, so I don't know.

I've posted a working Makefile back when Thomas was working on the
manual and it is still working with minimal modifications.  If you
decide you want to have this (and exactly which way) I'm sure that can
be further refined in a matter of days (not weeks) to everyones
satisfaction if that should be necessary.


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: [RFC] Moving "manual.org" into core

[Bastien]

Hi Achim,

Achim Gratz <Stromeko@nexgo.de> writes:

> I've posted a working Makefile back when Thomas was working on the
> manual and it is still working with minimal modifications.  If you
> decide you want to have this (and exactly which way) I'm sure that can
> be further refined in a matter of days (not weeks) to everyones
> satisfaction if that should be necessary.

That's great to read, thanks in advance.

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Nicolas,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> I disagree. My motivation is not to attract more contributors. I don't
> think this was Thomas and Jonathan's motivation when they started the
> project either, but I may be wrong.

For the record, I think having more contributors for the manual is a
very sane goal.

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Phillip Lord]

Bastien <bzg@gnu.org> writes:

>> For the record, and as a first feedback, I totally disagree with the
>> FUD (".org flexibility will bring us new problems", seriously)
>> spread about the Org manual.
>
> Testing the .texi exporter (and maybe .html and .pdf) against this big
> file will be interesting.
>
> Testing the process of running "make pdf" while emacs will in charge
> of producing a PDF file (.org => .texi => .pdf) will be interesting,
> and potentially more error-prone than the current .texi=>.pdf process.
>
> But again, that's fine.

I think it will slow the build. Currently, the texi gets compiled in
parallel with the C, while having Emacs build it will shunt it till the
very end (after byte-compilation) where there is nothing to parallelize
(except for the tests).

Of course, if it's only org.org (or whatever) and everything else is
texi, then most of the manual would build earlier. If everything were
org, I think it would add about a minute to a 5 or 6 minute
build. Probably, by the time all of the manuals are in org-mode,
machines will be significantly faster, there will be emacs-free org mode
converter, or we will have hit the heat death of the universe. Perhaps
it's not a problem.

Phil

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

phillip.lord@russet.org.uk (Phillip Lord) writes:

> Probably, by the time all of the manuals are in org-mode,
> machines will be significantly faster, there will be emacs-free org mode
> converter, or we will have hit the heat death of the universe. Perhaps
> it's not a problem.

:)

The output of pandoc is encouraging but not usable yet.

~$ pandoc -f org -t texinfo contrib/manual.org > org2.texi

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Nicolas,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> Is the current contrib/orgmanual.org in sync with doc/org.texi in both
>> master and maint?
>
> Not at all. It is in sync (and a bit above) in master only.

Okay.

>> How difficult is it to keep it in sync in both branches?
>
> "manual.org" relies on improvements made to the Texinfo exporter in
> master branch only, and probably to some smaller parts of the export
> framework. I wouldn't try to sync the manual in maint branch.

So when we make the move, we publish 9.2 by merging master in maint
and edit orgmanual.org from both maint and master.  Correct?

> I find it much easier to handle and edit than its Texinfo counterpart,
> even though I have a good command of the Texinfo syntax. This allowed me
> to do a large number of improvements to it (structure, index,
> typography, overall consistency...), still not integrated in our
> official manual.

For the record: I have no doubt on this and this is also one of the
reasons I'm willing to make the switch.

> I would be surprised, to say the least, if anyone browsing in parallel
> "org.texi" and "manual.org" told me in good faith the former is clearer.

I find orgmanual.org to be clearer.  And I think we can make even more
aesthetics progress on this.

> That being said, we can hold as many number of weeks as you see fit.

It is not about setting a time window: we just need to be careful with
this move and discuss it.  One week seems fine.

I know I have been missing in action very often, and asking for more
time may not sound reassuring... but I'll push this forward, no worry.

Thanks,

-- 
 Bastien

Re: [RFC] Moving "manual.org" into core

[Nicolas Goaziou]

Bastien Guerry <bzg@gnu.org> writes:

> So when we make the move, we publish 9.2 by merging master in maint
> and edit orgmanual.org from both maint and master.  Correct?

Correct, but I don't know what "orgmanual.org" you are talking about.
You recently re-introduced a file named "orgmanual.org" in contrib/
alongside "manual.org". The former is apparently outdated.

> It is not about setting a time window: we just need to be careful with
> this move and discuss it.  One week seems fine.

As pointed out in another message, I do not understand what carefulness
is needed. I suggest to replace "org.texi" with ... "org.texi". The only
difference lies in how we edit it, which concerns a handful of persons
in the world.

Re: [RFC] Moving "manual.org" into core

[Bastien Guerry]

Hi Nicolas,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> You recently re-introduced a file named "orgmanual.org" in contrib/
> alongside "manual.org". The former is apparently outdated.

Yes, my mistake, fixed now.

-- 
 Bastien