Meta tags in AsciiDoc (and some other markup languages)

[ska...@gmail.com]

Meta tags in AsciiDoc (and some other markup languages)

Yard supports meta tags in extra documents (@markup, @title etc.).  The problem is that these documents may be rendered outside Yard as well (typically in GitHub), and then meta tags become clutter.

Currently, there is one solution for that: meta tags can be surrounded with HTML comments, as they are recognized by Yard (see: https://github.com/lsegal/yard/blob/3ffb577107cc/lib/yard/code_objects/extra_file_object.rb#L85-L105).  However, many markup languages forbid raw HTML, so this trick has limited use.  For instance, it will not work in AsciiDoc, which is preferred by many, including myself (see https://github.com/lsegal/yard/issues/1192).

I see two improvements which can be made:

1. More comment types can be supported.  For instance, AsciiDoc's comment is a block surrounded with at least four backticks ("````").  Hence, it is just a matter of improving regular expressions.  However, I have doubts if Yard should parse comments at all, especially that particular markup (and comment syntax) is unknown at this step (i.e. may be defined by a @markup meta tag inside that comment).  It will work 99% of time, but may give some unexpected results in the edge cases.  Also, these regular expressions will require some maintenance.

2. Instead parsing comments, Yard could simply skip the first line (if includes no meta tags) and look for tags starting from line two.  Then, lines with meta tags would be removed from document, but surrounding comment (if present) left intact.  This approach allows for variety of comment syntaxes, including Textile's "###." syntax (https://txstyle.org/doc/40/textile-comments), or even AsciiDoc's preprocessor directives, which are otherwise difficult to parse.

Personally, I am leaning towards the second option as I consider it the most universal and future-proof.  I can implement it, but I wanted to discuss it first.

Regards,

Sebastian