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

[Bastien Guerry]

Hi Glenn,

Glenn Morris <address@hidden> 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