Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add a prototype for asciidoc #41

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Add a prototype for asciidoc #41

Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2a573f9
Add a prototype for asciidoc
sean- Jul 27, 2017
13930a7
Revise the prototype asciidoc to match latest thinking.
sean- Jul 28, 2017
3322f1a
Update asciidoc prototype to include both the desired front-matter an…
sean- Jul 30, 2017
7bb0290
Remove the `skip-front-matter` attribute, add a stub section.
sean- Jul 30, 2017
3b3de51
Warn when an undefined attribute is referenced.
sean- Jul 30, 2017
ed62689
Add keywords and a revnumber to the asciidoc prototype
sean- Jul 30, 2017
da40ee7
Fix admonition icons when rendering on Github
sean- Jul 30, 2017
4e5beb2
Use the `include` macro to move the asciidoc front-matter to an exter…
sean- Aug 1, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions prototypes/prototype.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
authors: Han Solo <[email protected]>, Frodo Baggins <[email protected]>
state: predraft
---
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

blank link before the title please... or perhaps let's move the title to after all the adoc attributes?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@trentm np. I'm curious as to why there is a preference. I haven't read anything to suggest it matters to asciidoc.

= RFD <NUMBER> <Title>
:author: Han Solo <[email protected]>; Frodo Baggins <[email protected]>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@trentm asciidoc does make use of this attribute somehow, somewhere. If you look at the rendered HTML, it has a placeholder for this value:

image

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup, thanks. I updated the new chatbot (joybot1999) already. I'll get the current jabber bot.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

:state: predraft
:revremark: State: {state}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:revmark: is the important attribute. I think @arekinath's example was correct in teasing the :state: attribute out from the :revmark: attribute.

:attribute-missing: warn
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

:docinfo:
:doctype: article
:hide-uri-scheme:
:icons: font
:idprefix:
:idseparator: -
:keywords: rfd, rfd <NUMBER, prototype, sample, keywords
:numbered:
:revnumber: 0.1.0
:sectanchors:
:sectlinks:
:sectnums:
:sectnumlevels: 2
:showtitle:
:source-highlighter: pygments
:toc: left
:xrefstyle: full
ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

////
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.

Copyright 2017 <contribution>
////

[[introduction]]
== Introduction