From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms1.migadu.com with LMTPS id cI4vIgACFWarsgAA62LTzQ:P1 (envelope-from ) for ; Tue, 09 Apr 2024 10:53:20 +0200 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id cI4vIgACFWarsgAA62LTzQ (envelope-from ) for ; Tue, 09 Apr 2024 10:53:20 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=J7B6j8hW; 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"; dmarc=pass (policy=none) header.from=posteo.net ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1712652800; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=Q5C4JI97Crf7QAfuM3eMUetkTZuSDQPKZkrcxMWRR7w=; b=CPAsyxgfyiHJDGDFkuAflZKhvYN+oGBGzLtb4ktC0a2nIAX6R0iPNYuqmY9v/8TfPJBy10 HFcVFqWVek/O755WbjOQ7RdkWqKfiqS6CCaVjxU2DknfR8lswq0WMn14T9egQRl27zeO3t 4n5FpG1ca0IaE7SoCkon6LbmQPydWa9P0vf2h6VqVDMr/MrKadIyBzM401bhB2Pksr8wCC P9qd9dizFhn4g2N20wIcWYaAqXEGQWlkUjowjbd5CYWahhPMRG7mOohkKQVwDHFhZEcd7/ Aphf5DQMVu41RR3Vhdf4JFVrDLgDmJS7aAtm7jGrrz7BcQKo+eU1MHXYJh9DqA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1712652800; a=rsa-sha256; cv=none; b=FPZo6OkkJdDT1OZUvCQvYbBG1Ky9HlTnjdUcfwj/qIf45yel379uqQLQQTlqlviz0WxguT v7rl8gqDTvjMngycR6wkIzJOkSa2LslRptoSToEp/BEaxYDn+xwtN5XGXHCiDa/v5Hobk7 foGsDIH3RKWu0ePVJSPwmjnGfhUcCIVjraOFbVDopcoxPBR2laIbELttlQlpLvu/4iUC5L xuO7b6PXVTCT75XesnRiwze7AUVxX82hSqBLnqHS8p2iggtoHWTDdD6aHVlWfEEjEMHtPu yTelUcTVqJtVNy0kR3viQXJnbNHMwVSkMnQoHxDnPvBEMZC2tjMlYPPVJNVtHA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=J7B6j8hW; 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"; dmarc=pass (policy=none) header.from=posteo.net 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 395D822424 for ; Tue, 9 Apr 2024 10:53:20 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ru7DP-0001ft-SK; Tue, 09 Apr 2024 04:52:27 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ru7DN-0001fc-J3 for emacs-orgmode@gnu.org; Tue, 09 Apr 2024 04:52:25 -0400 Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ru7DG-0007Lc-Gg for emacs-orgmode@gnu.org; Tue, 09 Apr 2024 04:52:22 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id DFA8D240028 for ; Tue, 9 Apr 2024 10:52:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1712652735; bh=CGWhkyEcnV5ta93SVAYQioh10H2Pek8wz/z5xmCyHv0=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type: Content-Transfer-Encoding:From; b=J7B6j8hWBuHWR9Na+DvofXbsJ+gucNM4wYcY/DDD875uoUuhQPe6uiNAoYRXS1fbJ yByInHEmNruaPU681g1L3tsQkEb6eJrZab0oLp1RJN45vIXhRkMoh08kKUN4RGgY2X 961Fve3D7uKvMKjjWx26QEbDuB70DGcdaZLXitccjsQft82Q/5ZiXBRUoLA4lPyK5+ DmtVbn9Izx6Tf5YqjqoMgHIQq+fnpq4/7tQ035EudY8tQuYpd6tVHNAFItS/9tT/MB nxp90W4Lrj7ri0QU1xMbNvMVixZYp7CXP8tbGsZNjqGRWYfdzQdxHw3gL8B7P1vYxl rcUoRsx8GEaHQ== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4VDKTV61WXz6twP; Tue, 9 Apr 2024 10:52:14 +0200 (CEST) From: Ihor Radchenko To: Juan Manuel =?utf-8?Q?Mac=C3=ADas?= Cc: orgmode Subject: Re: Experimental public branch for inline special blocks In-Reply-To: <87wmql6690.fsf@posteo.net> References: <87wmql6690.fsf@posteo.net> Date: Tue, 09 Apr 2024 08:52:38 +0000 Message-ID: <875xwqj4tl.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=185.67.36.65; envelope-from=yantar92@posteo.net; helo=mout01.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 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, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, 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-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Spam-Score: -9.58 X-Spam-Score: -9.58 X-Migadu-Queue-Id: 395D822424 X-Migadu-Scanner: mx12.migadu.com X-TUID: dQhsCKFVbuYK Juan Manuel Mac=C3=ADas writes: > Finally, I have made public on GitLab my experimental branch for the new > (possible) inline-special-block element: > > I have finally finished my review of the previous related discussions. See my comments and proposals below. [ Aside: It looks like your public branch is not up-to-date as the time of writing this email - I do not see commits changing the syntax to @foo{...} and @@{...} yet, as discussed in https://list.orgmode.org/orgmode/87sf121e9t.fsf@localhost/) I have edited your original message in the quotes to reflect upon the newly agreed syntax. ] --------------------- > The basic syntax: > @foo{lorem ipsum dolor} > There is also an anonymous variant: > @@{lorem ipsum dolor} > Optional attributes in square brackets are supported > @foo[:key1 value1 :key2 value2 ...]{lorem ipsum dolor} Let me list the main goals of the new inline markup within the scope of overall Org markup and discuss whether the proposed syntax can work to achieve them. 1. Introduce user-configurable ad-hoc syntax where exporting and fontification are fully configurable on Elisp level, per-document level, and maybe even per-markup level. Something combining flexibility of links and special blocks, but without their limitations: - In contrast to links, we should be able to nest inline markup without restrictions: @foo{@bar{text}} ([[foo:a][[[bar:b]]]] is not possible) ***This goal is covered by the branch*** - We should be able to have arbitrary text inside inline markup. No sequence of symbols should be prohibited: @foo{ can contain leading and trailing spaces } @foo{can contain "}" inside, especially inside =3Dverbatim }=3D text} = <-- **ambiguous** @foo{can even have "}" at the end boundary}} <-- **ambiguous** This is unlike links that prohibit closing "]". ***For the above examples, the proposed syntax is ambiguous*** - We should be able to define special markup for code, where the contents is not parsed. Something like @code{ unlike =3Dcode=3D, we can have leading and trailing spaces } @code{ @foo{is not interpreted inside}} ***This goal is not addressed by the experimental branch for now*** 2. Allow attaching auxiliary attributes to the on object level, as an equivalent of affiliated keywords on element level - For example, we should allow assigning height per-link without the awkward kludge we have with special handling of =20=20=20=20=20 #+attr_html: :height 300 [[file:image.png]] has a height of 300, but what if we want a different height in [[file:another-image.png]]? We can thus do =20=20=20=20=20 #+attr_html: :height 300 [[file:image.png]] has a height of 300, but what if we want a different height in @@[:html-height 300]{[[file:another-image.png]]}? Note how @@{...} markup assigns attributes to objects inside - the attributes should be somehow inherited. Another example is the proposed @@[:lang "en"]{...} attribute - we may want to assign it even beyond current paragraph; for example for the whole subtree (aka mark subtree language to be "English"). ***This is not covered by the branch*** - We should also be able to assign attributes that contain Org markup themselves: @@[:alt This image shows a _cat_ climbing a /wall/]{} ***This is not covered by the branch*** 3. The new syntax should allow us to do anything Texinfo markup can do (as per RMS request https://list.orgmode.org/orgmode/87bkqx4jyg.fsf@loca= lhost/) - Multi-argument markup in Texinfo like for abbreviations @abbr{abbreviation[,meaning]} Example: @abbr{Comput. J., Computer Journal} (https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#g_t_= 0040abbr) We can equivalently (if markup inside attributes is supported) do @abbr[:meaning Computer Journal]{Comput. J.} or even @abbr[Computer Journal]{Comput. J.} In theory, we may need even more than 2 arguments. ***This is partially covered*** 4. The new syntax should allow working around ambiguities of the *DWIM* markup without using the awkward zero-width space kludge - Intra-word markup foo@bold{bar}baz =20=20=20=20=20=20 ***This is covered already*** - Simultaneous markup =20=20=20 @bold{foo}@italic{bar} @@{*foo*}@@{/bar/} ***This is covered already*** - Solving the undesired first-fit-wins parser behaviour: /italics stops [[early/?here]], but not later/ need to *escape stars* like that one* =E4=BD=A0=E5=A5=BD=E3=80=82*=E6=88=91*=E4=B8=8D=E4=BC=9A=E4=BA=9B=E8= =BF=99=E4=B8=AA @italic{italics stops [[early/?here]], but not later} need to @bold{escape stars* like that one} =E4=BD=A0=E5=A5=BD=E3=80=82@bold{=E6=88=91}=E4=B8=8D=E4=BC=9A=E4=BA=9B= =E8=BF=99=E4=B8=AA ***This is covered already*** -------- Proposed modifications to the inline markup syntax ------- 1. @foo{basic form remains the same} 2. @foo{{but we allow arbitrary number of "{{..." to open the markup. Then, } inside does not end the @foo markup; we only end it at the matching number of }s; "{" and "}" inside do not have to be balanced.}} 3. @foo[alternative brackets] In an edge case, when the contents itself is {...}, allow alternative brackets @foo[{contents surrounded by curly braces}] 4. We also have a special form of syntax where the contents is not at all parsed @code{this is *verbatim* code; it may contain =3D or even have whitespace at the boundaries } This is equivalent to #+begin_example example blocks vs. #+begin_ special blocks. @code{{can also contain "}" inside, using multiple bracket alternative}} @code[{or be like this}] 5. Change the @foo[:key1 value1 :key2 value2 ...]{lorem ipsum dolor} syntax: @foo[can have][multiple][arguments]{the last argument is considered obje= ct contents} Every argument is parsed @title[This is an image title, with *markup*]{} @@[:lang cn :alt Hello]{=E4=BD=A0=E5=A5=BD} @@[:lang cn][:alt Hello]{=E4=BD=A0=E5=A5=BD} The exporters are responsible to interpret the arguments as needed, if keyword arguments are passed. We should also not layer additional rules for escaping delimiters apart from the existing Org mode markup: @@[:lang cn :alt @@{can have :keyword-like inside, insulated inside =3D@= @{...}=3D}]{...} @@[:lang cn][:attr_latex @@{:color blue}]{...} This is akin affiliated keywords that are never split into keyword/value pairs by org-element, leaving this job downstream to specific commands and libraries. (The difference is that affiliated keywords are mostly not parsed, but parsing is necessary here to address multi-argument markup syntax like @abbrev) ------- Attribute inheritance ------- As I described in @@[:html-height 300]{[[file:another-image.png]]} example, we should have some form of attribute inheritance, so that we are able to assign attributes to arbitrary Org markup, not just to inline markup objects. Furthermore, attributes like @@[:lang cn][=E5=A5=BD=E5=B7=A5=E4=BD=9C] may = need to be assigned to the text spanning across multiple paragraphs or even headings. I suggest following what we already do for source blocks: 1. org-babel-default-header-args sets global attributes applicable to everything globally 2. org-babel-default-header-args: sets global attributes per-language 3. #+PROPERTY: header-args sets global attributes per-file 4. #+PROPERTY: header-args: sets language-specific attributes 5. :HEADER-ARGS: or :HEADER-ARGS:: set attributes per-subtree 6. #+HEADERS: sets src block attributes 7. Attribute values are merged together: org-babel-default-header-args =3D :cache yes :export none #+HEADERS: :cache no :var x=3D1 combines into :export none :cache no :var x=3D1 I propose the following naming for inline markup: org-default-inline-attributes org-default-inline-attributes: #+PROPERTY: inline_attr #+PROPERTY: inline_attr: #+INLINE_ATTR: affiliated #+INLINE_ATTR:: In addition, attributes from @@[:alt Text]{} are applied to all the markup inside, including normal non-inline markup objects. Further, we may allow a special attribute :inherit that will allow more fine-grained control on where to inherit the attributes from: #+inline_attr:var: :inherit example @example[:color gray]{(defvar @var{variable-name} nil)} As an option, I am not yet sure about, we may also allow per-keyword control like @bold[:export latex rest*]{and some more @bold[:export+ html]{inside}} so that :export and :export+ are combined. (Despite me using :export example here, what I am proposing is not limited to :export keyword that have been discussed in-depth in https://list.orgmode.org/orgmode/87bk7k7tuf.fsf@posteo.net/) > Optional attributes in square brackets are supported. There are a series > of 'universal' attributes, common to each backend. At the moment: > `:lang', `:color' and `:smallcaps'. Example: ------- On :lang attribute ------- This attribute is special - language of a text is actually _not_ a markup. It is more global, and it does not quite fit within the framework of per-markup type inheritance. In contrast to something like @foo[:export latex rest*]{@bar{should be exported everywhere}} :lang attribute applies to all types of markup inside @foo{:lang cn}{@bar{=E5=85=AC=E5=85=B1=E6=B1=BD=E8=BD=A6}} Moreover, we may want to apply it per-paragraph or per-subtree. So, we may want to 1. Combine all the nested inline :lang attributes regardless of the inline markup types nesting 2. Introduce a new affiliated keyword #+LANGUAGE 3. Introduce a new subtree property :LANGUAGE: 4. Re-use #+LANGUAGE: per-document keyword 5. Use the previous 4 rules to :lang attributes as a special case. Then, export backends should implement :lang attribute support and ox.el should provide the means to query it, performing all the necessary inheritance calculations. ------- Configurable inline markup export ------- Given that the discussed inline markup is supposed to improve on the link export flexibility, and also add more ad-hoc export setting options, I have the following necessary features in mind: 1. We should have an equivalent of :export link parameter This will be Elisp level interface for inline markup, allowing to write Org mode syntax extensions (like the one necessary for Texinfo feature-parity) ***This is not covered by the branch*** 2. We should expose per-document ad-hoc markup customization that does not require Elisp. Something similar to link abbreviations or macros. However, I do not want the inline markup to turn into another variant of macros. So, I do like the proposal to define only attributes: > =E2=94=8C=E2=94=80=E2=94=80=E2=94=80=E2=94=80 > =E2=94=82 #+options: inline-special-block-aliases:(("latin" :lang "la" :l= atex-command "textit" :html-tag "em")) > =E2=94=82=20 > =E2=94=82 Caesar's famous quote: @latin{Alea iacta est} > =E2=94=82=20 > =E2=94=82 Caesar's famous quote: @latin[:smallcaps t :color blue]{Alea ia= cta est} > =E2=94=94=E2=94=80=E2=94=80=E2=94=80=E2=94=80 However, I am not a big fan of the way it is implemented - Elisp syntax with the need to layer all the (...) and "...". We may instead re-use my attribute inheritance idea: #+PROPERTY: inline_attr:latin :lang la :latex-command textit :html-tag em ------- On :color and :smallcaps attributes or user-customized markup ------- These proposed attributes are nothing but additional markups that will become a part of Org mode syntax. I see them as nothing different from @smallcals{...} and @color{blue}{...} inline markups. I am not in favour of adding such extra markup to Org mode syntax. Instead, we can make it a part of inline markup extensions, in parallel with what we need to support Texinfo-specific markup like @var, @defun, etc. I also do not see any clear benefit of adding :color and :smallcaps as _attributes_. Just markup will do. If one needs to combine smallcaps/color with other markup, it is a job for ad-hoc markup definitions. ------- pre/post-latex (aka templates) ------- > Specific to the LaTeX backend we have the `:prelatex' and `:postlatex' > attributes (which introduce arbitrary code before and after the content) > and `:latex-command', which overrides the exported command. > `:latex-command nocommand' does not export a command flag. Examples: > > =E2=94=8C=E2=94=80=E2=94=80=E2=94=80=E2=94=80 > =E2=94=82 @foo[:prelatex [bar] :postlatex {baz} :lang it :latex-command b= lah]{lorem ipsum dolor} > =E2=94=94=E2=94=80=E2=94=80=E2=94=80=E2=94=80 I do not like the idea of pre/post- attributes. I think that we discussed this particular idea in the past, when talking about prepending/appending commands like \newpage to headings during LaTeX export (https://list.orgmode.org/orgmode/87czbna4e4.fsf@localhost/) There, I proposed to use a more generalized approach, allowing custom export templates: * headline :PROPERTIES: :ATTR_BACKEND: :export_template "\begin{myenv}\n%s\n\end{myenv}" :ATTR_BACKEND+: "The %%s instances are replaced by the exported element" :ATTR_BACKEND+: (concat "arbitrary sexp, the exported element is bound to: = " *this*) :ATTR_BACKEND+: babel_block_name(exported=3D*this*) :ATTR_BACKEND+: "the property lines are concatenated with \" \" (space)," :ATTR_BACKEND+: "just like the usual approach in `org-export-read-attribute= '" :END: We can apply the same approach when defining ad-hoc markup, extending it a little. Rather than using %s, we introduce more placeholders: - %contents :: like CONTENTS argument in the export transcoders - %transcoded :: the result of what the export backend returns normally - %: :: reference to last Nth optional argument. For example in @abbrev{Computer Science}{CS} %contents =3D=3D CS and %:1 =3D Computer Science - %:attribute :: the value of attribute This way, @@[:prelatex \foo{bar} :color red]{lorem ipsum dolor} will become @foo[:latex-template @code[{\color{red}\foo{bar}%contents}]]{lorem ipsum do= lor} ------- On :export attribute ------- > I'm thinking about adding a new global attribute, `:export', that > would granularly control whether or not to export the object and how to > export it. > > Possible values: "noexport", "contents" (it would export only the content) > or the backends to which you want to export, separated by spaces. Each > backend should be followed by a "+" sign (=3D export all) or "*" (export > content only). For example: > > @foo[:color red :export latex+ odt* html*]{lorem ipsum dolor} Similar to :lang attribute, I see this idea to be more general than inline markup scope. It does not have to be applicable only to inline markup. We can extend selective export further - to paragraph-level elements and to headings. Recently, we even got a feature request to exclude/include certain subtrees from export for specific backends: https://list.orgmode.org/orgmode/1008678740.100388.1708624390334@fidget.co-= bxl/ So, we can approach this just like for :lang attribute, except that we do not need special handling with unconditional inheritance for all the inline markup 1. Allow :lang attributes and make them follow standard inheritance rules=20 2. Introduce a new affiliated keyword #+EXPORT 3. Introduce a new subtree property :EXPORT: 4. Introduce #+EXPORT: per-document keyword 5. (optional) Introduce new #+SELECT_TAGS:BACKEND: #+EXCLUDE_TAGS:BACKEND to allow excluding/selecting subtrees by tag (more visible compared to properties) --=20 Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at