`@`-tags delimiter

[panglesd]

I think it is clear from #1138 that tags should not expand unconditionally to the rest of the content.

So we need a way to have tags extend to several paragraphs. To make the discussion clearer, I open this issue separately from #1138 (which is about "what is the range of undelimited tags").

Here are the various options that I have recollected:

1. (From @dbuenzli) a single @ on an empty line adds the next block in the tag

   @return This is a paragraph
   @
   This is another paragraph in the same tag block

2. (From @dbuenzli) A @begin-block ... @end-block delimiter:

   @return @begin-block This is a paragraph
   
   This is another paragraph in the same tag block @end-block

3. (From @EmileTrotignon) A {| |} delimiter:

   @return {| This is a paragraph
   
   This is another paragraph in the same tag block |}

4. (From @EmileTrotignon) A {@ ...} delimitation:

   {@return This is a paragraph
   
   This is another paragraph in the same tag block}

Option 1. is weird to me (it can be explained, if we decide to delimit the range of an undelimited tag block with blank lines). Option 2. I'm not a fan since it feels quite orthogonal to what is currently used to delimit, in the odoc syntax. Option 3. is similar to option 2, replacing 11 letters with 2 symbols. Still orthogonal, I think! Option 4. is clearly my favorite, as it seems to integrate naturally in the odoc way of delimiting.

Feel free to comment, suggest another syntax, ... like and subscribe!

[dbuenzli]

4. looks good!

[EmileTrotignon]

4 is also my favourite

[jonludlam]

I'm also happy with 4 - though it's worth mentioning that any instance of [ in the text will turn it into a code block, so we may need to be able to escape them.

[panglesd]

Oh no, I did not think about that... Thanks for pointing it out. Having to escape them seems cumbersome: [ are used too often in odoc...

[dbuenzli]

I don't understand why this is the case.

[panglesd]

The doc seems not to be perfectly up to date with regards to code blocks, but one can specify a language as well as some other metadata information in a code block. Example:

{@ocaml env=f1 version>=4.06 [code goes here]}

The language name (ocaml here) is supposed to be chosen without constraint: it could be @return. Then, how to distinguish this from a code block?

{@return [x + 1]}

[dbuenzli]

Ah yes :-( Thanks for the explanation. In practice you'd have to escape only the first '[' but it is a bit annoying.

Some quick ideas. Perhaps combining 3 and 4 and have for example:

1. {{@tag … }}

2. {@ @tag … @}

3. {@@tag …}

   and require language that start with an @ (quite unlikely) to escape {@\@oddlanguage []}.

I think 2. could be ok no ?

[panglesd]

Yes, I think 2. could be OK, but let's continue a bit the list before choosing :)

4. Like 2 but without @ in the closing bracket:

   {@ @tag …}

5. Have a regular way to group in a div. A div could be {@ ...} or (5') {@ ... @}.

   @tag {@ … }
   @tag {@ … @}

6. Have a regular way to group in a div, but this time the syntax is taken from the extension nodes of OCaml. A div could be {% ...} or (6') {% ... %}.

   @tag {% … }
   @tag {% … %}

What I like about 6 and 6' is that we can easily add plugins which rewrite the extension node, if we allow them to be named: {%mermaid ... } (for mermaid diagrams) but that's a deep hole to fall into...

[dbuenzli]

4. Like 2 but without @ in the closing bracket:

But couldn't {@ @return [x+1]} be a code block ? If not then why not.

Regarding 5, personally I rather have the directive in the braces that's the ocamldoc way.

Regarding 6, I think code blocks are sufficient for that. For example {@mermaid eval=true […]} or something like that.

[panglesd]

Regarding 6, I think code blocks are sufficient for that. For example {@mermaid eval=true […]} or something like that.

Yes, mermaid was a bad example... Maybe a custom kind of admonition would be a better example.

{%theorem
  If {m x} is even then {m x+1} is odd.
}

(although I agree that code blocks are sufficient, you can run the parser on them)

[panglesd]

Another option that was suggested (I'm collecting them):

Base the scope of the tag on indentation:

@return [foo] which for bla

  This is also in the tag scope since it's indented

This is not in the tag

I think this does not integrate well with the current odoc syntax (no current syntax is affected by indentation). #1219 is an example among others). It could be a new direction, but that's a big change.

However, it is worth mentioning since some people tried that.

[panglesd]

Regarding 6, let me add that we could slightly modify it to distinguish inline and block "extension nodes" :

This element is {%blink special} and inline.

{%%example
  This one is a block
}

Currently this is my personal preference since I think it will be useful for the future, if one day plugins are possible. Without a name, it is simply grouping a list of blocks into a single blocks (thus we can group blocks under a tag).

However, maybe 4. ({@ @tag …}) is less controversial, and decently solves this specific problem without interacting too much with the rest of the syntax (it can only be used in the context of tags).