What's the purpose of requiring meta tags in the first line of textual document? And possible improvement.

21 views
Skip to first unread message

ska...@gmail.com

unread,
Oct 8, 2018, 4:32:17 PM10/8/18
to YARD
Yard supports meta tags in textual documents (a.k.a. extra file
objects).  However, some feature important to me is missing, and I plan
to develop it.  This is going to be a somewhat breaking change,
therefore I prefer to discuss it first.


== The current state ==

Yard requires that meta tags are declared in a way resembling tags in
Ruby code.  Also, the sequence of meta tags must start in the first line
of the document.  In example:

----------------
# @title The Document Title
# @author The Author Name

More of document.
----------------

I have delimited the document body with dashes for better readability.
I will follow this convention throughout this message.

Yard removes meta tags from document before passing it to markup
processor, so that they do not clutter the rendered documentation.
However, one may want to display given document outside Yard as well,
i.e. in GitHub.  For this reason, Yard allows to surround meta tags with
a regular HTML comment:

----------------
<!--
# @title The Document Title
# @author The Author Name
-->

More of document.
----------------

In this case, a whole comment block will be removed when processed by
Yard.  However, this Markdown document will still display as intended in
GitHub, as the Yard-specific markup is hidden from user in a comment.


== The problem ==

This is far from being sufficient, though, as HTML comments are markup-
specific.  Some markup languages like Markdown or Textile support them,
but others like AsciiDoc do not.  For example, AsciiDoc uses four
slashes to introduce a comment block:

----------------
////
# @title The Document Title
# @author The Author Name
////

More of document.
----------------

Furthermore, comments are not the only way of hiding content from user.
For example, AsciiDoc supports conditional processing directives:

----------------
ifdef::env-yard[]
# @title The Document Title
# @author The Author Name
endif::[]

More of document.
----------------

Although Textile supports injecting raw HTML, hence regular HTML
comments do work, users will probably prefer to use Textile's own
comments syntax:

----------------
###. Yard meta tags
# @title The Document Title
# @author The Author Name

More of document.
----------------

Or, Textile's multiline comments:

----------------
###..
# @title The Document Title
# @author The Author Name

This is also a comment, which includes some information
unrelated to Yard, maybe a TO-DO list.

p. More of document.
----------------

Neither of above will work correctly in current versions of Yard.
AsciiDoc users are unable to hide meta tags markup oustside Yard,
and Textile users are forced to use a foreign syntax.


== The improvement ==

I propose that Yard should not interpret any type of comment.  Instead,
it should simply expect the first meta tag in line 1 or 2, and remove
only these meta tags, leaving comment markup intact, whatever syntax it
follows.  It will result with a possibly empty comment block in rendered
document, which is harmless.

For example, following document:

----------------
<!--
# @title The Document Title
# @author The Author Name
-->

More of document.
----------------

Will be preprocessed to look like:

----------------
<!--
-->

More of document.
----------------

And then rendered.


== The catch ==

My proposition breaks following test case:

----------------
it "does not parse out attributes if there are newlines prior to attributes" do
  file = ExtraFileObject.new('file.txt', "\n# @title\nFOO BAR")
  expect(file.attributes).to be_empty
  expect(file.contents).to eq "\n# @title\nFOO BAR"
end
----------------

I am not sure why it has been introduced.  If it is meant to provide
some means of meta tags escaping, then I see two solutions:

1. Do a breaking change.  User can precede content with double blank
lines instead.

2. Add another requirement, that if meta tags are supplied from line 2,
then line 1 must not consist of blank characters only.


Regards,
Sebastian

ska...@gmail.com

unread,
Oct 8, 2018, 4:34:12 PM10/8/18
to YARD
Oh, I forgot to mention, that above message duplicates a feature request
reported by me in issue tracker
(https://github.com/lsegal/yard/issues/1192). I am reintroducing it here
because the mailing list is a correct place for that, and because I want
to discuss the problem prior implementing it.

Reply all
Reply to author
Forward
0 new messages