From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id aET/DWBpN2PzJAAAbAwnHQ (envelope-from ) for ; Sat, 01 Oct 2022 00:10:40 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id GFYaDmBpN2PxMwAAauVa8A (envelope-from ) for ; Sat, 01 Oct 2022 00:10:40 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id B0F2F2DAD3 for ; Sat, 1 Oct 2022 00:10:39 +0200 (CEST) Received: from localhost ([::1]:47300 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oeODN-0002dP-SG for larch@yhetil.org; Fri, 30 Sep 2022 18:10:37 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51334) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oeOCB-0002aE-NP for emacs-orgmode@gnu.org; Fri, 30 Sep 2022 18:09:23 -0400 Received: from mail-pg1-x532.google.com ([2607:f8b0:4864:20::532]:41700) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oeOC9-0003RU-44 for emacs-orgmode@gnu.org; Fri, 30 Sep 2022 18:09:23 -0400 Received: by mail-pg1-x532.google.com with SMTP id q9so5232338pgq.8 for ; Fri, 30 Sep 2022 15:09:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:message-id:in-reply-to:date:subject:to:from:user-agent :references:from:to:cc:subject:date; bh=BgHi3St8X02G4jxp9ASsgwuH+fxffDM1RbswYAHiD1A=; b=gPfBXlAG0ABAv+jMjXdgaq8yM4gtzNy5EeH53iAlH2DJ73QBiOM76p4lmtvddGF1v2 pJ0tR+XGE52uG69N6wisCsp962dYUPTkJytCBOCqGPHjodV/rTnZJNPyaH4k+v9+P9bE yWZYICL0tTF+9z9YElPtELpi/q66JyuKE9hx9r+tsYRjskGLBgYRpo7eDNBLrHr4/I4D RtJ45goZKURQcbjaKxAxv6zfU6kLGcZvH4B/EqswMgelC6RzpPAIA05rbJmKANLn1W4B 1HC6zAGEru7rLXnCSzLOx3JLmRCP1xj608iTbgfnGD4/Hoxe2VNGkws1Ixmdoi89c7NI 2sVg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=mime-version:message-id:in-reply-to:date:subject:to:from:user-agent :references:x-gm-message-state:from:to:cc:subject:date; bh=BgHi3St8X02G4jxp9ASsgwuH+fxffDM1RbswYAHiD1A=; b=B5wy1It2Q1Iin3FV4PEhoyl57nJkcT80Qh0Y7EcGQdLxy9cocwBrrJCBUDmU3pfTob ydsMbxVKwhiSv5YLObeQlFyb9+dE8pfcpAYH8RHbKdg1OpcjbY3CiB3ClFKXbq91RwDr IMqgvLzTk3qBBJ1lYQ8f+IM+HQXrRUogLIsSY8HtRvmah2LL85B9x+LEALttgFIAvhqh v0djiXFch2YIK009MdlpDOLcXJaaBmcfghBbSzk9ItS+QGh/bvu63yMpEwRy/oeyR03p 9yEsbvgzNkcRtRAGeu6U3I2q4OIY5vWCpCVLwteOqXcOwmW7XNfrmpJF1KbPCHGKN14w 2woQ== X-Gm-Message-State: ACrzQf30WRGUsofVoS3Z4F4l8Igf81JL5Dn4mOFrUoZkW4x7Hw+DUk1o WchshimLrq5hwBrDXYsQ3OFG0hsUk8c= X-Google-Smtp-Source: AMsMyM5HRdIRGzQp2yGp0IniaUnmEOP+5yiEWTHQiSDLlyjM81BT9QfTven5yns/uXSXILeUQbC7eA== X-Received: by 2002:a62:1bc8:0:b0:546:c62e:e84 with SMTP id b191-20020a621bc8000000b00546c62e0e84mr11104830pfb.45.1664575758851; Fri, 30 Sep 2022 15:09:18 -0700 (PDT) Received: from dingbat (124-169-22-230.dyn.iinet.net.au. [124.169.22.230]) by smtp.gmail.com with ESMTPSA id i6-20020a628706000000b005375a574846sm2298890pfe.125.2022.09.30.15.09.17 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 30 Sep 2022 15:09:18 -0700 (PDT) References: <87bkqx4jyg.fsf@localhost> User-agent: mu4e 1.9.0; emacs 29.0.50 From: Tim Cross To: emacs-orgmode@gnu.org Subject: Re: [HELP] Fwd: Org format as a new standard source format for GNU manuals Date: Sat, 01 Oct 2022 06:36:10 +1000 In-reply-to: <87bkqx4jyg.fsf@localhost> Message-ID: <86pmfcv7jq.fsf@gmail.com> MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=2607:f8b0:4864:20::532; envelope-from=theophilusx@gmail.com; helo=mail-pg1-x532.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1664575839; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=BgHi3St8X02G4jxp9ASsgwuH+fxffDM1RbswYAHiD1A=; b=HIbCwpDoxVOqu3vOj498hl75TFdlsRyoapE/GiZdLgaJlAezbzFXrusMj5GfbvBm6Bn0VC ooVSxClZMF91d1c/Dc4lHji3e2eJvQqECBhdrY3m2AzcB2Sgb8xJxYUmhHd7xqKWqA2k1y +2EzyfsxKn690gXAu8aiquiAVfKFrsLRAWIWWPPiA5hvp9Cw1U4a4GX+/79PCWx1zjZgXZ RNzCN/MM6EB8UYGGkyl/0+vbl/7Bq/TjfeRYP3D7KgvyqJ3THYLTomNmEXWuJJ8qTK8gFq BbVeoR4V0X/5G6k/Y0WVgsrwhTYYI6Mdxy7WevNh3oM3LZf+RoHbDkwVGO0nHw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1664575839; a=rsa-sha256; cv=none; b=BnRdflz2UwnR7DG9I630m6tn81yXFov/px4D0R8TGc9s2cKC2JsVciuxpzdrelUw8oj5nj XQKajAQ3OLM57CHeOPvqqqsBxCxE/hvA6KI0qE5xlC9rTHGYgjxTF7OBQMOIIg/CUNe71Y 3SYeEBPIcezD1AzIbFA2AUrYHLMfkpmphv7WcDcIa8nMQokSXD5guTXVkLPmSARY6y262e 0Si7fnIPDsgMJqMXr68+CXG3cM+TsFEpgoiyOuhyIpYOMmUZ6DuoIREGXNVNCW0UJ+S+8R 6BA18bI5zmcrgM8g+QRCqZTVmLUAzBglvYqwDsTdDER9zrZa3KrxWMBlbw8YRg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=gPfBXlAG; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -7.34 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=gPfBXlAG; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: B0F2F2DAD3 X-Spam-Score: -7.34 X-Migadu-Scanner: scn0.migadu.com X-TUID: wUwWUu0H4jlK Ihor Radchenko 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.fsf@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 > Subject: Re: Org mode and Emacs > To: Tim Cross > Cc: emacs-devel@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?