Replace Markdown with reStructuredText or AsciiDoc or some such?

[wking]

On Tue, Nov 08, 2016 at 01:54:21PM -0800, @RobDolinMS wrote:

I'm hesitant to use the auto-generated anchor links from GitHub since we might change the header text (ex: adding section numbers like "4.1 Container Format" and that would change the auto-generated anchor links.

Given this and our ongoing issues with single-page HTML/PDF generation (most recently #562), I'd rather switch to a framework that provides better support for long-form technical docs than Markdown. Both reStructuredText and AsciiDoc (among many other options) make it easy to automate this sort of section numbering, cross referencing, etc., and have good support for publishing into HTML, PDF, and other formats. Instead of repeating that work by hand (and renumbering all later sections when you remove an early one?), I'd rather just switch to a more structured language. And GitHub supports both formats with it's web UI.

To ease the cost of manually inserting anchors (#612, #613, #614, and more to come), it would be nice to automatically add anchors to finer-grained components as well (like Purple Numbers). I haven't found any modern tooling doing that yet though. Still, I think auto-numbered sections and more robust HTML/PDF generation are useful enough goals in their own right.

If this sort of transition sounds useful, I'm happy to put together a PR. That would also help turn up any limitations in either approach.

[RobDolinMS]

I'm not deeply familiar reStructuredText or AsciiDoc.

@wking Do you think this would be an easy conversion or something that might take non-trivial work?

If this would be non-trivial, maybe we move this for consideration to post v1?

[wking]

On Thu, Nov 10, 2016 at 01:13:29PM -0800, Rob Dolin (MSFT) wrote:

@wking Do you think this would be an easy conversion or something
that might take non-trivial work?

That sounds like “I'm cautiously interested. Mock up a PR so I can
get a better feel for this alternative future” ;). I'll try and file
one in the next few days.

[wking]

On Thu, Nov 10, 2016 at 01:28:19PM -0800, W. Trevor King wrote:

That sounds like “I'm cautiously interested. Mock up a PR so I can
get a better feel for this alternative future” ;). I'll try and
file one in the next few days.

The transition is maybe only ¼ complete, but here's where I'm at on
this at the moment [1,2,3]. I'm pretty excited about the
auto-numbered paragraphs (e.g. [4,5]), although the styling still
needs work. And I still need to figure out how to put a literal in
the default xref text 6. And for some reason, anchors on list
entries don't seem to work in the PDF 7.

 HTML output

 PDF output

[wking]

There was some discussion of this in today's meeting 1. My
understanding of the consensus is that:

1. A coherent, navigable spec is a hard requirement 2.
2. Easy access to past versions is a hard requirement 3.
3. Granular anchors are a hard requirement
   (Reference spec when reporting violations runtime-tools#16, 4).
4. Stand-alone HTML / PDF output with functional is not a hard
   requirement (indirectly from [2,5]).

(1) may have been addressed by #626 (@stephenrwalli was going to check
and report back 6).

The easiest way to satisfy (2) is by using GitHub's filesystem browser
with links like 7. Markdown is a good fit for that, as is a single
include-less AsciiDoc file. Multiple AsciiDoc files included together
to form the full spec (as implemented in #628) are not a good fit,
because GitHub's filesystem browser doesn't resolve cross-file
AsciiDoc cross-links. And GitHub's filesystem browser also does not
add automatic-paragraph anchors (e.g. 8 from c22a8dd). You could
push the rendered versions to gh-pages as v1.0.0-rc1/index.html and
v1.0.0-rc1/oci-runtime-spec-1.0.0-rc1.pdf, etc., but that's more
release work than we have now.

You can address (3) either with Markdown/HTML (like #614 and #615) or
in AsciiDoc with the same sort of manual anchor injection 8. You
can address it automatically in AsciiDoc with automatic-paragraph
anchors (e.g. 8 from c22a8dd), but it's hard to get that working
with (2).

You can address (4) with either a single-page Markdown document (so
that all internal cross-links are within the same file) or any
AsciiDoc or otherwise build. But stand-alone doc quality isn't a hard
requirement anyway.

The consensus position seems to be to use #614, #615, etc., for now
and revisit other options later 5. My personal position is that
extending the #614 approach to handle every paragraph and list entry
is more work than adding versioned directories to gh-pages ;).

[RobDolinMS]

BIG THANKS to @wking for pushing this forward.

Per discussion on today's OCI Dev ConCall, could we mark this as Milestone == v1.1 ?

[RobDolinMS]

@opencontainers/runtime-spec-maintainers Would someone please mark this as Milestone v1.1 (or Milestone v2.0)

[wking]

On Mon, Dec 19, 2016 at 10:18:06AM -0800, Rob Dolin (MSFT) wrote: @opencontainers/runtime-spec-maintainers Would someone please mark this as Milestone v1.1 (or Milestone v2.0)

And probably also put the implementation in #628 in the same milestone.

[hqhq]

@RobDolinMS Done.

[tianon]

Closing per the closure of #628 (see #628 (comment))