*: printable documents #263
Conversation
| config.md \ | ||
| config-linux.md \ | ||
| runtime-config.md \ | ||
| runtime-config-linux.md |
There was a problem hiding this comment.
Is maintaining this hard-coded list going to be a hassle? (ie, would something like $(wildcard *.md) also be correct without the same maintainer cost?)
There was a problem hiding this comment.
I thought that too, but order matters for how it assembles them in the pdf
There was a problem hiding this comment.
On Wed, Dec 09, 2015 at 09:37:07AM -0800, Tianon Gravi wrote:
+DOC_FILES := \
- README.md \
- code-of-conduct.md \
- ROADMAP.md \
- …
- runtime-config-linux.md
Is maintaining this hard-coded list going to be a hassle? (ie,
would something like$(wildcard *.md)also be correct without the
same maintainer cost?)
It looks like the ordering is significant, so the wildcard approach
would require numbering the filenames (e.g. 01-README.md). I think
the hard-coded approach is fine, since filename churn has been small
so far, and will only get smaller as the repository matures (excepting
a few isolated reorgs).
There was a problem hiding this comment.
On Wed, Dec 09, 2015 at 09:37:07AM -0800, Tianon Gravi wrote:
+DOC_FILES := \
- README.md \
- code-of-conduct.md \
- ROADMAP.md \
- implementations.md \
- bundle.md \
- runtime.md \
- runtime-linux.md \
- config.md \
- config-linux.md \
- runtime-config.md \
- runtime-config-linux.md
List is missing principles.md (insert after code-of-conduct.md?).
There was a problem hiding this comment.
|
preview here --> https://vbatts.fedorapeople.org/oci.pdf |
|
On Wed, Dec 09, 2015 at 09:53:07AM -0800, Vincent Batts wrote:
That seems to be preserving our “one sentence per line”, which looks |
|
I did consider jekyll or similar. The we might could have it displayed on https://opencontainers.github.io/specs/ or such. |
I do not like having this build step of printable documentation depending on pulling a container, but the pandoc+latex combo is a big bundle. This is the minimal and cleanest approach for using these tools, for now. Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
|
updated. added principle.md, an |
|
nice! LGTM |
|
LGTM ❤️ |
|
Would it be possible to auto-generate docs based on the schema (and comments) eventually? |
|
@vishh nice hope. perhaps something like swagger. This is a first effort. |
|
what do y'all say about where to have these generated artifacts per release? |
|
+1 On Thu, Dec 17, 2015 at 12:20 PM, Vincent Batts notifications@github.com
|
|
@vbatts maybe uploaded as a tar file to github for now ? Would be nice to publish them to a more accessible place as well |
|
Yeah, I'd be +1 to GitHub releases for now. 😄
|
|
right on. It looks like just doing a git push of a tag, makes a release, but I can not attach files that way. Files can only be attached by doing the release through the github UI. |
|
https://vbatts.fedorapeople.org/oci/v0.1.1/ for reference of the first tag... |
|
IIRC, you can make a "release" on top of an existing tag you've pushed though |
|
/me looks again |
|
removing the files from the reference host... |
|
lgtm |
|
3 LGTMs. merging |
At the end of the list, to match its position in the README. This catches opencontainers#107 up with opencontainers#263, which I'd missed during one of the opencontainers#107 rebases. Signed-off-by: W. Trevor King <wking@tremily.us>
Defaulting to whichever PANDOC is first in your path. This mirrors the existing DOCKER handling. Folks who want to use the old path can run: $ make PANDOC=vbatts/pandoc ... I'm not sure why 4ee036f (*: printable documents, 2015-12-09, opencontainers#263) went with a variable for 'docker' but a hard-coded path for 'pandoc'. I expect it was just oversight. Signed-off-by: W. Trevor King <wking@tremily.us>
The bulk of this was addressed by 4ee036f (*: printable documents, 2015-12-09, opencontainers#263). Any remaining polishing of that workflow seems like a GitHub-issue thing and not a ROADMAP thing. And publishing these to opencontainers.org certainly seems like it's outside the scope of this repository (although I think that such publishing is a good idea). Signed-off-by: W. Trevor King <wking@tremily.us>
# digest/hashing target Most of this has spun off with [1], and I haven't heard of anyone talking about verifying the on-disk filesystem in a while. My personal take is on-disk verification doesn't add much over serialized verification unless you have a local attacker (or unreliable disk), and you'll need some careful threat modeling if you want to do anything productive about the local attacker case. For some more on-disk verification discussion, see the thread starting with [2]. # distributable-format target This spun off with [1]. # lifecycle target I think this is resolved since 7713efc (Add lifecycle for containers, 2015-10-22, opencontainers#231), which was committed on the same day as the ROADMAP entry (4859f6d, Add initial roadmap, 2015-10-22, opencontainers#230). # container-action target Addressed by 7117ede (Expand on the definition of our ops, 2015-10-13, opencontainers#225), although there has been additional discussion in a7a366b (Remove exec from required runtime functionalities, 2016-04-19, opencontainers#388) and 0430aaf (Split create and start, 2016-04-01, opencontainers#384). # validation and testing targets Validation is partly covered by cdcabde (schema: JSON Schema and validator for `config.json`, 2016-01-19, opencontainers#313) and subequent JSON Schema work. The remainder of these targets are handled by ocitools [3]. # printable/compiled-spec target The bulk of this was addressed by 4ee036f (*: printable documents, 2015-12-09, opencontainers#263). Any remaining polishing of that workflow seems like a GitHub-issue thing and not a ROADMAP thing. And publishing these to opencontainers.org certainly seems like it's outside the scope of this repository (although I think that such publishing is a good idea). [1]: https://github.com/opencontainers/image-spec [2]: https://groups.google.com/a/opencontainers.org/d/msg/dev/xo4SQ92aWJ8/NHpSQ19KCAAJ Subject: OCI Bundle Digests Summary Date: Wed, 14 Oct 2015 17:09:15 +0000 Message-ID: <CAD2oYtN-9yLLhG_STO3F1h58Bn5QovK+u3wOBa=t+7TQi-hP1Q@mail.gmail.com> [3]: https://github.com/opencontainers/ocitools Signed-off-by: W. Trevor King <wking@tremily.us>
At the end of the list, to match its position in the README. This catches opencontainers#107 up with opencontainers#263, which I'd missed during one of the opencontainers#107 rebases. Signed-off-by: W. Trevor King <wking@tremily.us>
Defaulting to whichever PANDOC is first in your path. This mirrors the existing DOCKER handling. Folks who want to use the old path can run: $ make PANDOC=vbatts/pandoc ... I'm not sure why 4ee036f (*: printable documents, 2015-12-09, opencontainers#263) went with a variable for 'docker' but a hard-coded path for 'pandoc'. I expect it was just oversight. Signed-off-by: W. Trevor King <wking@tremily.us>
# digest/hashing target Most of this has spun off with [1], and I haven't heard of anyone talking about verifying the on-disk filesystem in a while. My personal take is on-disk verification doesn't add much over serialized verification unless you have a local attacker (or unreliable disk), and you'll need some careful threat modeling if you want to do anything productive about the local attacker case. For some more on-disk verification discussion, see the thread starting with [2]. # distributable-format target This spun off with [1]. # lifecycle target I think this is resolved since 7713efc (Add lifecycle for containers, 2015-10-22, opencontainers#231), which was committed on the same day as the ROADMAP entry (4859f6d, Add initial roadmap, 2015-10-22, opencontainers#230). # container-action target Addressed by 7117ede (Expand on the definition of our ops, 2015-10-13, opencontainers#225), although there has been additional discussion in a7a366b (Remove exec from required runtime functionalities, 2016-04-19, opencontainers#388) and 0430aaf (Split create and start, 2016-04-01, opencontainers#384). # validation and testing targets Validation is partly covered by cdcabde (schema: JSON Schema and validator for `config.json`, 2016-01-19, opencontainers#313) and subequent JSON Schema work. The remainder of these targets are handled by ocitools [3]. # printable/compiled-spec target The bulk of this was addressed by 4ee036f (*: printable documents, 2015-12-09, opencontainers#263). Any remaining polishing of that workflow seems like a GitHub-issue thing and not a ROADMAP thing. And publishing these to opencontainers.org certainly seems like it's outside the scope of this repository (although I think that such publishing is a good idea). [1]: https://github.com/opencontainers/image-spec [2]: https://groups.google.com/a/opencontainers.org/d/msg/dev/xo4SQ92aWJ8/NHpSQ19KCAAJ Subject: OCI Bundle Digests Summary Date: Wed, 14 Oct 2015 17:09:15 +0000 Message-ID: <CAD2oYtN-9yLLhG_STO3F1h58Bn5QovK+u3wOBa=t+7TQi-hP1Q@mail.gmail.com> [3]: https://github.com/opencontainers/ocitools Signed-off-by: W. Trevor King <wking@tremily.us>
I do not like having this build step of printable documentation
depending on pulling a container, but the pandoc+latex combo is a big
bundle. This is the minimal and cleanest approach for using these tools,
for now.
Just run
make pdf && xdg-open ./output/docs.pdfPer: https://github.com/opencontainers/specs/blob/master/ROADMAP.md#printablecompiled-spec
Signed-off-by: Vincent Batts vbatts@hashbangbash.com