Add a prototype for asciidoc #41
Conversation
|
I suspect we still want the YAML front matter block to be the same as it would be for a Markdown document? |
|
@jclulow I looked at RFD 77 and didn't see it so I went with what was there and blessed. Mixing and matching markups for the sake of Github rendering isn't something I'd be happy with. [update] I looked at what @trentm did a few hours ago re: RFD77 and assumed that to be the canonical state of the world. As our thinking evolves we can track updates and make the necessary adjustments. |
|
It is, as far as I can tell, a content-agnostic YAML front matter block that we're expecting to put everywhere. While Github can render it, I believe the form originally came from Jekyll. |
|
Note that it appears that asciidoctor does have support for handling the front matter block on at least some level. |
|
@arekinath and I discussed the usage of an AsciiDoc custom attribute (i.e. |
prototypes/prototype.adoc
Outdated
| Copyright 2017 <contribution> | ||
| //// | ||
|
|
||
| # RFD <Number> <Title> |
There was a problem hiding this comment.
Do we want "# ..." for the h1 or "= ..." as the AsciiDoc user-guide seems to suggest? (Note that 'make check' and the bot tooling don't yet recognize "= ...".)
There was a problem hiding this comment.
I'd advocate for = in order to be idiomatic. The token alias is nice, but we shouldn't rely on it.
When in Rome, do as the Romans do.
…d attributes. h/t to @jclulow for pointing the [`skip-front-matter`](http://asciidoctor.org/docs/user-manual/#front-matter-added-for-static-site-generators) attribute.
|
@jclulow Yup, I just got to that part of the manual. Updated the |
The `skip-front-matter` attribute can only be passed in via the CLI: ```sh $ asciidoctor --attribute=skip-front-matter ... ```
Brought to you by: future self asking, "WTF isn't this the default behavior?"
RFD's are going to need their own ghpages branch and joyent.github.io/rfd/rfd*.html needs to be a thing otherwise this won't render well by default. This is a start, and it improves the state of the world.
| --- | ||
| authors: Han Solo <han@example.com>, Frodo Baggins <frodo@example.com> | ||
| state: predraft | ||
| --- |
There was a problem hiding this comment.
blank link before the title please... or perhaps let's move the title to after all the adoc attributes?
There was a problem hiding this comment.
@trentm np. I'm curious as to why there is a preference. I haven't read anything to suggest it matters to asciidoc.
| state: predraft | ||
| --- | ||
| = RFD <NUMBER> <Title> | ||
| :author: Han Solo <han@example.com>; Frodo Baggins <frodo@example.com> |
There was a problem hiding this comment.
Do we need this duplication? If there is a reason for 'author' and 'state' in adoc attributes, then I say we should drop the jekyll-format frontmatter.
There was a problem hiding this comment.
@trentm asciidoc does make use of this attribute somehow, somewhere. If you look at the rendered HTML, it has a placeholder for this value:
The front-matter for jekyll is purely for Jekyll. asciidoc ignores it completely (and though does save the value for reference, the content of the front-matter is un-indexable by asciidoc thereby rendering it effectively useless to asciidoc). I'm indifferent to its presence despite the fact that it doesn't add any value to the meaning of the content and also doesn't improve Github's rendering of the document (compare GH's rendering of asciidoc vs the actual asciidoctor-rendered version at https://cdn.rawgit.com/joyent/rfd/1bc065db/rfd/0106/README.html). I assumed the front-matter was being used somehow by one of our tools and was therefore a structurally important thing to leave in place for compatibility reasons.
There was a problem hiding this comment.
Yes, the front matter is being parsed by the chat bot, and I think by 'make check'. I think I'd prefer we just use the asciidoc attributes, and drop the jekyll front-matter for .adoc RFDs.
There was a problem hiding this comment.
I updated rfdlint to validate the titles for .adoc files. rfdlint is using = as its doc title token, not #: https://github.com/joyent/rfd/blob/master/tools/rfdlint#L131-L133
As for the chat bots, I haven't touched them but suspect it would be a similar change.
There was a problem hiding this comment.
Yup, thanks. I updated the new chatbot (joybot1999) already. I'll get the current jabber bot.
There was a problem hiding this comment.
I lied, I won't get the current jabber bot. Meh, if we are going to move away from it in the next couple of weeks.
prototypes/prototype.adoc
Outdated
| = RFD <NUMBER> <Title> | ||
| :author: Han Solo <han@example.com>; Frodo Baggins <frodo@example.com> | ||
| :state: predraft | ||
| :revremark: State: {state} |
There was a problem hiding this comment.
I know/suspect this came from RFD 77's example. Do we care to have this? /cc @arekinath
My goal here is to reduce boilerplate we don't need.
There was a problem hiding this comment.
:revmark: is the important attribute. I think @arekinath's example was correct in teasing the :state: attribute out from the :revmark: attribute.
prototypes/prototype.adoc
Outdated
| :author: Han Solo <han@example.com>; Frodo Baggins <frodo@example.com> | ||
| :state: predraft | ||
| :revremark: State: {state} | ||
| :attribute-missing: warn |
There was a problem hiding this comment.
Can we have a justification for any/all of these attributes? It would be nice if we could have none of them to have let distraction from the content when reading/editing the raw files.
There was a problem hiding this comment.
re: justification, yes. Most of them substantially improve the readability of the document. My understanding of this prototype was that it was intended to be the canonical source for a cargo-cult^Wskeleton RFD so that future authors wouldn't have to become experts and could still obtain the maximal benefit of the markup format (esp for larger/longer documents).
If we want to take a few minutes to optimize for readability of the raw files I'm sure we can figure out which attributes can be moved to the bottom of the document. I have some anecdotal evidence from my reformatting effort that some of them can't be moved around arbitrarily. I suspect - but have not confirmed - that asciidoc only makes a single-pass over the document.
In general I'd favor maintainability of raw files over readability of the raw files, especially in larger documents where consumption of the raw document is going to become increasingly difficult with the use of external files that are externally maintained and included at document compile-time. I like that both Markdown and asciidoc are very readable forms in the raw (compared with mdoc or Docbook), but I'm less concerned with the first 50 lines of a file compared with the remaining hundreds to thousands of lines of the document that contain the real content.
|
@trentm and I had an offline conversation where he suggested It still doesn't address the problem that Github doesn't render the includes inline (https://github.com/joyent/rfd/tree/master/rfd/0106#recommendations), but that's a secondary concern, imo, because now we have testable examples being used in documentation (https://github.com/joyent/rfd/blob/master/rfd/0106/examples/import_test.go). The compiled HTML is still available via https://cdn.rawgit.com/joyent/rfd/2744c91/rfd/0106/README.html which is a marked improvement in nearly every dimension and its presentation is orthogonal to the prototype markup for asciidoc, imo. |
@arekinath , can you give this a quick once over w/ your tooling. I had to go digging into the spec to see how multiple authors are supported (semicolon delimited list), but I don't know how the missing
:email:attribute will impact things (or if that should also be a semicolon delimited list).Feel free to merge if you approve.