Generate the xml2rfc documentation and make it part of each release.

[rjsparks]

While we will be pointing authors to authors.ietf.org for grammar instruction, we should still make it easy to find what xml2rfc produces as its own documentation when xml2rfc.tools.ietf.org is taken down.

The output of xml2rfc --doc --html should be put in the release, and maybe made easily viewable using github pages.

[cabo]

True (with the GitHub pages thing), so you can look up old versions.

But why should authors.ietf.org ever say something different from the xml2rfc documentation?

I think that means that authors.ietf.org needs to point to that, or that the xml2rfc release process needs to involve copying over the documentation to authors.ietf.org.

[JayDaley]

The intent here is to separate out the grammar from the specifics of the tool and document each separately. For example the details of the xml2rfc command line switches is not for authors.ietf.org, and equally the --doc switch should not replicate what is at authors.ietf.org. Assuming we keep that separation then it makes senses for the xml2rfc documentation to be accessible both as --doc --html and on the GitHub repository. My preference is for it to be the README (identical, not a subset or superset) as that is the default page that everyone visits, and that way it says everything that people need to read, in one file.

[ajeanmahoney]

I think that means that authors.ietf.org needs to point to that, or that the xml2rfc release process needs to involve copying over the documentation to authors.ietf.org.

Longer term, perhaps a single-source solution for xml2rfc documentation could be implemented. The documentation would be broken down into smaller files (e.g., each element has a separate doc file) and included by reference rather than copy/pasted. The CLI docs include CLI switches; the vocabulary reference on authors.ietf.org doesn't.

[jrlevine]

It is quite straightforward to maintain one source file or set of source files that we can render into different versions with or without different sections.