Re: [netmod] [Tools-discuss] reflow of YANG descriptions, and general YANG format annoyances

[Carsten Bormann]

On 2020-11-11, at 19:54, Kent Watsen  wrote:
> 
> I don’t understand the "extraction code should not be needed any more” 
> comment, but know that Shepherds and, to a lesser extent, Copy Editors, rely 
> on being able to extract the YANG modules and/or instance examples from the 
> `xml2rfc` XML files.

Once you have the XML for the RFC:
See https://tools.ietf.org/html/rfc8152#page-7
for the right way to do this.

Grüße, Carsten

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

Re: [netmod] [Tools-discuss] reflow of YANG descriptions, and general YANG format annoyances

[Kent Watsen]

As a contributor:

I don’t like the YIN format, but Lada makes some good points below.

I don’t understand the "extraction code should not be needed any more” comment, 
but know that Shepherds and, to a lesser extent, Copy Editors, rely on being 
able to extract the YANG modules and/or instance examples from the `xml2rfc` 
XML files.

K.


> On Nov 11, 2020, at 8:52 AM, Ladislav Lhotka  wrote:
> 
> tom petch  writes:
> 
>> 
>> 
>> In the category of general annoyance, rather than the points above, the IETF 
>> has abolished the page number.  Look at recent RFC and pagination has 
>> vanished.  The justification is that RFC are now available in different 
>> format and that page numbers are not consistent across the format so they 
>> must be eliminated.
>> 
>> This came up on RFC Interest and I asked how to reference a piece of text 
>> and was told that you include lots of section numbers.  I asked about 
>> 50-page YANG modules with no sections but this is a requirement that has 
>> escaped the tool-makers.  One suggestion was to include lots of numbered 
>> sub-headings, another to include separate sourcecode elements with an anchor 
>> for each.
> 
> I share your concerns, but these developments are hard to avoid - people want 
> to read the documents on the small screens of their phones, and a fixed 
> format isn't well suited for that.
> 
>> One passing comment was that with v3 xml the extraction code should not be 
>> needed any more.  I do not understand but expect that there will be 
>> interesting times.
> 
> I don't know what the plan is, but in the recent survey on IETF authoring 
> tools, I suggested the option of including YANG modules in xml2rfc sources as 
> foreign-namespace blocks in the YIN format. This could solve most of these 
> issues and, in particular, allow for safely reflowing text in descriptions 
> etc. along with the rest of the RFC.
> 
> Regarding markup inside description/contact/reference/error-message, I think 
> XML is in fact still the best option. Light-weight choices such as markdown 
> are too brittle for these purposes.
> 
> Lada

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

Re: [netmod] [Tools-discuss] reflow of YANG descriptions, and general YANG format annoyances

[Ladislav Lhotka]

tom petch  writes:

>
> 
> In the category of general annoyance, rather than the points above, the IETF 
> has abolished the page number.  Look at recent RFC and pagination has 
> vanished.  The justification is that RFC are now available in different 
> format and that page numbers are not consistent across the format so they 
> must be eliminated.
>
> This came up on RFC Interest and I asked how to reference a piece of text and 
> was told that you include lots of section numbers.  I asked about 50-page 
> YANG modules with no sections but this is a requirement that has escaped the 
> tool-makers.  One suggestion was to include lots of numbered sub-headings, 
> another to include separate sourcecode elements with an anchor for each.

I share your concerns, but these developments are hard to avoid - people want 
to read the documents on the small screens of their phones, and a fixed format 
isn't well suited for that.

> One passing comment was that with v3 xml the extraction code should not be 
> needed any more.  I do not understand but expect that there will be 
> interesting times.

I don't know what the plan is, but in the recent survey on IETF authoring 
tools, I suggested the option of including YANG modules in xml2rfc sources as 
foreign-namespace blocks in the YIN format. This could solve most of these 
issues and, in particular, allow for safely reflowing text in descriptions etc. 
along with the rest of the RFC.

Regarding markup inside description/contact/reference/error-message, I think 
XML is in fact still the best option. Light-weight choices such as markdown are 
too brittle for these purposes.

Lada

>
> Tom Petch
>
> William
>
> On Sat, 7 Nov 2020 at 05:07, Carsten Bormann 
> mailto:c...@tzi.org>> wrote:
> On 2020-11-07, at 01:06, Michael Richardson 
> mailto:mcr%2bi...@sandelman.ca>> wrote:
>>
>> M-q reflowed a paragraph, but made it too long with 76 columns wide.
>
> Is your .emacs setting fill-column to a non-standard value?
>
> C-x f 69 RET
>
> or put
>
> // -*- fill-column: 69 -*-
>
> into the first line of your YANG file (in a comment)
> or better
>
> (add-hook 'yang-mode-hook
>   '(lambda () (set-fill-column 69)))
>
> in your .emacs.
>
> Grüße, Carsten
>
> ___
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod
>
> ___
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod

-- 
Ladislav Lhotka 
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

Re: [netmod] [Tools-discuss] reflow of YANG descriptions, and general YANG format annoyances

[tom petch]

From: netmod  on behalf of William Lupton 

Sent: 09 November 2020 09:38
To: NetMod WG
Cc: tools-disc...@ietf.org
Subject: Re: [netmod] [Tools-discuss] reflow of YANG descriptions, and general 
YANG format annoyances

I ensured that I have the latest version of the Emacs YANG mode, and find that 
M-q works well to wrap description strings, but...

  1.  Should I expect intelligent behaviour of RET and TAB when within a 
description (or other) string? I find that (in this context) RET positions the 
cursor at the start of the line, and TAB does nothing. Ideally RET might 
position the cursor at the indentation point of the previous line, or one 
character past the opening quote if this was the first line.
  2.  Wrapping (quite reasonably) can't handle cases where the author didn't in 
fact intend line breaks to be inserted. The most common cases are probably (a) 
not using a blank line as a paragraph break, (b) text was further indented 
(which often implies literal text), or (c) text started with * (or -, ...) and 
was to be interpreted as a list item.

I don't believe that RFCs 7950 and 8407 say anything about paragraph 
formatting, but most NETMOD YANG does seem to adhere to the convention that 
paragraphs should be separated by blank lines. Perhaps this could be made into 
a stronger convention?

As for the other cases (further indentation -> literal, and */- mean list 
items), of course this is getting back to the markdown discussion. I believe 
that when this has come up before the discussion has died for want of clear 
standards. However I do believe that it would be very useful to define some 
layout conventions (or rules) that allow automated reflow and other formatting, 
and personally I would take it further than just the three points that I have 
mentioned! It doesn't have to be called 'markdown'...


In the category of general annoyance, rather than the points above, the IETF 
has abolished the page number.  Look at recent RFC and pagination has vanished. 
 The justification is that RFC are now available in different format and that 
page numbers are not consistent across the format so they must be eliminated.

This came up on RFC Interest and I asked how to reference a piece of text and 
was told that you include lots of section numbers.  I asked about 50-page YANG 
modules with no sections but this is a requirement that has escaped the 
tool-makers.  One suggestion was to include lots of numbered sub-headings, 
another to include separate sourcecode elements with an anchor for each.
One passing comment was that with v3 xml the extraction code should not be 
needed any more.  I do not understand but expect that there will be interesting 
times.

Tom Petch

William

On Sat, 7 Nov 2020 at 05:07, Carsten Bormann 
mailto:c...@tzi.org>> wrote:
On 2020-11-07, at 01:06, Michael Richardson 
mailto:mcr%2bi...@sandelman.ca>> wrote:
>
> M-q reflowed a paragraph, but made it too long with 76 columns wide.

Is your .emacs setting fill-column to a non-standard value?

C-x f 69 RET

or put

// -*- fill-column: 69 -*-

into the first line of your YANG file (in a comment)
or better

(add-hook 'yang-mode-hook
  '(lambda () (set-fill-column 69)))

in your .emacs.

Grüße, Carsten

___
netmod mailing list
netmod@ietf.org<mailto:netmod@ietf.org>
https://www.ietf.org/mailman/listinfo/netmod

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

Re: [netmod] [Tools-discuss] reflow of YANG descriptions, and general YANG format annoyances

[William Lupton]

I ensured that I have the latest version of the Emacs YANG mode, and find
that M-q works well to wrap description strings, but...

   1. Should I expect intelligent behaviour of RET and TAB when within a
   description (or other) string? I find that (in this context) RET positions
   the cursor at the start of the line, and TAB does nothing. Ideally RET
   might position the cursor at the indentation point of the previous line, or
   one character past the opening quote if this was the first line.
   2. Wrapping (quite reasonably) can't handle cases where the author
   didn't in fact intend line breaks to be inserted. The most common cases are
   probably (a) not using a blank line as a paragraph break, (b) text was
   further indented (which often implies literal text), or (c) text started
   with * (or -, ...) and was to be interpreted as a list item.

I don't believe that RFCs 7950 and 8407 say anything about paragraph
formatting, but most NETMOD YANG does seem to adhere to the convention that
paragraphs should be separated by blank lines. Perhaps this could be made
into a stronger convention?

As for the other cases (further indentation -> literal, and */- mean list
items), of course this is getting back to the markdown discussion. I
believe that when this has come up before the discussion has died for want
of clear standards. However I do believe that it would be very useful to
define some layout conventions (or rules) that allow automated reflow and
other formatting, and personally I would take it further than just the
three points that I have mentioned! It doesn't have to be called
'markdown'...

William

On Sat, 7 Nov 2020 at 05:07, Carsten Bormann  wrote:

> On 2020-11-07, at 01:06, Michael Richardson  wrote:
> >
> > M-q reflowed a paragraph, but made it too long with 76 columns wide.
>
> Is your .emacs setting fill-column to a non-standard value?
>
> C-x f 69 RET
>
> or put
>
> // -*- fill-column: 69 -*-
>
> into the first line of your YANG file (in a comment)
> or better
>
> (add-hook 'yang-mode-hook
>   '(lambda () (set-fill-column 69)))
>
> in your .emacs.
>
> Grüße, Carsten
>
> ___
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod
>
___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

Re: [netmod] [Tools-discuss] reflow of YANG descriptions, and general YANG format annoyances

[Carsten Bormann]

On 2020-11-07, at 01:06, Michael Richardson  wrote:
> 
> M-q reflowed a paragraph, but made it too long with 76 columns wide.

Is your .emacs setting fill-column to a non-standard value?

C-x f 69 RET

or put

// -*- fill-column: 69 -*-

into the first line of your YANG file (in a comment)
or better

(add-hook 'yang-mode-hook
  '(lambda () (set-fill-column 69)))

in your .emacs.

Grüße, Carsten

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

Re: [netmod] [Tools-discuss] reflow of YANG descriptions, and general YANG format annoyances

[Michael Richardson]

Carsten Bormann  wrote:
> On 2020-11-06, at 22:24, Michael Richardson  wrote:
>>
>> In one of my drafts, I guess some minor wording tweaks in one draft 
leads to
>> some lines exceeding 72 characters (by one). Argh. Change from C-mode to
>> text-mode. reflow.

> https://www.emacswiki.org/emacs/yang-mode.el
> https://www.emacswiki.org/emacs/download/yang-mode.el

Yes, turns out I already have used this, but forgot I had it.
I don't see anything that helps.
M-q reflowed a paragraph, but made it too long with 76 columns wide.

And that still doesn't help get the references in the description right.

--
Michael Richardson. o O ( IPv6 IøT consulting )
   Sandelman Software Works Inc, Ottawa and Worldwide






signature.asc
Description: PGP signature
___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

Re: [netmod] [Tools-discuss] reflow of YANG descriptions, and general YANG format annoyances

[Carsten Bormann]

On 2020-11-06, at 22:24, Michael Richardson  wrote:
>
> In one of my drafts, I guess some minor wording tweaks in one draft leads to
> some lines exceeding 72 characters (by one). Argh. Change from C-mode to
> text-mode. reflow.

https://www.emacswiki.org/emacs/yang-mode.el
https://www.emacswiki.org/emacs/download/yang-mode.el

Grüße, Carsten



signature.asc
Description: Message signed with OpenPGP
___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod