Re: Org mode and Emacs

[Po Lu]

chad <yandros@gmail.com> writes:

> I think a reasonable examination of the emacs-devel archives as well
> as the common practices of most of the people publishing emacs lisp
> packages today would lead to a very different conclusion. There are
> several threads about maintenance concerns around makeinfo/texinfo,
> and many discussions about replacing texinfo with, for example,
> HTML.

Published Emacs Lisp packages in the wild typically come with no
documentation at all, aside from doc strings and a single README file.

Org mode happens to be popular for the latter, but I don't know why.
The learning curve is high and the results seem to be unjustified.  An
easier format such as HTML or Markdown can be used instead.

> There are periodic threads where people claim that they won't try to
> add their project to GNU because the burden of learning and using
> texinfo is too high, although those have died down in volume since it
> became more practical to translate other formats to texinfo.

Why would Org mode be any different?  Unlike HTML, it is completely
specific to Emacs, which actually makes it worse than Texinfo, because
Texinfo is at least widely used throughout the entire GNU project.

And anyway, I make the following offer: if someone doesn't want to
contribute documentation (or code) because he doesn't know Texinfo, he
can write the documentation in plain text, and I will translate it to
Texinfo for him.  IIRC the GDB developers made a similar offer, and for
the many years that it existed nobody ever took advantage of it, which
shows that Texinfo is not a serious barrier to contributors.

Further more, using Org mode for documentation will make Emacs lose many
people who are actually writing documentation, right now.  At least I
have no interest in ever learning Org mode, and there seem to be no
volunteers who will translate Texinfo (or plain text) to Org mode for me
if we begin to use it for documentation in the future.