Subject: [xml2rfc-dev] RFC 7991 issue #21: Schema Issue, RFC 7991, In Section 2.5.5, "name" Attribute

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 1 Oct 2018 13:27:37 +0200

This captures an issue noted during implementation, also described in
https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation#section-3.1.1

Specification: https://tools.ietf.org/html/rfc7991#section-2.5.5

---

      "A filename suitable for the contents (such as for extraction to a
      local file)."

   Given the existing use of "name" on <seriesInfo>, this attribute name
   has a semantic dissonance.

   Recommendation:  Deprecate "name" for use on <artwork> and <sourcecode>,
                    and instead use "file", which for <sourcecode> will be
                    explicitly rendered, as established as best current
                    practice for YANG modules (see for instance RFC 6087
                    [RFC6087])

   Implementation:  The current version of xml2rfc uses "name".
---

Regards,
	Henrik

-- 
This issue is tracked at:
   https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/36

Discussion should take place on this list.

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 1 Oct 2018 13:36:36 +0200

Oops.  Slight tooling problem.  The subject line of the previous version
gave the wrong issue number.  (The link at the bottom of the message used
the right one).

On 2018-10-01 13:27, Henrik Levkowetz wrote:
This captures an issue noted during implementation, also described in
https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation#section-3.1.1

---

Regards,
	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Mon, 1 Oct 2018 14:10:08 +0200

On 10/1/2018 1:36 PM, Henrik Levkowetz wrote:
> ...
> ...

I would avoid making changes that aren't strictly necessary, thus keep 
the name as-is.

I also disagree with coupling the sourcecode tagging to the presence of 
a (file)name. This violates the principle of least surprise. There are 
good reasons for providing names, such as for automatic extraction 
during build time (for instance for running check scripts), which have 
absolutely nothing to do with the presentation in text or other formats.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 1 Oct 2018 14:45:18 +0200

Hi Julian,

> I would avoid making changes that aren't strictly necessary, thus keep 

I think now, before actual use of v3 starts in earnest is the only chance
we have to make changes like this.  So if the change makes sense, let's
do it, rather than live forever with something which is (even if only
slightly) less appropriate.

> absolutely nothing to do with the presentation in text or other formats.

On the coupling with sourcecode tagging, it was not my intention here
to argue for that.  FWIW, in the next release of xml2rfc the insertion
of <CODE BEGINS> will be controlled by an attribute "markers", with the
default being "false".  Expansion of "file" or "name" would occur only
for markers="true".

The "markers" attribute is of course also something we'll have to decide
on, quite apart from this issue's proposed change of "name" to "file".

Best regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Mon, 1 Oct 2018 15:07:01 +0200

> slightly) less appropriate.

Well, @name has been around for over a decade, it's not a V3 thing. If 
this was new, I'd be more likely to agree.

> on, quite apart from this issue's proposed change of "name" to "file".

Ok, then I misread that point.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 1 Oct 2018 15:27:04 +0200

Hi Julian,

> this was new, I'd be more likely to agree.

Umm?  For the specific purpose of specifying the name of a file for
extraction of artwork or sourcecode?  This is the specific case I'm
thinking of here.

Best,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Mon, 1 Oct 2018 16:10:16 +0200

> extraction of artwork or sourcecode?  This is the specific case I'm

Yes.

"A filename suitable for the contents (such as for extraction to a local 
file).

This attribute generally isn't used for document generation, but it can 
be helpful for other kinds of tools (such as automated syntax checkers, 
which work by extracting the source code)." -- 
<https://greenbytes.de/tech/webdav/rfc7749.html#element.artwork.attribute.name>

...and, previously...:

"Finally, the "artwork" element has two optional attributes: "name" and 
"type". The former is used to suggest a filename to use when storing the 
content of the "artwork" element, whilst the latter contains a 
suggestive data-typing for the content." --
<https://tools.ietf.org/html/rfc2629#section-2.3.1.3>

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 1 Oct 2018 16:23:32 +0200

Hi Julian,

> <https://tools.ietf.org/html/rfc2629#section-2.3.1.3>

Ah! Ok.  I've closed the issue.

Best regards,

	Henrik

---

From: Jim Schaad <[email-masked]>
Date: Tue, 2 Oct 2018 20:02:08 -0700

> -----Original Message-----
> From: xml2rfc-dev <[email-masked]> On Behalf Of Henrik
> Levkowetz
> Sent: Monday, October 1, 2018 4:28 AM
> To: XML Developer List <[email-masked]>
> Subject: [xml2rfc-dev] RFC 7991 issue #21: Schema Issue, RFC 7991, In Section
> 2.5.5, "name" Attribute
> 

I have no problems with keeping this as "name" rather than "file".  There is not a great deal of difference to me.

I am worried about the rendering of the "name" parameter if present.  Is this going to be conditional on the presence of the <CODE BEGINS> rendering or is it done regardless.  I would like to be able to associate file names that are not rendered to the public as I generally chose those names that make sense if you read them.  Such as "Appendix.3.2.cddl"

Jim

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 3 Oct 2018 11:56:57 +0200

Hi Jim,

On 2018-10-03 05:02, Jim Schaad wrote:
> I have no problems with keeping this as "name" rather than "file".
> There is not a great deal of difference to me.
> 
> I am worried about the rendering of the "name" parameter if present.
> Is this going to be conditional on the presence of the <CODE BEGINS>
> rendering or is it done regardless.

The next release will render <CODE BEGINS> file "Appendix.3.2.cddl" only
if a new attribute "markers" is set to "true", which is my proposed
resolution for the question of whether to render code markers or not.

> I would like to be able to
> associate file names that are not rendered to the public as I
> generally chose those names that make sense if you read them. Such as
> "Appendix.3.2.cddl"

Will the above resolution work for you, then, or do we need separate
"name" and "file" attributes, or do we need 2 separate attributes to
control rendering of code markers vs rendering of file name?

Best regards,

	Henrik

---

From: Jim Schaad <[email-masked]>
Date: Wed, 3 Oct 2018 07:55:20 -0700

> From: Henrik Levkowetz <[email-masked]>
> Sent: Wednesday, October 3, 2018 2:57 AM
> To: Jim Schaad <[email-masked]>; 'XML Developer List' <xml2rfc-
> [email-masked]>
> Subject: Re: [xml2rfc-dev] RFC 7991 issue #21: Schema Issue, RFC 7991, In
> Section 2.5.5, "name" Attribute
> 
> Hi Jim,
> 
> >> Subject: [xml2rfc-dev] RFC 7991 issue #21: Schema Issue, RFC 7991, In
> >> Section 2.5.5, "name" Attribute
> >>
> >> https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation
> >> #section-
> >> 3.1.1
> >>
> The next release will render <CODE BEGINS> file "Appendix.3.2.cddl" only if a
> new attribute "markers" is set to "true", which is my proposed resolution for
> the question of whether to render code markers or not.
> 
> Will the above resolution work for you, then, or do we need separate "name"
> and "file" attributes, or do we need 2 separate attributes to control rendering
> of code markers vs rendering of file name?

That resolution works for me.   There might be some source code people who might be surprised but I don't know how big of a problem that would be. 

Jim

---

From: Paul Hoffman <[email-masked]>
Date: Wed, 3 Oct 2018 23:10:46 +0000

On 1 Oct 2018, at 4:36, [email-masked] wrote:

> https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation#section-3.1.4
>
> ---
> New Section 2.20.4, "indent" Attribute
>
>    The deprecation of the "hangIndent" attribute on <list> leaves no
>    opportunity to control the size of the hanging indent.  In some
>    definition lists, it is desirable to have a wide indentation, in order
>    to clearly show the terms, in other cases it is more important to allow
>    for a larger text volume than the width of the terms would allow.
>
>    Recommendation:  Add an "indent" attribute on <dl> to control the size
>                     of the hanging indent.
>
>    Implementation:  The current version of xml2rfc does not support the
>                     attribute, but has all the underlying functions needed
>                     to apply such an attribute.  Internally, an indentation
>                     is calculated based on length of the <dt> text and the
>                     settings of some of the other attributes.

This could be done where the value of the "indent" attribute is always em units (from CSS).

--Paul Hoffman

---

From: Paul Hoffman <[email-masked]>
Date: Wed, 3 Oct 2018 23:13:54 +0000

On 1 Oct 2018, at 4:35, [email-masked] wrote:

> https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation#section-3.1.3
>
> Specification: https://tools.ietf.org/html/rfc7991#section-2.20
>
> ---
> In Section 2.20, <dl>
>
>    The current specification says:
>
>       "The "hanging" attribute defines whether or not the term appears on
>       the same line as the definition.  hanging="true" indicates that the
>       term is to the left of the definition, while hanging="false"
>       indicates that the term will be on a separate line."
>
>    This does not match established typographic terminology.  In typographic
>    terminology, "hanging indent" describes the case where the indentation
>    of the second and subsequent lines of a paragraph is greater than the
>    indentation of the first line.  Whether the definition in a definition
>    list starts on the first line or not has nothing to do with the presence
>    of hanging indent; our definition lists will _always_ have hanging
>    indent.
>
>    The 'hanging' attribute also describes something different from what the
>    term has been used to describe in the version 2 vocabulary.  This will
>    be confusing to users.
>
>    A more descriptive name for the attribute we're talking about would be
>    'start-definition-on-first-line', but that's unwieldy.  Maybe
>    'newline="false"' to start the definition on the first line, or
>    something like 'definition-start="first"'?
>
>    Recommendation:  Change this to a different term that is more
>                     descriptive and does not use typographically incorrect
>                     terminology.
>
>    Implementation:  The current version of xml2rfc still uses "hanging".

I like the idea of changing this to "newline" with boolean values.

--Paul Hoffman

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 8 Oct 2018 16:53:14 +0200

I propose closing this ticket with the following resolution:

In Section 2.20.2.  "hanging" Attribute:

Change "hanging" to "newline" throughout.

If there are no objections to the resolution by EOB Tuesday, I'll close the
ticket. 

Best regards,

	Henrik

On 2018-10-04 01:13, Paul Hoffman wrote:
> _______________________________________________
> xml2rfc-dev mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev
>