Tagging in code blocks

[alexpdp7]

First, thanks! I've been looking for something like this since I started doing serious technical writing for about 2 years.

My question is: what I currently write we use AsciiDoc, which allows us to tag inside code blocks. We teach people to use shell commands, for example, and we tag bits as user input (what you're supposed to type at a prompt), replaceable (stuff where you'll have to write something variable), highlights (to draw attention to parts of command output), etc. Stuff like this:

Execute the following command, replacing _youruser_ with your GitHub user name. Then note the current qux (in the example below, `quux`).

----
$ *git clone https://github.com/_youruser_/foo*
_...output omitted..._
$ *cd foo*
$ *./bar*
Current qux is `quux`.
----

Is there any possibility to consider providing ways to do this?

I am looking at this project because I am yet to find a markup language that has a well-defined AST and allows doing things like this. We have esp. a hard time writing nice tooling for AsciiDoc (think integrating spell checkers, style checkers, internal lints, etc.).

[uvtc]

Maybe a syntax to specially-mark a verbatim block to allow inline formatting --- something like:

```{*}
func do-stuff(x) {
    check-sensors();
    {*refill-tank();*}
    restart-pump();
}
```

and equivalently

~~~{*}
func do-stuff(x) {
    check-sensors();
    {*refill-tank();*}
    restart-pump();
}
~~~

where refill-tank(); would be rendered as monospace and bold. That is:

• code block is specially-marked with that {*}
• code block is (of course) still rendered in monospace
• only inline markup is allowed in the specially-marked code block
• surrounding curlies always required with the inline markup

and further, within that special code block:

• {`backticks`} would have no effect
• might be nice to have a markup that gets you out of monospace and back to plain roman... maybe {;this;}?

[bpj]

Why not just invert the semantics of {`...`} so that it means "variable width" inside such a block.

I for one would find this useful in inline code too, like in syntax descriptions: $({_identifier_}).

I have a hacky Pandoc filter which chops up inline verbatim based on delimiters, makes each chunk its own Code element and wraps those that shall be styled in Emph/Strong elements, then wraps the whole thing in a Span element. Works pretty well for inline code.

[jgm]

Why not just invert the semantics of {`...`} so that it means "variable width" inside such a block.

Because that makes it impossible to present code that contains literal backticks.
(The same problem affects any syntax for tagging in code blocks.)

[alexpdp7]

Yes, this would be a complex feature. I was discussing the same problem with the creator of Nota, and he pointed me to the LaTeX listings package (3.3 of https://texdoc.org/serve/listings.pdf/0 , Delimiters). I think in the end, if you want code blocks to be not completely verbatim, you need to add complexity to the parser (e.g. Djot already has variable-length fences). I think configurable delimiters are preferrable (if this feature were to be implemented) to escaping (which is what AsciiDoc does).

[lcnbr]

if a syntax were to be developed for this it would be nice to have it work with latex math as well! One could then more easily filter / create macros for latex that also work outside of latex!

[matklad]

I think one way to deal with it is to kick the can down the line and let the rendering process to (recursively) invoke djot on the verbatim snippet. This also scales to, eg, including code from external files or doing other arbitrary processing.

Though, having a programmatic API to tell djot to parse only inlines would help here!