On 17/03/2017 15:08, Ladislav Lhotka wrote:
On 17 Mar 2017, at 15:11, Robert Wilton <rwil...@cisco.com> wrote:
On 17/03/2017 12:55, Ladislav Lhotka wrote:
Hi Rob,
thank you for reading the draft.
On 17 Mar 2017, at 13:30, Robert Wilton <rwil...@cisco.com> wrote:
Hi Lada,
I've had a quick scan of your YANG markup extension draft and I have a few
comments:
Allowing description, and similar descriptive statements, to use something
other than text seems like it could be useful in some cases.
I'm not sure that allowing the statements to use any text-like media type is a
good idea, this could increase the burden on tool makers if each module author
chooses their own preferred format.
Instead, I think that it might be better to restrict it to a very small set of
media types, that could be extended in future. I would think that initially
just allowing plain text and one particular flavour of markdown would be a
reasonable starting point.
I agree although I am not sure that we can easily find an agreement on the particular
flavour. So maybe we can leave it open and let the "market" decide.
I think that would be a mistake. How would device/tools vendors know which
versions to spend time implementing?
I would agree to have a fixed choice in 6087bis, but there may be niche
communities or special cases that need something else, so YANG IMO shouldn't
preclude it a priori.
I think that this idea works quite well as a YANG extension, and that
would be a better path than baking it into YANG at this time.
I'm still not convinced that allowing an arbitrary encoding is a good idea.
I think that the only formats that should be allowed are those that are still
readily readable as plain text, so that tools that don't want to parse the
formatted text can still sensibly display the descriptive statements. I.e. I
don't think that it would be helpful to allow things like text/xml since it
isn't easy to read.
Sure, and the draft says:
It is RECOMMENDED to use only media types representing "lightweight"
markup that is easy to read even in the unprocessed source form, such
as "text/markdown".
I was proposing REQUIRED instead of RECOMMENDED.
I usually write my modules in the YIN format with a very restricted set of HTML
tags that are used in the text arguments:
https://gitlab.labs.nic.cz/labs/yang-tools/wikis/editing_yang#yin-schema-extensions
OK. I had assumed that nobody was using YIN ;-)
It would be useful to indicate "text/html" media type, and a YIN->YANG convertor could
translate it e.g. to "text/markdown".
Isn't that just part of the YIN conversion to YANG. I.e. by the time the
file is YANG it would be text/markdown.
Allowing this extension on particular descriptive statements may also be
helpful. It seems plausible that the vast majority of these statements in a
module might just be written in plain text with just a few of them using more
advanced formatting like markdown.
Yes, I was thinking about this. On the other hand, plain text is typically
compatible with any markup format, so this would probably be useful only if
somebody wanted to use multiple different markup formats in the same module,
which sounds crazy. But we can discuss it.
I was only thinking of a mix of some plain text descriptions and some using
markup.
Tooling may choose to format raw text differently from markup text (e.g.
converting lines into a paragraph). Also a markup processor would be extra
work, and may not warn or error on the structure of a plain text description
that doesn't conform to the markup rules.
Actually, the design philosophy behind markdown is that there is no formal
concept of validity and so processors should never complain.
But how does an implementation know what it needs to support so that it
works with all descriptions? I think that there would need to be a
based specification to be useful.
On the other hand, it is conceivable that some descriptions may use a more specialized
format. For example, we could use a media type (variant) for the top-level
"contact" statements that we include in modules, and tools could then more
easily extract this metadata.
I'm not sure ... this is just sounding like extra work/complexity, and
YANG is already pretty complex!
Thanks,
Rob
So maybe we could really permit the "text-media-type" extension anywhere and
apply some natural scoping rules.
Lada
Finally, I have a concern that if more structured formatting in the comments is
used then would that encourage model writers to produce more verbose comments,
and if so that might possibly reduce the readability of the modules. Although,
I guess ultimately one has to trust the model writers to do the right thing.
Well, this draft doesn't permit anything above what module writers can do
already now - the descriptions etc. have to be valid YANG strings as before.
The only new thing is a piece of metadata that may be helpful for some tools
but that can also be safely ignored.
Thanks,
Rob
Thanks, Lada
Thanks,
Rob
--
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67
.
--
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67
.
_______________________________________________
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod
