rfc14: render examples inline

[garlick]

RFC 14 is kind of long and difficult to digest. It might be nice to refocus RFC 14 on succinctly defining well formed jobspec, leaving the examples and any expository discussion to another RFC.

Could we split the examples out to another Flux Jobspec Use Cases RFC? At the same time could we work around the fact that the jobspec examples are not rendered inline by github, by generating the final document with expanded examples as suggested in asciidoctor/asciidoctor#1088?

Edit: let's just focus on that last bit, rendering examples inline, here, and then we'll decide whether to open a new issue on reorganizing after that's done.

[grondo]

I'm not sure that splitting the material is going to make the RFC any easier to digest, it is just a difficult specification to grok (for me anyway). This might be a bit like trying to make Ulysses easier to understand by turning it into a trilogy. (besides, the rfc is < 1000 lines even with the examples) Maybe what we need is a rewrite?

However, I don't mind splitting up the use cases into a separate RFC, this does mean that updates to RFC 14 will always have to affect another RFC (and possibly vice versa).

At the same time could we work around the fact that the jobspec examples are not rendered inline by github, by generating the final document with expanded examples as suggested in github/markup#1088?

Did you reference the right issue/PR? That one is just a PR to integrate Asciidoctor 1.5.6.1 into github-markup and push it to github.com.

[garlick]

Did you reference the right issue/PR?

Referenced the wrong project! I edited the orig comment to reference the correct one.

[garlick]

Let's focus this issue on rendering examples inline in RFC 14. We can consider splitting it separately after we get this done.

[garlick]

As discussed briefly in flux-framework/flux-core#2036, it sounds like we might pursue a way to publish our docs as static web pages. In pr #173 the make html target was updated to use asciidoctor and coderay to generate html that properly expands includes (and syntax highlights code examples). We just need somewhere to push them.

Given this direction, the workaround here of generating the adoc files is perhaps less interesting, so closing this issue.