> 13. 10. 2025 v 16:30, Kent Watsen <[email protected]>: > > [top-posting, to everyone's comments so far] > > I find that the ASCII-armor CODE BEGINS/CODE ENDS is an undesirable relic > from days before XML-based RFCs. Now that RFCs are XML-native, better > constructs are possible. I do not think that extracting from Text-formatted > RFCs is necessary. Being able to extract from just XML is fine. Therefore I > do NOT support adding support for code-tags for examples.
Absolutely. It would be great to extend xml2rfc with a new element serving this purpose (the <code> element of xml2rfc v3 is somewhat unfortunately already used for postal code). > > Please note this (somewhat abandoned) project: https://pypi.org/project/xiax. > The source code is on GitHub here: https://github.com/kwatsen/xiax. The > idea was 1) to replace a whole bunch of shell-scripts I use to build > XML-documents to upload to Datatracker and 2) make it possible for any > downstream consumer (shepherd, AD, IESG, RFC Editor, etc) to run a command > that would quickly validate all the YANG and examples contained in the > document. I abandoned the effort because (as I think Andy wrote) sometime > the validation context is much more than what is contained in the document, > e.g., many of the client-server drafts assume a context defined in the > truststore and keystore RFCs. Ultimately, after significant effort, I > figured it was not a problem I wanted to invest more time trying to solve. > That said, it does seem to be the focus of the Onions WG, so maybe it can be > resurrected or used for inspiration? Pro-tip: xiax stores a whole bunch of > metadata/files into a secret XML-comment block (##xiax-block-v1:), which I > discovered is not stripped by Datatracker during the submission process. > > As Lada mentioned here, Yangson has already the ability to accumulate/report > coverage statistics. The goal, or course, is that no node in the tree > reports zero (0) hits after all validation-tests have run. If all nodes have > hits, then 100% coverage has been achieved. Ideally, RFCs would have 100% > test coverage: not only showing that the YANG is good, but also that the > examples in the document are good. Unfortunately, this entails documents > needing complete examples, not example-snippets... Both complete examples and snippets/sketches are useful. It should suffice to be able to distinguish them in a machine-readable form, and validate only the former. In my YANG Doctors reviews I pay close attention to examples and try to validate them. Examples are extremely helpful but a broken example is actually worse than no example at all. Lada > > Kent // contributor > > _______________________________________________ > netmod mailing list -- [email protected] > To unsubscribe send an email to [email protected] -- Ladislav Lhotka PGP Key ID: 0xB8F92B08A9F76C67 _______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
