Subject: [xml2rfc-dev] <artset> feedback

From: Julian Reschke <[email-masked]>
Date: Thu, 9 May 2019 13:24:59 +0200

Hi there,

see below for some feedback on <artset>, as currently described in 
<https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation-notes-08#section-3.1.1>.

I have worked on an implementation in rfc2629.xslt (which should be 
fairly complete), and have my own set of tests at 
<https://greenbytes.de/tech/webdav/rfc2629xslt/v3test.xml#artset>. So 
please read this as implementer's *practical* feedback.

In general I found this change to be very disruptive, because it affects 
all code that deals with <artwork>, and everything related to it 
(numbering, references, etc). A simpler approach (as proposed back then) 
IMHO would be far better.

That said, here are the details:

1) The grammar allows <artset> to be empty

This makes things really hard. How is an empty <artset> element expected 
to be handled? Does it contribute to the counting of paragraphs? Can it 
be target of an <xref>? These things of course could be defined, but it 
would be much simpler to require at least one <artwork> child element-

2) anchor propagation and <xref>

"The first anchor on an <artwork> element within an <artset> element 
will be promoted to the <artset> element if it has none; apart from 
that, anchors on <artwork> elements within an <artset> element will be 
removed by the preptool."

I understand that this is supposed to make the author's life easier - an 
existing <artwork> element can be moved into a new <artset> container 
without modification.

However, it causes lots of edge cases, such as: what happens if I <xref> 
an <artwork> element that does not appear in the rendered output? I 
*assume* the intention is to say that the anchor propagation applies (1) 
not only at the preptool stage, and (2) applies *both* to the <artwork> 
elements and all <xref>s referencing them - but the spec would need to 
say way more about that.

3) Invisible content

Having multiple <artwork> alternatives can lead to content being present 
in the canonical XML, but not to appear in the rendered output. I can 
see that this is a problem with textual fallback content already, but 
allowing any number of altenative <artwork> elements in the canonical 
XML makes this a much more serious problem.

4) Processing model

"This would let the renderer pick the most appropriate <artwork> 
instance for its format from the alternatives present within an <artset> 
element, based on the "type" attribute of each enclosed <artwork> 
element.If more than one <artwork> element is found within an <artset> 
element, with the same "type" attribute, the renderer could select the 
first one, or possibly choose between the alternative instances based on 
the output format and some quality of the alternative instances that 
made one more suitable than the other for that particular format, such 
as size, aspect ratio, or whatnot."

"Implementation:  Xml2rfc as of version 2.19.0 implements this, with a 
preference list when rendering to HTML and PDF of ( "svg", "binary-art", 
"ascii-art" ), while the text renderer uses the list
       ( "ascii-art", ) -- i.e., one entry only."

So there is no precise processing model, due to the fact that we can't 
predict what kind of alternative formats will come up. The description 
of the *actual* model is specific to a certain version of one 
implementation.

In addition, this depends on the "type" attribute which as per RFC 7991 
is sort of advisory only (see 
<https://greenbytes.de/tech/webdav/rfc7991.html#element.artwork.attribute.type>).

I believe it would be better (and more author friendly) to actually 
inspect the contents of the <artwork>, and decide based on that (that's 
what I'm currently doing in rfc2629.xslt).

I have spent a significant amount of time to implement this, but I'd 
still prefer to throw this all away and make a less-intrusive extension 
instead.

That being said, point 3) above really needs to be discussed in the 
context of how the canonical form and the default rendering relate to 
each other.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 9 May 2019 13:57:47 +0200

Hi Julian,

> would be much simpler to require at least one <artwork> child element-

Good point.  What would be your proposed grammar change to address this?

> elements and all <xref>s referencing them - but the spec would need to 

Ok.

> XML makes this a much more serious problem.

I don't see this -- the essential problem is the same whether the number
of alternatives are 2 or more than 2.  And that is built into the idea
that the XML should be able to provide richer content for HTML than for
text; I don't see any way around this.

> of the *actual* model is specific to a certain version of one 

The serious fussiness here comes from 

  1) not prescribing whether the first or some other <artwork> should be
     chosen when there are multiple instances with the same type.
     For this, I propose that we codify that the first is always chosen,
     or alternatively, make it an error to have more than one of each type.

  2) having implementation-specific preference lists.  We could codify this
     more strictly too.  Would the xml2rfc settings work for you here?

> what I'm currently doing in rfc2629.xslt).

We've had this discussion before, and disagree.  I maintain that an explicit
type is better than an implicit type.  An implicit type leads to _huge_
difficulties in specifying exactly how the inspection is done and how
the result is interpreted.

> context of how the canonical form and the default rendering relate to 

And that's the issue that is inherent also in the RFC 7991 schema, since it
permits 2 different artworks, only one of which will be shown in the
rendered form.  Nothing new here.  I'm fine with discussing the issue, but
don't make it out as something introduced with <artset>.

Regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Thu, 9 May 2019 14:10:45 +0200

> Good point.  What would be your proposed grammar change to address this?

       artset =
         element artset {
           attribute xml:base { text }?,
           attribute xml:lang { text }?,
           attribute anchor { xsd:ID }?,
           attribute pn { xsd:ID }?,
           artwork+
         }

(I think)

> text; I don't see any way around this.

If we just have "rich" and "text fallback", we can always capture that
in HTML too (<img alt="..."> etc). It might not be visible by default,
but it would at least be included.

>       or alternatively, make it an error to have more than one of each type.

+1 to always pick the first.

> the result is interpreted.

Let me disagree. The only case relevant for RFCs right now is SVG, and
that can be detected very easily be the processor without the presence
of a type attribute.

> don't make it out as something introduced with <artset>.

I believe it's much worse then before, thus I want to make sure people
are aware of it.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 10 May 2019 08:51:33 +0200

On 09.05.2019 14:10, Julian Reschke wrote:
> ...

(if there is a type attribute)

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 10 May 2019 10:46:56 +0200

5. Preptool behavior

So the motivation for <artset> is:

>    The way <artwork> has been specified to handle the presence of both
>    SVG artwork and text fallback (in Section 2.5 of [RFC7991]) has the
>    result that any SVG content has to be placed as a data: URL in the
>    "src" attribute when an ascii-art fallback is present.  This makes
>    the SVG effectively uneditable once the preptool has been run, even
>    if the SVG artwork was originally provided as a regular SVG XML file
>    external to the document XML file.

<https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation-notes-08#section-3.1.1>

So I was under the impression that the preptool would deal with this by
inserting <artset> elements when needed, and I was confused because the
documentation doesn't say so.

Testing with:

> <artwork type="svg" src="rect.svg">
> +-+
> | |
> +-+</artwork>

and xml2rfc --v3 however gives:

> foo.xml(225): Error: Found <artwork> with both a 'src' attribute and content.  Please use <artset> with multiple <artwork> instances instead.
> foo.xml(475): Error: When looking for the name of "     ", got: no such name

So something that was perfectly valid before is now a fatal error. Is
this intentional or something that is on the todo list?

IMHO, this input is perfectly ok (and indeed what authors would want to
use), and the preptool should rewrite that if needed.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 10 May 2019 11:16:13 +0200

Hi Julian,

> this intentional or something that is on the todo list?

"Before" meaning at which point in time?  Are you claiming this is valid v2?

> use), and the preptool should rewrite that if needed.

??  The preptool isn't in the business of converting invalid input to valid.

What you have above is invalid v2, valid according to RFC 7991, but not
valid after the introduction of <artset>.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Fri, 10 May 2019 11:19:49 +0200

> "Before" meaning at which point in time?  Are you claiming this is valid v2?

Yes. What makes you think it's not?

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 10 May 2019 11:25:23 +0200

> Yes. What makes you think it's not?

When did v2 get support for handling both a 'src' attribute and textual
content in <artwork>?

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Fri, 10 May 2019 11:38:26 +0200

> When did v2 get support for handling both a 'src' attribute and textual

For at least ten years, I'd say.

Excerpt from rfc5598.xml, dated July 2009:

>         <artwork
>         align="center"
>         alt="[ User, MHS, User Service Model ]"
>         name="Basic Internet Mail Service Model"
>         src="email-arch-fig-svcmodel.png"
>         type="image/png">
> <![CDATA[
>                                +--------+
>             ++================>|  User  |
>             ||                 +--------+
>             ||                      ^
> +--------+  ||          +--------+  .
> |  User  +==++=========>|  User  |  .
> +---+----+  ||          +--------+  .
>     .       ||               ^      .
>     .       ||   +--------+  .      .
>     .       ++==>|  User  |  .      .
>     .            +--------+  .      .
>     .                 ^      .      .
>     .                 .      .      .
>     V                 .      .      .
> +---+-----------------+------+------+---+
> |   .                 .      .      .   |
> |   .................>.      .      .   |
> |   .                        .      .   |
> |   ........................>.      .   |
> |   .                               .   |
> |   ...............................>.   |
> |                                       |
> |     Message Handling Service (MHS)    |
> +---------------------------------------+

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 10 May 2019 12:00:22 +0200

>>         src="email-arch-fig-svcmodel.png"

And what was the v2 handling of this?

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Fri, 10 May 2019 17:46:04 +0200

> And what was the v2 handling of this?

If by "v2" you refer to the spec, the answer is over here:
<https://greenbytes.de/tech/webdav/rfc7749.html#element.artwork>.

But if you refer to the v2 impl (Python-based), as opposed to the
original TCL implementation: I don't know. That RFC was produced with
the old tool. But just because the rewritten tool failed to implement
that doesn't make the syntax suddenly invalid.

Best regards, Julian

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 10 May 2019 18:05:18 +0200

Hi Julian,

> <https://greenbytes.de/tech/webdav/rfc7749.html#element.artwork>.

No, Julian.  That is not the _spec_ for v2.  That is a retroactive 
best-effort attempt at describing what v2 tools did, and very useful
as such.  If there is a _spec_ for the vocabulary before RFC 7991, it
would be RFC 2629.

> original TCL implementation: I don't know.

Ok.

> That RFC was produced with
> the old tool.

Aha?  So that's HTML from the TCL tool, not from your XSLT processor?
 
> But just because the rewritten tool failed to implement

No, it doesn't, quite right.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Fri, 10 May 2019 19:02:31 +0200

> as such.  If there is a _spec_ for the vocabulary before RFC 7991, it

No. The abstract says:

"Version 2 represents the state of the vocabulary (as implemented by
several tools and as used by the RFC Editor) around 2014."

So this is version 2 of the vocabulary (as spoken in 2014), opposed to
v1 (RFC 2629) and v3 (RFC 7991).

> Aha?  So that's HTML from the TCL tool, not from your XSLT processor?

The published PDF was generated using rfc2629toFO.xslt. The published
text was published my submitting XML to the RFC Editor, and they
presumably used the TCL processor to generate nroff.

If your question is whether the TCL version processed artwork/@src: yes,
it did (when generating HTML). Even for SVG. Try yourself.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 10 May 2019 19:17:33 +0200

> several tools and as used by the RFC Editor) around 2014."

As an analysis of the state of things, yes.  As a specification, no.

What I was attempting to say in the comment above, put in different
words, was that we've not had any _specification_ between 2629 and 7991.

> v1 (RFC 2629) and v3 (RFC 7991).

It's a retrospective analysis of the vocabulary, yes.  And as you know,
we've found discrepancies since it was published.  It's not the
specification.  It's been very useful, but please don't try to represent
it as something that it isn't.

> presumably used the TCL processor to generate nroff.

I'm asking about the HTML you pointed to.

> it did (when generating HTML). Even for SVG. Try yourself.

I don't have a TCL installation which will let me do that.  Which is why
I'm asking.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 May 2019 11:14:16 +0200

> words, was that we've not had any _specification_ between 2629 and 7991.

That doesn't make any sense. Why do you consider RFC 2629 and 7991 as
specification, but not 7749? In particular given the fact that a large
part of 7991 is a copy if 7749????

> we've found discrepancies since it was published.  It's not the

Example, please.

> it as something that it isn't.

It is exactly what I am saying. I don't say it is perfect, but the goal
was to specify the vocabulary in use (and implemented), and that's what
we did.

If this wasn't the case, why does it obsolete RFC 2629???

> I'm asking about the HTML you pointed to.

Did I point to HTML?

> I don't have a TCL installation which will let me do that.  Which is why

I can't produce an HTML version of RFC 5598 as I don't have the PNG
files. I can run the code an a simple example. See attachments.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 May 2019 11:18:27 +0200

> files. I can run the code an a simple example. See attachments.

And of course I did forgot to attach the external graphics file... :-)

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Sat, 11 May 2019 12:15:11 +0200

> part of 7991 is a copy if 7749????

I think it's a matter of an understanding of words.  A specification is
what's written before you build something, it is a controlling document.

If the software comes first, and is the controlling factor, what you write
is a description.  You can't put something into the description that
differs from what the already built software does, and then turn around
and say that the software doesn't conform.  So it's not a specification
of what the software should do, it's a description of what the software
is already doing.

If you intend to build a new instance of the software, then you can say
that the description of the old software is to be the specification of the
new instance.  Then you've elevated it to the controlling document for the
new instance.  But it's still just a description of the old instance, not
the specification for it.

>> we've found discrepancies since it was published.  It's not the

You have the errata, of course, and there are a few things I've mentioned
to you in email over the years.  I can go and dig in old emails.

Oh, I recall one; xml2rfc already had 'quote-title', but you didn't mention
that in RFC 7749; as a result, RFC 7991 introduced 'quoteTitle'.

> was to specify the vocabulary in use (and implemented), and that's what

The goal was to describe the vocabulary, and that's what you did, to some
extent.

>> I'm asking about the HTML you pointed to.

I believed you did, but I may have found that on my own.  Apologies.

> files. I can run the code an a simple example. See attachments.

Ok, so when producing HTML output, the TCL code included both the external
graphics pointed at by the "src" attribute _and_ the <artwork> text content.

(There's another discrepancy for you, by the way.)

I'll adjust the v2v3 converter to produce <artset> in the v3 output when it
comes across both "src" content and inline content in the v2 input.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 May 2019 14:26:54 +0200

> the specification for it.

So the HTTP specification is a description, not a specification?

/me shakes head

> that in RFC 7749; as a result, RFC 7991 introduced 'quoteTitle'.

As far as I recall, quote-title was introduced while 7749 was in the
works, and we consciously limited it to what was implemented when the
work started.

We did indeed look at quote-title, found that the name was inconsistent
with the remainder of the vocabulary, and picked quoteTitle instead (in
7791).

I still don't understand why you just don't fix it in your
implementation according to the spec.

> (There's another discrepancy for you, by the way.)

Good catch. So the TCL code did something weird here (also not what it
said it does in
<http://svn.tools.ietf.org/svn/tools/xml2rfc/archive/README.html#anchor10>)

> comes across both "src" content and inline content in the v2 input.

That's nice but I don't think it's sufficient.

This simply is and had been valid input, and there is no reason not to
support it in v3. Well, except to justify the introduction of <artset> :-)

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Sat, 11 May 2019 14:40:56 +0200

> So the HTTP specification is a description, not a specification?

Could you be slightly more specific?  Which document are you talking
about?  

> /me shakes head

Interesting approach to what ought to be a reasonable discussion.

> works, and we consciously limited it to what was implemented when the

So it's a description of the status quo at a particular point in time?

> implementation according to the spec.

You're asking for something that would break existing xml?

The current xml2rfc understands both, and the v2v3 converter converts
quote-title to quoteTitle; if you're asking for more, you're asking for
intentional breakage.

> That's nice but I don't think it's sufficient.

Ahh, but I think it is.  Difference of opinion, here.

> support it in v3. Well, except to justify the introduction of <artset> :-)

So there's a lot of the vocabulary that is marked deprecated.  I'll just
permit all of that in pure v3 too, then?

I understand that you don't like <artset>.  You've said so repeatedly, and
it looks as if you can't let it go.  I'm fine with you having that opinion.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 May 2019 17:05:30 +0200

> Could you be slightly more specific?  Which document are you talking

RFC 2616, for instance.

> So it's a description of the status quo at a particular point in time?

Yes. But just because something describes doesn't mean it's not a
specification (in case that's your point).

> You're asking for something that would break existing xml?

a) I did research and found just a few XML files (in AUTH48 history)
that used it.

b) Feel free to accept the other form as well (and maybe emit a
warning). Then there'll be no breakage.

> quote-title to quoteTitle; if you're asking for more, you're asking for

That's fine.

> permit all of that in pure v3 too, then?

<https://greenbytes.de/tech/webdav/rfc7991.html#rfc.section.1.3.3> says:

"Deprecated elements and attributes are legacy vocabulary from v2 that
are supported for input to v3 tools. They are likely to be removed from
those tools in the future."

So I'd say yes, they should be accepted.

> it looks as if you can't let it go.  I'm fine with you having that opinion.

Well, if you don't want to back it out, at least take my implementation
feedback seriously.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Sun, 12 May 2019 22:19:29 +0200

To the list:

After the latest discussion, and in particular this:

> /me shakes head

I'm going to black-hole postings and direct communications from Julian Reschke.

It's a pity, because I'll also be missing his factual observations of bugs
in the tools, but the emotional cost to me of discussions with Julian is
now too high.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Mon, 13 May 2019 06:47:03 +0200

> On 2019-05-11 14:26, Julian Reschke wrote:

I recommend reading this in context.

> in the tools, but the emotional cost to me of discussions with Julian is

It's indeed a pity, because with that the process of finalizing the v3
vocabulary would be entirely broken.

Best regards, Julian

---

From: Paul Hoffman <[email-masked]>
Date: Mon, 13 May 2019 07:28:15 +0000

> vocabulary would be entirely broken.

I agree with Julian. During the process of developing the v3 vocabulary, we did not black-hole postings from anyone.

--Paul Hoffman

---

From: Heather Flanagan <[email-masked]>
Date: Mon, 13 May 2019 07:48:53 -0700

> I agree with Julian. During the process of developing the v3 vocabulary, we did not black-hole postings from anyone.

I don’t like the idea of black holing, either, but when two parties start arguing past each other to the extent I’ve been observing, a cooling off period is necessary. I’m still watching for input for all parties, and expect a very engaging -bis process to start when the final implementation diff draft (draft-levkowetz-xml2rfc-v3-implementation-notes) is posted.

-Heather