Subject: Re: [Gen-art] Gen-ART Early review of draft-brownlee-svg-rfc-07

From: Nevil Brownlee <[email-masked]>
Date: Mon, 29 Sep 2014 19:06:31 +1300

Hi Suresh:

Thanks very much for your review.  Responses inline ...

On 21/08/14 5:27 PM, Suresh Krishnan wrote:
> I am the assigned Gen-ART reviewer for draft-brownlee-svg-rfc-07
>
> For background on Gen-ART, please see the FAQ at
> <http://www.alvestrand.no/ietf/gen/art/gen-art-FAQ.html>.
>
>
>
> Please resolve these comments along with any other comments you may receive.
>
>
>
> Summary: This draft is on track to be published as an Informational RFC,
> but I have some suggestions that the authors may like to consider.
>
>
> * Meta comment
>
>
> It is not clear how the SVGs will be included in the RFCs? Will they be
> included as inline XML? Can you please clarify.

Getting an SVG diagram into an RFC is a matter for verson 3 of xml2rfc 
(see Paul Hoffman's "The 'XML2RFC' version 3 Vocabulary," 
draft-hoffman-xml2rfc) - I've added a note at the end of section 3 to say

       To include a diagram into an RFC, the xml2rfc (v3) tool will
       need to provide a way to include SVG drawings in Internet
       Drafts.

> * Section 1
>
>
> Last paragraph: It is not really true that diagrams in RFCs are not
> normative. e.g. The ordering of fields in a packet is specified by a
> packet format diagram and the text only describes the contents of the
> fields (and not necessarily the structure of the packet itself). Is this
> paragraph necessary?

Hmm.  I thought it was, but looking back at 'classic' RFCs like 1035
I see that you're right.  793 says that its TCP state diagram is "only a 
summary and must not be taken as the total specification."

How about changing it as follows:

OLD: they are informative, not normative.

NEW: they provide supporting detail, and should not be considered
      to be complete specifications in themselves.

> * Section 4
>
>
> Shouldn't we also be discussing the "role" attribute in the
> accessibility context?

Well caught.  I've added the 'role' SVG attribute, for all the elements
where it's allowed in SVG 1.2 Tiny.

> I also found that the Web Accessibility Initiative's ARIA primer to be a
> good introduction in addition to the SVG-ARIA reference.
> http://www.w3.org/TR/wai-aria-primer/

Added that into the last paragraph of Section 4, Accessibility.

> * Sections 5.2 and 5.3
>
>
> The meta language used in these sections (especially 5.3) is a bit
> confusing. Is the goal of such languages to also go into the
> presentation details as they do now? I think it would be more
> illustrative if the example languages are made a bit simpler. e.g. I use
> the mscgen program a lot in my day job and the language used by mscgen
> is a bit simpler and illustrates the message sequence more clearly.
>
> http://www.mcternan.me.uk/mscgen/

When I started my draft, I wasn't aware of all the diagram-drawing 
packages that are out there!  My examples in the draft are intended to 
show what I think would be 'good' diagrams.

For now I'll start collecting a list of diagram-drawing websites and 
applications; one day perhaps that list can move into the draft.

> Thanks
> Suresh

-- 
---------------------------------------------------------------------
  Nevil Brownlee                          Computer Science Department
  Phone: +64 9 373 7599 x88941             The University of Auckland
  FAX: +64 9 373 7453   Private Bag 92019, Auckland 1142, New Zealand