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

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

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