Re: [netmod] Comments on draft-lhotka-netmod-yang-markup-00

[William Lupton <[e-mail]>]

Lada, Rob, all,

I would support use of markdown, with the principle that descriptions (etc) should remain readable as plain text. Indeed many of the published NETMOD YANG modules have descriptions that look as though they would already render quite well if regarded as markdown (blank lines as paragraph separators, bulleted and numbered lists etc).

Note that GitHub have recently published https://githubengineering.com/a-formal-spec-for-github-markdown, which might be worth looking at or even adopting? From a quick perusal, it doesn’t seem to include any GH specifics (e.g for referencing issues or pull requests), which actually surprised me a little.

Maybe this goes too far, but I would also consider conventions allowing validation of references to enums, bits, nodes etc within descriptions. Obviously this is potentially a slippery slope and potentially (if additional markup is needed) a threat to readability, but also a potential gain (can be validated and so increases quality, can become hyperlinks when rendered, etc).

William

PS, We support this sort of thing in TR-069 data model description strings. Showing our age, the markup is mediawiki-like. For example:
* If the ACS sets the value of this parameter to {{enum|Requested}}, the CPE MUST initiate the corresponding diagnostic test. When writing, the only allowed values are {{enum|Requested}} and {{enum|Canceled}}…
* Identifier of the class of product for which the serial number applies.  That is, for a given manufacturer, this  parameter is used to identify the product or class of product over which the {{param|SerialNumber}} parameter is unique.

> On 17 Mar 2017, at 12:55, Ladislav Lhotka <[e-mail]> wrote:
> 
> Hi Rob,
> 
> thank you for reading the draft.
> 
>> On 17 Mar 2017, at 13:30, Robert Wilton <[e-mail]> 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 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".
> 
>> 
>> 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.
> 
>> 
>> 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, Lada
> 
>> 
>> Thanks,
>> Rob