Kent Watsen <kent+ietf@xxxxxxxxxx> writes:
Ignas, Martin, and I met with Sandy (all CC-ed) during IETF 104
to the YANG module formatting issue described by Heather below.
The plan was to quickly add a process step (to test formatting)
into the shepherd writeup, followed later integration into
Datatracker submission checks. The goal was/is to remove this
burden from the copyeditors entirely.
It would IMO be much better to remove most of this burden from
*everybody* and do the visual formatting of YANG modules
automatically along with the rest of the RFC or I-D document. In
my own experience, it is entirely possible if YANG modules are
written in the XML syntax (YIN) using additional logical markup in
descriptions and some (scarce) processing instructions as
formatting hints. Here is an example:
https://github.com/CZ-NIC/iana-dns-zone-types/blob/master/iana-dns-class-rr-type.yinx
I have been preparing all my YANG modules this way. As a module
author, I never need, e.g., to reformat a description after a
minor edit.
In practical terms, the xml2rfc source with embedded YANG modules
could be a compound XML document in which the YANG parts live in
their own XML namespace. Another huge advantage of this approach
would be that HTML-formatted RFCs could also include
HTML-formatted YANG modules with hyperlinks, prettyprinting etc.
Lada
PS. Here is the toolchain that I use:
https://github.com/llhotka/YANG-I-D
Unfortunately, I don't see the process step added to
https://www.ietf.org/chairs/document-writeups
<https://www.ietf.org/chairs/document-writeups> yet...
To be clear, the shepherd steps are roughly:
1) pyang -f yang --keep-comments --max-line-length 69
<infile> > <outfile>
2) diff <infile> <outfile> 3) explain why any diffs are
acceptable.
Kent // NETMOD co-chair
Hola a todos, and sorry it took long for me to find this in the
thread! I can provide some information, but not hard numbers -
editors don’t use a stopwatch to determine exactly how long
each step takes, as that would both take an unfortunate amount
of time and drive us insane for very little benefit. Checking
YANG modules became quite challenging in 2018, because it was
no longer about ensuring only that the module parsed, but that
it was well formatted (per pyang) as well. The formatting part
of the process took a substantial amount of effort, as the
tools to check the YANG modules were still in development
during that time, and we found out much later that the
structure of the YANG modules as generated by the tools was not
something that had full buy-in from the community. So, the RPC
found itself working closely with the tool maintainer and the
authors to get well-formatted YANG modules, experimenting with
the updated toolset and updating procedures, training staff on
the new features of the tool and procedures, and sometimes
manually editing the automated output because the author(s)
disagreed with parts of the formatting. While the RPC will
continue to check the format of YANG modules, we have suggested
updating the YANG-related documentation for authors and we have
asked the IESG to consider how the authors can be involved
earlier in the process, as AUTH48 does not seem to be the
correct place to initiate this check (especially if the authors
are unaware that this is step is happening). I hope that
helps answer your question; let me know if you’d like to
discuss further. -Heather
--
Ladislav Lhotka Head, CZ.NIC Labs PGP Key ID: 0xB8F92B08A9F76C67
