Subject: [rfc-i] Preparing for allowing v3 submissions into the repository (was Re: [xml2rfc-dev] Alternate artwork vocabulary and post preptool)

From: Robert Sparks <[email-masked]>
Date: Thu, 7 Feb 2019 14:07:50 -0600

The change proposed in this thread (to allow the preptool to incorporate 
SVG from external files as artwork rather than a data URI) seems right, 
and important.

The IESG is ready to allow v3 submissions into the repository as soon as 
the tooling is ready. The tooling is very close. As noted in the thread, 
our goal is to have the submission tool accept a standalone file (rather 
than solve how to allow submission of multiple components.)

I'm asking that this change be made to the toolchain.

RjS

On 11/20/18 7:10 AM, Andrew G. Malis wrote:
> Henrik,
>
> That makes sense, thanks!
>
> Cheers,
> Andy
>
>
> On Mon, Nov 19, 2018 at 5:56 PM Henrik Levkowetz <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>
>     On 2018-11-19 22:50, Jim Schaad wrote:
>     > The answer is yes. But we haven’t worked out what the mechanism is
>     > going to be yet. Another possibility is that something like the
>     > current –exp option will be added to create a single file from
>     > multiple files.
>
>     The new --prep switch does that (and also a lot of normalization).
>
>     So even if we don't add alternative upload options, running
>     xml2rfc --prep
>     on an xml file will result in a complete standalone uploadable xml
>     file.
>
>
>             Henrik
>
>
>     >
>     >
>     > Jim
>     >
>     >
>     >
>     >
>     >
>     > From: Andrew G. Malis <[email-masked]
>     <mailto:[email-masked]>>
>     > Sent: Monday, November 19, 2018 12:27 PM
>     > To: Henrik Levkowetz <[email-masked]
>     <mailto:[email-masked]>>
>     > Cc: [email-masked] <mailto:[email-masked]>;
>     [email-masked] <mailto:[email-masked]>
>     > Subject: Re: [xml2rfc-dev] Alternate artwork vocabulary and post
>     preptool
>     >
>     >
>     >
>     > Henrik et al,
>     >
>     >
>     >
>     > Given that we're going to have multiple source files for a draft
>     or RFC (in the example in this email, there would be three files,
>     the draft/rfc xml, plus tcp-header.svg and tcp-header.txt), will
>     there be a mechanism for uploading multiple source files? Or will
>     we be zipping them first into an archive?
>     >
>     >
>     >
>     > Just curious.
>     >
>     >
>     >
>     > Thanks,
>     >
>     > Andy
>     >
>     >
>     >
>     >
>     >
>     > On Mon, Nov 19, 2018 at 1:47 PM Henrik Levkowetz
>     <[email-masked] <mailto:[email-masked]>
>     <mailto:[email-masked] <mailto:[email-masked]>> > wrote:
>     >
>     >
>     > On 2018-11-19 18:53, Jim Schaad wrote:
>     >>> -----Original Message-----
>     >>> From: Henrik Levkowetz <[email-masked]
>     <mailto:[email-masked]> <mailto:[email-masked]
>     <mailto:[email-masked]>> >
>     >>> Sent: Monday, November 19, 2018 9:32 AM
>     >>> To: Jim Schaad <[email-masked]
>     <mailto:[email-masked]> <mailto:[email-masked]
>     <mailto:[email-masked]>> >; [email-masked]
>     <mailto:[email-masked]> <mailto:[email-masked]
>     <mailto:[email-masked]>>
>     >>> Subject: Re: [xml2rfc-dev] Alternate artwork vocabulary and
>     post preptool
>     >>>
>     >>> Hi Jim,
>     >>>
>     >>> On 2018-11-19 17:58, Jim Schaad wrote:
>     >>> > I have now created a document that uses SVG and has some
>     ASCII art as
>     >>> > a backup and I do not like trying to work with the output that
>     >>> > results.  I also had problems with reading RFC 7991 and
>     getting the
>     >>> > same answer as Henrik did.
>     >>> >
>     >>> > I am not a big fan of the fact that the SVG is going to be
>     encoded
>     >>> > into a data URI and placed in the file post preptool as this
>     is going
>     >>> > to be very hard to try and figure out what the changes are
>     during
>     >>> > AUTH48.  I would also think that the RPC is going to have a
>     hard time
>     >>> > doing anything except ignore the contents of the data URI during
>     >>> > editing.  I am not even sure that I think they are going to
>     be very
>     >>> > happy with having to create and replace the data URI at the
>     point in
>     >>> > time that I decide to do a small change and update the SVG
>     which is
>     >>> embedded there.
>     >>>
>     >>> That makes sense to me.
>     >>>
>     >>> > I would propose that we do the following:
>     >>> >
>     >>> > 1. Add a new element <altArtwork> which contains the same
>     attributes
>     >>> > and content as <artwork> 2.  The it is made "illegal" to
>     have both a
>     >>> > src attribute and text content at the same time on both
>     <artwork> and
>     >>> > <altArtwork>.
>     >>> > 3.  That those places in the grammar where <artwork> occurs
>     it be
>     >>> > replaced with  (artwork, altArtwork+).
>     >>> >
>     >>> > I am not sure if that is legal grammar or not.  The intent
>     is to say
>     >>> > that an altArtwork element can only directly follow from an
>     artwork
>     >>> > element (or an altArtwork element).
>     >>> >
>     >>> > This would result in:
>     >>> >
>     >>> > <figure>
>     >>> >    <name> Packet Layout Diagram</name>
>     >>> >    <artwork src="tcp-header.svg" type="svg"/>
>     >>> >    <altArtwork src="tcp-header.txt" type="ascii-art"/> </figure>
>     >>>
>     >>> I think this would make it valid to have only <altArtwork>,
>     which seems a bit
>     >>> odd -- and how would you distinguish the case where you would
>     want two
>     >>> successive <artwork> elements rendered?
>     >>
>     >> The intent of my grammar was to say that altArtwork could ONLY
>     follow
>     >> artwork. That mean that a bear altArtwork would not be legal.
>     >
>     > Aha, ok.
>     >
>     >> You could still do (artwork, altArtwork, artwork) which would
>     be two
>     >> artworks in a row with the first one having an alternate but
>     not the
>     >> second one.
>     >
>     > Understood.
>     >
>     >>>
>     >>> I wonder if it could be an alternative to instead let artwork
>     either contain text
>     >>> (the compatibility version) or a set of alternative enclosed
>     artwork elements,
>     >>> where each would need to have the type attribute set, and
>     could only hold
>     >>> content of that type.  A formatter could then pick the
>     alternative with the best
>     >>> type for its output format:
>     >>>
>     >>> <figure>
>     >>>   <name> Packet Layout Diagram</name>
>     >>>   <artwork>
>     >>>     <artwork src="tcp-header.svg" type="svg"/>
>     >>>     <artwork src="tcp-header.txt" type="ascii-art"/>
>     >>>   </artwork>
>     >>> </figure>
>     >>
>     >
>     >> I have no problems with this, but worry about the turtles all
>     the way
>     >> down case that this would allow. I had thought about
>     introducing a an
>     >> element that could hold multiple artwork but decided that the way I
>     >> outlined would be fewer changes. If the container would called
>     >> something like artGroup then I would have no problems here.
>     >
>     > Ack.  Or maybe <artgroup> to match <referencegroup>?
>     >
>     >         Henrik
>     >
>     >>>
>     >>> That would make the case of how to handle multiple successive
>     <artwork> in a
>     >>> figure or in text unambiguous, and would avoid the extra
>     <altArtwork>
>     >>> element.
>     >>
>     >> Yeah - but turtles all the way down.
>     >>
>     >> Jim
>     >>
>     >>
>     >>>
>     >>> > This would still allow for a data URI to be used in the original
>     >>> > source file, although why somebody would is unclear.  But
>     preptool
>     >>> > would move it from the src attribute to content of the
>     artwork (or altArtwork)
>     >>> element.
>     >>> > This will be both easier to edit and easier to review for
>     differences
>     >>> > during AUTH48.
>     >>>
>     >>> Ack.  I like it (but would prefer to avoid the parallel
>     <altArtwork> element
>     >>> without any enclosing (grouping) element).
>     >>>
>     >>>
>     >>>
>     >>> Best,
>     >>>
>     >>>      Henrik
>     >>
>     >>
>     >>
>     >
>     > _______________________________________________
>     > xml2rfc-dev mailing list
>     > [email-masked] <mailto:[email-masked]>
>     <mailto:[email-masked] <mailto:[email-masked]>>
>     > https://www.ietf.org/mailman/listinfo/xml2rfc-dev
>     >
>     >
>
>
> _______________________________________________
> xml2rfc-dev mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Julian Reschke <[email-masked]>
Date: Thu, 7 Feb 2019 21:24:53 +0100

> I'm asking that this change be made to the toolchain.

Could you please clarify what you mean by "v3"?

1. The thing described in RFC 7991?

2. The thing described in draft-iab-rfc7991bis-01?

3. The vocabulary that happens to be implemented by the current version 
of xml2rfc?

Best regards, Julian

---

From: Robert Sparks <[email-masked]>
Date: Thu, 7 Feb 2019 14:33:17 -0600

On 2/7/19 2:24 PM, Julian Reschke wrote:
>> The change proposed in this thread (to allow the preptool to 
>> incorporate SVG from external files as artwork rather than a data 
>> URI) seems right, and important.
>>
>> The IESG is ready to allow v3 submissions into the repository as soon 
>> as the tooling is ready. The tooling is very close. As noted in the 
>> thread, our goal is to have the submission tool accept a standalone 
>> file (rather than solve how to allow submission of multiple components.)
>>
> 3. The vocabulary that happens to be implemented by the current 
> version of xml2rfc?

Practically, right now, I mean 3.

I do remember that we need to reconcile as implemented with what's in 
the bis draft, but that's not what this message is about.

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 7 Feb 2019 21:37:15 +0100

Hi Robert,

> I'm asking that this change be made to the toolchain.

Ok, I'll coordinate with Jim to make sure to support his original use
case, and make a tentative implementation, using the <artgroup> idea we
landed on in the original thread.  I'll provide the details of that in my
implementation notes draft, as part of the release notes of the release
where they appear, and in a separate message to the lists this message
goes to.  We can then adjust and iterate.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Thu, 7 Feb 2019 21:38:19 +0100

On 07.02.2019 21:33, Robert Sparks wrote:
> ...

a) It would be good to know that the actual plan to reconcile things is.

b) As far as I understand, until we have an answer to a), "v3" is a 
moving (and not completely documented) target. As such, accepting 
submissions seems to be premature, unless there's a clarification about 
what it would mean for a submitted document becoming broken after a 
future change in "v3".

Best regards, Julian

---

From: Martin Thomson <[email-masked]>
Date: Fri, 08 Feb 2019 10:03:43 +1100

Hi Robert,

What is the status of inline SVG?

For the purposes of authoring, a separate file is great.  The preptool might inline the file to ensure that there is just one file to manage.

A data: URI is the worst possible option from a usability perspective.  It's also less efficient.

---

From: Julian Reschke <[email-masked]>
Date: Fri, 8 Feb 2019 06:22:24 +0100

<https://greenbytes.de/tech/webdav/rfc7998.html#rfc.section.5.5.1>:

> If an <artwork> element has type='svg' and there is an "src" attribute, the data needs to be moved into the content of the <artwork> element.
> 
>     If the "src" URI scheme is "data:", fill the content of the <artwork> element with that data and remove the "src" attribute.
>     If the "src" URI scheme is "file:", "http:", or "https:", fill the content of the <artwork> element with the resolved XML from the URI in the "src" attribute. If there is no "originalSrc" attribute, add an "originalSrc" attribute with the value of the URI and remove the "src" attribute.
>     If the <artwork> element has an "alt" attribute, and the SVG does not have a <desc> element, add the <desc> element with the contents of the "alt" attribute.

So yes, per spec, the content would be in-lined as-is, not moved into a 
"data URI".

(there are some issue with the text above because it doesn't really talk 
about relative references which would be most common, but the intent is 
pretty clear)

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 8 Feb 2019 07:50:55 +0100

Hi Martin,

On 2019-02-08 00:03, Martin Thomson wrote:
> For the purposes of authoring, a separate file is great. The preptool
> might inline the file to ensure that there is just one file to
> manage.
> 

Agreed.  Which is what the described change is aimed at avoiding.  It would
in all cases let the preptool inline the SVG, instead of having to stash it
in a data: URI when there is also ascii-art fallback content.

The original discussion on xml2rfc-dev has more details.

Best,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Fri, 8 Feb 2019 09:42:58 +0100

> The original discussion on xml2rfc-dev has more details.

Ah, that makes a lot of sense.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 9 Feb 2019 11:19:49 +0100

> goes to.  We can then adjust and iterate.

Hm.

It's a bit unfortunate to complicate the grammar that much for this 
case. I don't believe we need that.

Why don't we simply do something like

<artwork>
   <text-equivalent>

   </text-equivalent>
   <svg:svg>
     ...
   </svg:svg>
<artwork>

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 9 Feb 2019 11:30:56 +0100

> Why don't we simply do something like

Or even:

<artwork>
   <svg:svg>
     <svg:desc>
text equivalent
     </svg:desc>
     ...
   </svg:svg>
<artwork>

See 
<https://www.w3.org/TR/SVGTiny12/struct.html#TitleAndDescriptionElements>.

Best regards, Julian