Ihor Radchenko <yanta...@gmail.com> writes:
> Dear List, > > I am forwarding an official email from RMS changing subject line to more > descriptive. See below. > > For some context, in order to support specialized syntax for manuals, we > may first need to implement the discussed special blocks export and > inline special blocks: > 1. https://list.orgmode.org/orgmode/87y1yr9gbl....@gmail.com/ > 2. https://list.orgmode.org/orgmode/87edzqv4ha.fsf@localhost/ > > The above links aim to introduce export functionality that we now have > for links to special blocks and new custom markup elements. I am > referring to > 1. Ability to create new custom element types programmatically > 2. Ability to define how to :export the custom element types > > Similar to `org-link-set-parameters'. > > Patches and more concrete ideas are welcome! > > From: Richard Stallman <r...@gnu.org> > Subject: Re: Org mode and Emacs > To: Tim Cross <theophil...@gmail.com> > Cc: emacs-de...@gnu.org > Date: Mon, 26 Sep 2022 08:10:03 -0400 (4 days, 8 hours, 26 minutes ago) > Flags: seen, list > Maildir: /gmail/10 - Tech/software/org > > [[[ To any NSA and FBI agents reading my email: please consider ]]] > [[[ whether defending the US Constitution against all enemies, ]]] > [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > > Speaking as the Chief GNUisance, rssponsible for GNU Project > standards, I would be happy to adopt an upgraded Org format as a new > standard source format for GNU manuals, _provided_ Org format has been > extended with the capability to express all the constructions and > distinctions that Texinfo can express, generate all the output formats > Texinfo can generate, and use TeX to make beautiful printed output. > > Texinfo can generate these output formats: Info files, HTML, ASCII > text, and DVI and PDF files via TeX. > > Texinfo provides numerous subtle distinctions that show up clearly in > each of these output formats. Compare, for example, @var, @dfn and > @emph; compare @code, @samp, @file, @command, @option, @kbd, and @key. > > I am sure people can extend Org software to handle these semantic > distinctions and generate these output formats. Since it has been > done once, it can be done again. But the work is not trivial. > > The work has to start by designing what the extended Org format will look > like. That part is the crucial part; once it has been specified, > people can work independently to implement various parts of handling > that format. > > -- > Dr Richard Stallman (https://stallman.org) > Chief GNUisance of the GNU Project (https://gnu.org) > Founder, Free Software Foundation (https://fsf.org) > Internet Hall-of-Famer (https://internethalloffame.org) > > > > ---------- I realise this will likely come across as another post from "Debbie Downer", but I feel it is important to add a warning here and not get too carried away with the excitement of seeing org mode accepted to the point it becomes the official documentation format for Emacs. There are some potential pitfalls here which need to be considered and which could impact on how we satisfy the remaining 'blocker' to org mode taking on this important role. A few questions we might want to consider.... What impact will adding all the additional formatting/markup primitives have to the user experience? 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. Will adding a lot of additional markup entities have any impact on the development of new and maintenance of existing export back ends? i 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. 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? 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 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? 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 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?