Re: [HELP] Fwd: Org format as a new standard source format for GNU manuals

[Ihor Radchenko <yantar92@gmail.com>]

Tim Cross <theophilusx@gmail.com> writes:

> What impact will adding all the additional formatting/markup primitives
> have to the user experience?

From my perspective, the first and main goal related to this request is
developing the minimally (!) necessary Org format extensions to allow
Texinfo constructs.

I do not think that we need to add all the variety of Texinfo-specific
constructs to the Org specification. Instead, we should add generic
configurable syntax elements to Org. (The Texinfo-specific part will
come as a separate library, similar to ol-*.el)

In particular, I suggest to (1) extend the existing special block elements
with Elisp-configurable :export settings; (2) add special block
equivalent object.

The latter will also serve as an alternative to our current awkward
approach to escaping the inline markup (bold, italics, verbatim, etc).
Especially wrt requirements to the spaces around the markup symbols.

For user experience, the new markup primitives will be unnecessary,
except specific export requirements or edge cases with our current
markup (e.g. spaces at the beginning/end of verbatim/code).

> One of the big benefits org has is simplicity in markup. This is one of
> the driving themes in the 'markdown' movement. Will adding a lot of
> additional syntax and markup tags add to cognitive load and complexity
> and losing some of what makes org mode great to use. This could be one
> of those situations where less is more.

I agree that adding yet another markup tagging will be an extra
cognitive burden. But I envision it to be used only when necessary. If
our current markup is sufficient for the user needs, there will be no
need to go into the more verbose tagging. But if there are special needs
(like exporting manual), there is no way to maintain Org simplicity yet
allowing the complex @dfn/@code/whatnot distinctions.

Also, see https://yhetil.org/emacs-devel/87v8t3wfgd.fsf@localhost

> Will adding a lot of additional markup entities have any impact on the
> development of new and maintenance of existing export back ends? i

I only suggest adding a single new markup object entity, similar to
special block elements. Just like #+BEGIN_FOO can spawn infinite number
of special block types, the new markup object will allow arbitrary new
markup entities loaded as necessary by the corresponding export
backends/libraries.

> With all the additional entities, I suspect the demand for nesting of
> entities will also increase. This has been an area org has struggled
> with in the past. I suspect the big issue is that allowing nesting of
> markup entities and maintaining simple syntax is very difficult.

Agree. However, it is the demand for nested constructs being one of the
motivators why we should have a new markup object syntax that will allow
nesting when absolutely necessary and when the existing simpler Org
markup does not cut it.

> Is there a risk of one aspect of org mode dominating all others and
> potentially transforming it from a very flexible and general solution to
> a technical documentation focus?

I do not think so. Org functionality only depends on the community
interest and contributions. I see no reason why technical documentation
is going to prevail over other Org uses.

> Texifno has a very specific focus. It aims to be an advanced formatting
> system for writing software technical documents. As such, it is very
> suitable for Emacs documentation. Org mode on the other hand is not a
> documentation framework. While it does a fine job in this area, it is
> not its prime focus. Org has many other unrelated roles, such as task
> management, time tracking, simple spreadsheet and data
> management/manipulation, literate programming and live document
> generation, data capture etc etc. Will adopting org mode as the default
> documentation format for Emacs run the risk of the technical
> documentation aspects of org mode taking precedence over other aspects?
> Will funcionality in different areas have to be modified in order to
> better support technical documentation?

> What impact on maintenance and future development directions will
> becoming the official documentation framework have for org mode?
>
> Will this result in document formatting gaining additional focus over
> other areas?  Will it result in interface changes which favor
> documentation processes over other areas like babel, data capture etc?


I do not think so. We are certainly not going to remove features from
Org just because they will improve support for technical documentation.

I mean, I do not really see why this should be needed. But if it is
needed, then we will not go this road and simply abandon the
documentation idea.
https://bzg.fr/en/the-software-maintainers-pledge/

> What is the underlying motivation for this very significant change? 
>
> A big question which I've not seen answered is what is the motivation
> for this very significant change? Are there problems with texinfo which
> are driving this change? If so, are these problems ones we need to be
> very careful not to import into org mode. When you look at it, texinfo
> already exports to many different formats similar to what org mode
> does. It is a system with a very specific and quite narrow focus -
> software technical documentation and yet, its use sems to be
> declining. If it wasn't the flagship for GNU documentation, would it
> even still exist? So the question becomes, why is this system not more
> popular within software documentation circles? If part of the reason is
> to potentialy increase contributors, will there still be as many people
> wanting to use org mode if the underlying syntax is extended and
> modified to support all the main texinfo markup set?

This is a good question. I'd like to hear from RMS or other people
familiar with Texinfo issues.

As a starter, there was a bit of related discussion in emacs-devel:
- RMS mentioned that one big gotcha with Texinfo is that it inherits
  from plain TeX. Supporting LaTeX features would require a major
  re-design. Org supports LaTeX out of the box.
  https://yhetil.org/emacs-devel/E1o0WEF-0004wJ-Iw@fencepost.gnu.org
- Also, from Christopher Dimech:
  "Because texinfo is just plain tex, and as consequence remained
   limited (e.g. no colouring, no bold mathematical expressions' no
   boxes for formal end of proof).
   https://yhetil.org/emacs-devel/trinity-5129f2bc-bc9d-4f40-a099-ba1c913178fe-1655084866514@3c-app-mailcom-bs16

> I think it should also be noted that there are some core Emacs
> developers who are not supportive of this change and who don't like or
> use org mode. Despite what RMS states, this is not a sure thing. Once
> org mode is able to meet all the stated requirements, there debate
> regarding switching to use org mode will begin and I suspect it will be
> pretty full on. We will need to have a very clear picture regarding what
> our (the org mode community) motivation is here and know what we are
> prepared to compromise and what is non-negotiable.
>
> If we do decide to go down this road, one idea which I feel would be
> worth exploring is the extent to which we could have these additional
> markup elements as an optional component. In some ways, similar to org
> export back ends. If we could add these additional makrujp elements as
> an optional add on, perhaps we can maintain the markup simplicity and
> simple syntax for those who don't need specialised markup and for when
> we do, we could require the 'technical documentation' module? 

Agree. Let's not go too far yet and focus on extending special blocks
and the inline special block element I propose. These topics (especially
for markup element with less edge cases) pop up on the Org ML from time
to time and worth looking into regardless whether Org is going to be
used as technical documentation format.

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92