Re: Verbatim content (inline-special-block)

[Ihor Radchenko <yantar92@posteo.net>]

Max Nikulin <manikulin@gmail.com> writes:

>>     - We should be able to define special markup for code, where the
>>       contents is not parsed. Something like
>> 
>>       @code{ unlike =code=, we can have leading and trailing spaces }
>>       @code{ @foo{is not interpreted inside}}
>
> I think, it should be controlled by some optional parameter like
>
>      @kbd[:verbatim t]{ unlike =code=, ... }

I do not like this idea - this will make the attribute list a part of
the Org markup spec, which I would like to avoid if possible:

1. External parsers would be forced to understand the attribute syntax,
   which will complicate Org markup spec.
2. Our own parser may have to account for attribute inheritance while
   parsing, which will complicate the parser too much.

The question remains how to define custom verbatim markup, of course.

It may be enough to have @kbd{@code{...}} - it is not like Texinfo has a
concept of truly verbatim text like in Org.

Alternatively, we may allow two classes of inline markup:
@foo{parsed *text* inside}
and
@foo={verbatim *text* inside}/@foo~{verbatim *text* inside}

This way, instead of @code{}, we should use @code~{...} or even
@~{...}/@={...} (mnemonics for ~...~ and =...=)

> Certainly parsing of normal Org markup should be suppressed,
> however I am less sure concerning @markup{}. In the following example 
> text inside @param{} may be emphasized:
>
>      @code{def calculate(@param{expr}, @param{env})}
>
> "@" inside such object may be escaped as @{@}. An alternatively is a 
> parameter like :parse that can have values like "markup", "custom", 
> "verbatim". This case "verbatim" disabled parsing of @objects().

AFAIU, you are referring to how Texinfo handles its @code{...} command,
where other texinfo commands are allowed, which is _conceptually_
different from how Org handles the verbatim/code - as a general rule,
all the "code" in Org mode syntax is taken verbatim (with the only
exception of src blocks where we have no choice).

Also, the reason why Texinfo users do @param in @code is the lack of
automatic syntax highlighting, unlike in Org mode.

I think that Org mode's equivalent of Texinfo @code should be either

1. inline src block
2. if direct markup is unavoidable, use something like
   @fixedwidth{@code{def calculate(}@param{expr}@code{, }@param{env}@code{)}}
   Most of the @code{..} can be safely dropped. It is just to illustrate
   the idea that we still parse the contents.

   In practice, things like
   *def* calculate(expr, env) "foo\alpha"
   will become
   @fixedwidth{*def@code{*} calculate(@param{expr}, @param{env}) "foo@code{\}alpha"}
   or
   @fixedwidth{\star{}def* calculate(@param{expr}, @param{env}) "foo\@@{}alpha"}

-- 
Ihor Radchenko // yantar92,
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>