bug#45143: Incorrect markup in some doc/misc manuals

[Protesilaos Stavrou]

On 2021-02-22, 01:22 -0500, Richard Stallman <rms@gnu.org> wrote:

>   > With regard to the modus-themes, I am indeed building the manual from an
>   > Org file.  I have not found any way to fix those issues in advance (at
>   > the Org level), so I am willing to do so manually when I am about to
>   > send a patch to the Emacs maintainers.
>
> I appreciate your willingness to do this work, but this situation is a
> problem, because there is no such thing as the source file for that
> manual.  The Texinfo file is not the real source file, since you don't
> really do editing in it.  The Org file is not the real source file
> since you can't compile it automatically.
>
> We need to have a real source file!
>
> Can you treat the Texinfo file as the source,
> and do your editing in that.

I think we need to distinguish between two cases:

1. The version of the Modus themes' manual that ships with Emacs.  This
   is exclusively in .texi format.

2. The version that is distributed through my git repository.  This is
   written in .org and also distributed as a derivative .info file.  A
   website version is on offer as well (no javascript required).[1]

With regard to case 1, I agree that we should treat Texinfo as the
source: it is all we provide.  This is why I am willing to edit it
manually in those cases where the Org export falls short, as we have
already established.  What prevents me from doing so right now is the
pending upgrade of the themes in Emacs from their 0.13.0 version to what
I currently have, which will soon be 1.2.0 (three releases ahead).

If you think that I should patch the manual of case 1 right now, without
waiting for the sync between core Emacs and my repo, then I will do it.
If, however, you believe we can afford to wait a while longer, I would
prefer to edit the version of the manual that corresponds to the themes'
forthcoming version 1.2.0.  It makes it easier to maintain my project
when I do not have to deal with branching paths.

As for case 2, I would like to continue to treat the .org as the
original source file.  For me Org is easier to work with than Texinfo.
It is also better for end users who, I presume, are more likely not to
be familiar with the .texi markup.  Given my expressed willingness to
make the requisite changes in the .texi file of case 1, I see no problem
in opting for such a preference.

If you disagree, please inform me about it (or point me to the right
documentation) and I will do my best to adopt a better practice.

At any rate, I must stress that there is no intent whatsoever to
obfuscate any piece of information or otherwise hide anything from the
user: everything is already available and is licensed under libre
licenses.  Whatever issue we have been discussing here is caused by
infrastructure-level constraints that should be overcome with some
effort.

> Alternatively, could you enhance Org format so you can
> generate the Texinfo file automatically from it, with all
> the proper Texinfo markup?

That would be nice.  I am afraid I cannot do that though: I do not have
intimate knowledge of the Org export facility and the Texinfo syntax.

[1]: <https://protesilaos.com/modus-themes/>.

-- 
Protesilaos Stavrou
protesilaos.com