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

[Bastien Guerry <bzg@gnu.org>]

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