Transition from Markdown to AsciiDoc #628
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This will make it a lot easier to structure a large document, e.g. auto-generating the table of contents [1], numbering sections [1], anchoring sections [2], etc. AsciiDoc usually uses .txt extensions [3], but GitHub recognizes .asciidoc, .adoc, and .asc [4]. I've gone with the shortest GitHub-recognized extension. The header version (v1.0.0-rc2 at the moment) ends up in revnumber [5] for later reuse. With AsciiDoctor you can apply attribute replacement to source blocks [6], but AsciiDoc's source highlighter doesn't support that [7], and I've stuck with vanilla AsciiDoc highlighting with Pygments [8,9] here. Lines like: :OCI: http://www.opencontainers.org/ are attribute entries [10], which are basically constants so you can stay DRY and avoid later distractions (like long URIs interrupting your paragraph's flow). The separate Make rules for XHTML and PDF are because a2x (for whatever reason) only supports -D / --destination-dir for HTML-based output formats. I've dropped the Docker tooling for now, and will put that back in when I get around to testing it. I've also dropped the '&& \' line continuations, since Make recipes apply the same "abort if the command dies" semantics without the continuations. [1]: http://www.methods.co.nz/asciidoc/userguide.html#X88 Appendix H: Backend Attributes [2]: http://www.methods.co.nz/asciidoc/userguide.html#_section_ids 8.4.2 Section IDs [3]: http://www.methods.co.nz/asciidoc/faq.html#_what_is_the_preferred_file_name_extension_for_asciidoc_files [4]: https://github.com/github/markup#markups [5]: http://www.methods.co.nz/asciidoc/userguide.html#X95 8.2 Header [6]: http://asciidoctor.org/docs/user-manual/#applying-substitutions [7]: http://asciidoc.org/source-highlight-filter.html#_block_attributes [8]: http://asciidoc.org/source-highlight-filter.html#_pygments [9]: http://pygments.org/ [10]: http://www.methods.co.nz/asciidoc/userguide.html#X18 28 Attribute Entries Signed-off-by: W. Trevor King <wking@tremily.us>
…EADME The README will be a GitHub landing page, but these are part of the spec proper. I'd like to cleanup the wording a bit while I'm touching the lines, but I'll leave that for follow-up work. Signed-off-by: W. Trevor King <wking@tremily.us>
The README will be a GitHub landing page, but these are part of the spec proper. I've quoted [1] the xrefs [2] for now, because the targets haven't been transitioned over yet. The only change I made to the content was re-ordering the Linux portions to group the runtime references together (instead of having runtime before the configs and runtime-linux after). [1]: http://asciidoc.org/userguide.html#X81 Monospaced text [2]: http://asciidoc.org/userguide.html#_xref Signed-off-by: W. Trevor King <wking@tremily.us>
The README will be a GitHub landing page, but these are the informative lead-in to the spec. I've quoted [1] the xrefs [2] for now, because the targets haven't been transitioned over yet. In some cases, I expect the appropriate caption to be filled in by the (possibly autogenerated) xreflabel [3]. While the use-cases came after the definitions and protocols in the old README, I've put them first in the AsciiDoc spec. It reads better to me with the informative use-cases first to orient readers before we get down to business with the normative definitions and protocols. [1]: http://asciidoc.org/userguide.html#X81 Monospaced text [2]: http://asciidoc.org/userguide.html#_xref [3]: http://asciidoc.org/userguide.html#X30 anchor Signed-off-by: W. Trevor King <wking@tremily.us>
This gets a title [1] with an anchor [2], and the old *...* becomes _..._ [3]. I've also dropped the separate "Container Format" header because it didn't seem to be adding any useful information. [1]: http://asciidoc.org/userguide.html#X17 Titles [2]: http://asciidoc.org/userguide.html#X30 anchor [3]: http://asciidoc.org/userguide.html#X51 10.1. Quoted Text Signed-off-by: W. Trevor King <wking@tremily.us>
There's a bit of hoop-jumping here for syntax highlighting. asciidoc (the command) can generate highted HTML (and the source-highlighter line in oci-runtime-spec.asc sets it up to use Pygments). However, asciidoc's direct HTML output does not support xref default captions [1]. asciidoc's DocBook output, on the other hand, *does* support default captions [1]. Unfortunately, in this case asciidoc punts the syntax highlighting to DocBook as well, passing through a programlisting tag [2,3]. Unfortunately, syntax highlighting there depends on an XSLTHL extension module which is only implemented in Java [4,5], and that's not worth the trouble ;). Highlighting is a bit easier for the PDF output, because while asciidoc is still delegating to DocBook, DocBook is in turn delegating to LaTeX and listings. Listings v1.6 doesn't support JavaScript or JSON, but it does support Python [6], and Python's dict, list, string, and number syntax is very close to JSON's object, array, string, and number syntax. To setup that mapping, we copy the usual asciidoc-dblatex.sty from the system, add a json -> python alias, and tell dblatex to use our amended style. Also bump the section numbering depth back up to DocBook's default 8 [7]. For some reason, the default a2x output seems to set this to 2. And bump the number of ToC levels up from two to four [8]. An anchor's default captions [9] seem to be treated literally without further parsing. So [[created,`created`]] will lead to references like a regularly-styled "`created`" instead of the intended monospace "created". Monospace isn't worth jumping through lots of hoops for though, so I've just left the backticks off and leaned on the link highlighting to set the should-be-literals off from surrounding text. The [[create,create]] anchors avoid auto-generated captions like: Section 5.4.2, "Create" because we usually use those references as stand-ins for an invokable command (e.g. `funC create ...`). [1]: http://asciidoc.org/userguide.html#_xref [2]: http://asciidoc.org/source-highlight-filter.html#_docbook_outputs [3]: http://docbook.org/tdg/en/html/programlisting.html [4]: http://docbook.sourceforge.net/release/xsl/1.79.1/doc/html/highlight.source.html [5]: https://sourceforge.net/p/xslthl/wiki/Home/ [6]: http://mirrors.ctan.org/macros/latex/contrib/listings/listings.pdf#page=13 [7]: http://docbook.sourceforge.net/release/xsl/1.79.1/doc/html/section.autolabel.max.depth.html [8]: http://asciidoc.org/faq.html#_the_asciidoc_toclevels_attribute_does_not_work_with_docbook_outputs_why [9]: http://asciidoc.org/userguide.html#X30 anchor Signed-off-by: W. Trevor King <wking@tremily.us>
The new bits for this file are the table [1] and the leveloffset [2]. Keeping runtime-linux under runtime makes the ToC tree more consistent (all the runtime stuff is under section 5). [1]: http://asciidoc.org/userguide.html#_tables 23. Tables [2]: http://asciidoc.org/userguide.html#X90 36.5. Combining separate documents Signed-off-by: W. Trevor King <wking@tremily.us>
I haven't gone with [[config]] instead of [[config,configuration]], because I want the section-numbered reference in the protocol listing. Signed-off-by: W. Trevor King <wking@tremily.us>
For labeled paragraphs, e.g.: [[foo]] Foo bar baz... the paragraph ID (pid) will be "foo". For unlabeled paragraphs, e.g.: Foo bar baz... the paragraph label will be _para-#. The implementation is based on the FAQ entry [1], but I've shuffled things around to get the _para-# support and a linkable pilcrow (a la Purple Pilcrows [3]). It would still be nice to have logic to only show pilcrows on hover (although I'm not sure how that would work in PDF output). [1]: http://asciidoc.org/faq.html#_how_do_i_number_all_paragraphs [2]: http://www.tbray.org/ongoing/When/200x/2004/05/31/PurpleAgain Signed-off-by: W. Trevor King <wking@tremily.us>
Dropping the "Platform-specific configuration" header so we can down
to:
6. Container Configuration
6.7. Linux-specific Container Configuration
6.7.5. Control groups
6.7.5.1. Device whitelist
without exceeding AsciiDoc's four-level section limit [1].
[1]: http://asciidoc.org/userguide.html#_sections
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: W. Trevor King <wking@tremily.us>
There is no reason to separate these from the definitions which are already there. But the existing definition paragraphs define multiple terms a piece, so I haven't converted them to the alphabetized labeled-list format I've been using for glossary entries. Signed-off-by: W. Trevor King <wking@tremily.us>
|
CC @vbatts, @RobDolinMS. |
|
The rendered pdf/html look pretty good! |
|
@wking Sorry I missed this PR earlier. I agree that if everyone is on board, we should land this first. |
|
can we do this after #626 ? |
|
On Tue, Nov 15, 2016 at 12:20:20PM -0800, Doug Davis wrote:
Sure. I'm happy to rebase around anything that lands before this PR. |
|
that's how I feel too :-) |
|
The rendered version looks good ( like really good compared to markdown-rendered 😄 ) |
|
could be rebased now that #626 is merged. |
|
On Wed, Nov 16, 2016 at 12:19:06PM -0800, Mrunal Patel wrote:
There are still a lot of open PRs that would conflict with this one |
|
I'm +1 for this change, rendered version looks better than markdown. |
|
Per @crosbymichael, not sure we want to do this at all; but agree we want to hold-off on this conversation until after v1.0.0 |
|
We will looking into consolidating the spec into a single markdown file to make publishing easier. |
|
there will be pains in either staying with markdown or switching to asciidoc |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
As discussed in #615. Rendered HTML and PDF forms are here and here. There's a fair bit of detail in most commit messages if you're interested in that sort of thing.
The base of this PR is currently a few commits behind master, but keeping this branch up do date will be a pain. I think we should collect feedback on the approach here, and if/when the approach collects enough maintainer approval I'll push through a rebase and we can land this quickly (before it goes stale again, which will happen if pretty much anything touching the Markdown lands ;).