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

[Protesilaos Stavrou <info@protesilaos.com>]

Hello again!

This is in response to my previous reply, copied below.

After reading through the discussion[1] on using Org for Emacs manuals,
I have managed to make some changes to the modus-themes.org file which
generates modus-themes.texi.

You can inspect the source code with:

    git clone https://gitlab.com/protesilaos/modus-themes.git

Documentation is stored in the repo's "doc" directory.

The changes pertain to the appropriate use of Texinfo markup such as
'kbd', 'code', and 'file'.  Furthermore, the modus-themes.texi file is
now distributed as part of the source code, whereas before I was only
sharing the modus-themes.org and its derived modus-themes.info.

Those improvements will be made available for the forthcoming version
1.2.0 of the Modus themes (expected within the next few days).  Core
Emacs currently ships with the themes' 0.13.0 version, which will soon
be three releases behind.

As noted before, I want to only maintain one copy of my project, so the
bug we are currently discussing (#45143) as well as #45141 should be
contingent on #45068.  A few weeks ago, I offered a summary of what the
state of affairs on #45068 is.[2] The only change since then is the
newer version of my project.

Thank you for your time!

All the best,
Protesilaos

[1]: <https://lists.gnu.org/archive/html/emacs-devel/2018-03/msg00166.html>.
[2]: <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=45068#86>.



On 2021-02-22, 18:38 +0200, Protesilaos Stavrou <info@protesilaos.com> wrote:

> 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