search

AMWA-TV / nmos-render-scripts

Build scripts for NMOS documentation
https://hub.docker.com/r/amwa/nmos-render
Apache License 2.0
1 stars 1 forks source link

Better document numbering... or remove document numbering? #38

Closed peterbrightwell closed 3 years ago

peterbrightwell commented 3 years ago

At the moment e.g. 10.0. Ten.md will appear rendered in the index before 9.0. Nine.md, because this is done with a simple bash glob. This has become an issue with nmos-modeling which currently has >10 top level docs and I had to number them 101.0. Scope.md etc.

Should extend to sub-sections also e.g. order 9.9.9, 9.9.10, 9.10.1, 10.0 etc.?

(And allow 10. without a trailing zero?)

peterbrightwell commented 3 years ago

Alternatively – and perhaps preferably? – we could remove document numbering altogether and specify the outline in an index document? As we don't have paragraph numbering that would be more consistent. By making the index docs/README.md the links can be added during authoring and would render to HTML. Some additional work would be needed to make the navigation arrows keep working, and we'd need to either backport to older releases we still want rendered, or include the old code to handle those.

peterbrightwell commented 3 years ago

We've now moved to un-numbered documents with the index in docs/README.md. See #39.