Eventually we want to be able to generate "transient.texi" from
"transient.org", without having to either give up on idiomatic texinfo
or making it much more painful to maintain the org file.
We are much closer to that now, but there are still a few areas where
additional work is needed. This was mostly accomplished by using Org
macros.
The most significant outstanding issue is that the generated
references don't yet look like an experienced texinfo author like Eli
would like them to look. Additionally it is not yet possible to use a
macro that produces @dots{} in the places Eli added them, and in Org
code blocks it is not possible to use macros, so we cannot have
@var{...} appear in "@lisp ... @end lisp". The last issue probably
cannot be changed on Org's side, but since there are only two such
code blocks, this might be a situation where the compromise has to
come from the texinfo side. There are also three other very minor
and inconsequential differences.
For now I have regenerated the texinfo file from the org file and then
discarded the differences mentioned in the previous paragraph.
The process of merging (1) Eli's changes to the texinfo file
(including, but certainly not limited to markup), (2) changes to the
org source (updated content, formatting changes backported earlier,
fixes for formatting changes Eli did not fix, etc.) and (3) changes to
the code that converts the org source to texinfo, was very laborious
and painful. In essence, this amounted to a (at least) three-way
merge across three different languages and three repositories.
I tried very hard to not waste any of the effort Eli had put into
fixing up the generated texinfo file. I.e., I went back and forth
making improvements to the org source, implementing org macros,
regenerating the texinfo and comparing the remaining difference, and
creating commits on both sides. This resulted in a dozen commits on
both sides and took me well over a day. I could have put in even more
effort to absolutely ensure nothing at all is lost in the process, but
I think that would have amounted to a colossal waste of my time.
Going forward, if you find unidiomatic texinfo, then please don't fix
each instance. Instead write me an email, explaining what the problem
is. You are welcome to make limited fixes to the content or fix
one-of markup issue in the texinfo file; those are relatively simple
to backport in comparison.
* doc/misc/transient.texi (all nodes): Replace ".." with Texinfo
style ``..'' quoting or by @dfn{..} or by other appropriate
markup, like @samp{..}. Add indexing. Fix punctuation. Fix
markup of keyboard commands.
