Subject: [xml2rfc-dev] Preparing for allowing v3 submissions into the repository (was Re: 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

---

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

> 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: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: 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

---

From: Martin Thomson <[email-masked]>
Date: Mon, 11 Feb 2019 10:27:45 +1100

>From testing, whitespace is erased from this element in some tools.  Nothing specifies whitespace preservation, so that's unsurprising.  A specific element is probably best.

SVG2 provides some hints: https://www.w3.org/TR/SVG2/struct.html#DescriptionAndTitleElements

---

From: Julian Reschke <[email-masked]>
Date: Mon, 11 Feb 2019 06:35:59 +0100

> SVG2 provides some hints: https://www.w3.org/TR/SVG2/struct.html#DescriptionAndTitleElements

xml:space comes to mind.

That said, what will be more common? Plain text equivalent authored as 
part of the RFC source, or as part of the SVG source?

In the former case, it would be annoying to have it reside in the SVG, 
so my first proposal (side-by-side sibling element to SVG) would work 
better...

Best regards, Julian

---

From: Martin Thomson <[email-masked]>
Date: Mon, 11 Feb 2019 17:06:15 +1100

> part of the RFC source, or as part of the SVG source?

I tend to do ASCII art inline, but a separate file for SVG seems most likely, due to SVG tools being better at handling that.  That suggests SVG link, text fallback.  But I can equally see both being external.  If "artwork" could be either inlined or externally sourced for both types, that would be ideal.  Of course, limitations in a tool can be worked around if it comes to that.

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 11 Feb 2019 08:12:25 +0100

Hi Martin,

On 2019-02-11 07:06, Martin Thomson wrote:
> I tend to do ASCII art inline, but a separate file for SVG seems most
> likely, due to SVG tools being better at handling that.  That
> suggests SVG link, text fallback.  But I can equally see both being
> external.  If "artwork" could be either inlined or externally sourced
> for both types, that would be ideal.

That is already the plan with the proposal worked out in November, quoted
in Robert's original post, which I'm implementing.  No worries needed.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Mon, 11 Feb 2019 09:45:04 +0100

> I tend to do ASCII art inline, but a separate file for SVG seems most likely, due to SVG tools being better at handling that.  That suggests SVG link, text fallback.  But I can equally see both bei…

Well, we can always externalize everything using xi:include...

---

From: Julian Reschke <[email-masked]>
Date: Mon, 11 Feb 2019 09:49:09 +0100

> in Robert's original post, which I'm implementing.  No worries needed.

Once again: can we please consider something simpler? The proposal IMHO 
complicates the grammar in a way that is not needed.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 11 Feb 2019 12:04:23 +0100

>> in Robert's original post, which I'm implementing.  No worries needed.

FWIW, if you are referring to the mail dated Feb 7, I have no idea which 
of the solutions discussed in the thread he was responding to is the one 
you have chosen.

> I think the simplest possible fix is something like:

Expanding on that a bit...:

This change would only affect code pieces that actually are about the 
alternative text representation. Everything else would remain unaffected.

The other proposals that I have seen do a much more intrusive change to 
the grammar, affecting how <artwork> is nested etc. Please reconsider this.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 11 Feb 2019 12:21:45 +0100

> complicates the grammar in a way that is not needed.

I'm working on what was agreed on in November:

<artgroup>
  <artwork>
  </artwork>
  <artwork>
  </artwork>
</artgroup>

> I think the simplest possible fix is something like:

I don't see how it would be simpler.  The only I see with this is that it
reopens the discussion that ended in an acceptable solution in November.

Regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Mon, 11 Feb 2019 13:19:10 +0100

> I'm working on what was agreed on in November:

How does a processor decide which of the enclosed artwork elements to 
render? What's the algorithm?

> reopens the discussion that ended in an acceptable solution in November.

I just explained why it's simpler, didn't I?

<artgroup> requires changes all over the place as it fundamentally 
changes the grammar. For instance, it creates new issues with 
referenceability: what if prose has an <xref> to an <artwork> element 
which will not actually be output by the renderer (such as the plain 
text variant in HTML, or the SVG variant in plain text?).

Yes, questions like this can be solved, but they need to, and I just 
don't see why we need this complexity if a much simpler approach is 
available.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Tue, 12 Feb 2019 06:37:30 +0100

> don't see why we need this complexity if a much simpler approach is 

Another one: will the insertion of the artwork element affect numbering 
of artwork elements, thus affecting the supposed-to-be-stable anchors in 
HTML output?

Best regards, Julian

---

From: Jim Schaad <[email-masked]>
Date: Wed, 20 Feb 2019 15:55:49 -0800

> From: xml2rfc-dev <[email-masked]> On Behalf Of Julian
> Reschke
> Sent: Monday, February 11, 2019 4:19 AM
> To: Henrik Levkowetz <[email-masked]>; Martin Thomson
> <[email-masked]>; [email-masked]
> Subject: Re: [xml2rfc-dev] [rfc-i] Preparing for allowing v3 submissions
into
> the repository (was Re: Alternate artwork vocabulary and post preptool)
> 
> >>>>> That said, what will be more common? Plain text equivalent
> >>>>> authored as part of the RFC source, or as part of the SVG source?
> >>>>
> >>>> I tend to do ASCII art inline, but a separate file for SVG seems
> >>>> most likely, due to SVG tools being better at handling that.  That
> >>>> external.  If "artwork" could be either inlined or externally
> >>>> sourced for both types, that would be ideal.
> >>>
> >>> That is already the plan with the proposal worked out in November,
> >>> quoted in Robert's original post, which I'm implementing.  No worries
> needed.
> >>
> >> Once again: can we please consider something simpler? The proposal
> >> IMHO complicates the grammar in a way that is not needed.
> >
> > I don't see how it would be simpler.  The only I see with this is that
> > it reopens the discussion that ended in an acceptable solution in
> November.
> 
> <artgroup> requires changes all over the place as it fundamentally changes
> the grammar. For instance, it creates new issues with
which
> will not actually be output by the renderer (such as the plain text
variant in
> HTML, or the SVG variant in plain text?).
> 
> Yes, questions like this can be solved, but they need to, and I just don't
see
> why we need this complexity if a much simpler approach is available.

I think that easier is sometimes in the eye of the beholder.   I would not
like to see <text-equivalent> here because that would indicate something
completely different for me.  

One the questions that I raised as part of the original discussions was the
question of are there potentially going to be other formats that need to be
inserted, in which case the more uniform the better.  One possible format
that I was thinking about at the time was a more friendly version for
someone who was blind which was an actual text description of the picture
rather than something which is ASCII art.  This would be something along the
lines of:

This is a protocol flow diagram.  There are three vertical lines from left
to right for the 'client', the 'authorization server (AS)' and the 'resource
server (RS)'.  The first horizontal line gores from 'client' to 'RS' and has
the comment 'client asks to get resource foo'.   And so forth.

Having to add a new element to this object in the RNG every time something
is added seems to be potentially more work in the future and thus maybe even
worse than adding the extra semantics now.

Jim