[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Org mode and Emacs
From: |
Eli Zaretskii |
Subject: |
Re: Org mode and Emacs |
Date: |
Mon, 26 Sep 2022 19:16:21 +0300 |
> From: "T.V Raman" <raman@google.com>
> Cc: Po Lu <luangruo@yahoo.com>, Ihor Radchenko <yantar92@gmail.com>, Payas
> Relekar <relekarpayas@gmail.com>, emacs-devel@gnu.org
> Date: Mon, 26 Sep 2022 06:58:31 -0700
>
> I think there are two (perhaps more) aspects to writing good
> documentation and accepting / making contributions:
>
> 1. The basics -- write a paragraph or two describing some feature.
> Orthogonal to that and here is where each format bites in different
> ways:
>
> 2. Integrating that contribution into the main corpus of the work --- at
> the write place, with the right surrounding context, generating the
> right table-of-contents and menus (a running nightmare in Texinfo if
> you dont set things up right at the beginning) and so on.
>
> I think (2) might likely contribute negatively to (1) happening more
> often.
I think the division you suggest is somewhat artificial. Unlike man
pages, Info manuals are not a collection of loosely-couples articles;
instead, the sections in a good Info manual are always connected and
context-aware. Thus, writing the documentation for the manual should
_always_ start by studying the "neighborhood" in which that new stuff
will live. IOW, putting the new text in context is not an
after-thought, it should be considered prior to writing.
I don't know what you allude to as "running nightmare in Texinfo".
Adding a new node to a manual is since long ago a very simple process:
just add it and make sure the @menu of the parent node (if there is
one) is updated to have the new node in its correct place. That's it.
> So rather than arguing about formats (and it's been pointed out already
> that there are tools for automatic conversion) we should perhaps:
>
> A. Create a simple content repository where contributors can check-in
> their small to medium contributions in the format of their choice
> (limited to a few open formats) along with the meta-data
> B. A small group of more experienced volunteers take on the task of
> incorporating those contributions into the main work.
Most contributors to Emacs already write pretty good Texinfo; adding
finishing touches to that and fixing a few style or markup mistakes is
already being done in the background by those who spot those blunders.
So I think we already have the above in place.
- Re: Org mode and Emacs, (continued)
- Re: Org mode and Emacs, Richard Stallman, 2022/09/26
- Re: Org mode and Emacs, Ihor Radchenko, 2022/09/25
- Re: Org mode and Emacs, Po Lu, 2022/09/26
- Re: Org mode and Emacs, Emanuel Berg, 2022/09/26
- Re: Org mode and Emacs, Bastien Guerry, 2022/09/26
- Re: Org mode and Emacs, T.V Raman, 2022/09/26
- Re: Org mode and Emacs,
Eli Zaretskii <=
- Re: Org mode and Emacs, Ihor Radchenko, 2022/09/26
- Re: Org mode and Emacs, Bastien, 2022/09/26
- Re: Org mode and Emacs, Ihor Radchenko, 2022/09/26