Subject: [rfc-i] Two drafts showing the advantage of the new format

From: Phillip Hallam-Baker <[email-masked]>
Date: Wed, 16 Aug 2017 18:29:23 -0400

My tools are not yet complete, there are several bugs and glitches to iron
out. But I thought people might like to see examples of two new drafts that
I think really show why this work is so worthwhile.

Original Format:

https://www.ietf.org/internet-drafts/draft-hallambaker-mesh-recrypt-02.txt

https://www.ietf.org/internet-drafts/draft-hallambaker-mesh-confirm-01.txt

New Format:

http://prismproof.org/Documents/draft-hallambaker-mesh-recrypt.html

http://prismproof.org/Documents/draft-hallambaker-mesh-confirm.html

Major thanks to everyone who made this all possible.

The diagrams illustrating the cryptographic protocol would be simply
unreadable if attempted in ASCII art. The ability to use super and
subscripts totally matters when describing a cryptographic protocol.

My tool has only been tested on Windows so far but should run on OSX and
Linux if Mono is installed. The Git repo is here:

https://github.com/hallambaker/PHB-Build-Tools
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Adam Roach <[email-masked]>
Date: Wed, 16 Aug 2017 18:10:33 -0500

> subscripts totally matters when describing a cryptographic protocol.

Aside --

The diagrams in the new format will not allow colors. You're going to 
want to use some other mechanism to indicate what you are currently 
intending color to mean.

/a

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Wed, 16 Aug 2017 20:22:18 -0400

On Wed, Aug 16, 2017 at 7:10 PM, Adam Roach <[email-masked]> wrote:

> The diagrams in the new format will not allow colors. You're going to want
> to use some other mechanism to indicate what you are currently intending
> color to mean.
>
Perhaps we should let IETF participants see and decide for themselves?

Until you have a working toolset, all you have is suggestions.

---

From: "Paul Hoffman" <[email-masked]>
Date: Wed, 16 Aug 2017 17:30:27 -0700

On 16 Aug 2017, at 17:22, Phillip Hallam-Baker wrote:

>> want

The IETF did that during the various discussions on draft-iab-svg-rfc, 
which became RFC 7996.

> Until you have a working toolset, all you have is suggestions.

You have an RFC to work from. If you want to re-open the discussion 
based on your experience, you can certainly do so. There is an issue 
list at:
    https://github.com/rfc-format/draft-iab-svg-rfc-bis

--Paul Hoffman

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Wed, 16 Aug 2017 20:45:32 -0400

On Wed, Aug 16, 2017 at 8:30 PM, Paul Hoffman <[email-masked]> wrote:

> You have an RFC to work from. If you want to re-open the discussion based
> on your experience, you can certainly do so. There is an issue list at:

​If you really want to make things unpleasant you can always add a css
attribute

​svg
 {
    -webkit-filter: grayscale(100%); /* Safari 6.0 - 9.0 */
    filter: grayscale(100%);
}​

​Then folk who want to can drop it out in a local stylesheet.

​It is likely that there are going to be rather more challenges for using
SVG for quite some time to come.
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Adam Roach <[email-masked]>
Date: Wed, 16 Aug 2017 19:47:44 -0500

> The IETF did that during the various discussions on draft-iab-svg-rfc, 

Well, to be clear, it was established earlier than that; cf. 
<https://tools.ietf.org/html/rfc6949#section-3.2>, list item 8. This is 
some pretty long-running consensus.

/a

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Wed, 16 Aug 2017 21:07:41 -0400

On Wed, Aug 16, 2017 at 8:47 PM, Adam Roach <[email-masked]> wrote:

> On Wed, Aug 16, 2017 at 7:10 PM, Adam Roach <[email-masked]>
> <[email-masked]> wrote:
>
> <https://tools.ietf.org/html/rfc6949#section-3.2>
Design documents have always been subject to revision in the light of
implementation experience.

Let us see how long the consensus lasts when people can see the consequence.

---

From: Andrew Sullivan <[email-masked]>
Date: Wed, 16 Aug 2017 21:13:50 -0400

Note that at least one IAB member at the time thought the plan was to modify the rfcs in question in light of experience.  I believe said IAB member made this point at a plenary.  

-- 
Andrew Sullivan 
Please excuse my clumbsy thums. 

> On Aug 16, 2017, at 20:30, Paul Hoffman <[email-masked]> wrote:
> 
> The IETF did that during the various discussions on draft-iab-svg-rfc, which became RFC 7996.
> 
> You have an RFC to work from. If you want to re-open the discussion based on your experience, you can certainly do so. There is an issue list at:

---

From: Martin Thomson <[email-masked]>
Date: Thu, 17 Aug 2017 11:18:41 +1000

> Note that at least one IAB member at the time thought the plan was to modify the rfcs in question in light of experience.  I believe said IAB member made this point at a plenary.

So rather than leaning on past precent, I have to say that the
difficulty of getting colour right here exceeds the value it brings at
this point in time.  I'm not sure, but those people with trouble
distinguishing red and green would find this particular draft
challenging.
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Adam Roach <[email-masked]>
Date: Wed, 16 Aug 2017 20:20:57 -0500

> Note that at least one IAB member at the time thought the plan was to modify the rfcs in question in light of experience.  I believe said IAB member made this point at a plenary.

Sure -- my understanding of the plan is to have revised versions of all 
of the documents out now that we've had time to poke at their practical 
impact.  However, unless you've found a way to let my laser printer 
produce colors, and additionally come up with a miracle cure for the 
red-green colorblindness that impacts a non-trivial percentage of the 
general population, it's going to be hard arguing that there's 
experiential reasons to revisit this *specific* requirement.

/a

---

From: Andrew Sullivan <[email-masked]>
Date: Wed, 16 Aug 2017 21:23:31 -0400

Sure. I was just objecting to the "there's an RFC, shut up and change your stuff" message.  The reason not to use colour is because of printing and colour blind people, not because The RFC Sez. 

A

> On Aug 16, 2017, at 21:20, Adam Roach <[email-masked]> wrote:
> 
> Sure -- my understanding of the plan is to have revised versions of all of the documents out now that we've had time to poke at their practical impact.  However, unless you've found a way to let my laser printer produce colors, and additionally come up with a miracle cure for the red-green colorblindness that impacts a non-trivial percentage of the general population, it's going to be hard arguing that there's experiential reasons to revisit this *specific* requirement.
> 
> /a
>

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Wed, 16 Aug 2017 22:21:50 -0400

If people are colorblind, they are not going to know. So they are only
going to care if someone lets on. Or they don't understand the document.

If Mozilla can't afford a color printer then I will assume that paper is
also scarce.

Since the experimental stylesheet on GitHub produced white text on a white
background on the first two browsers I used, it does not appear that the
ability to print has been of significant concern. As I was merely trying to
produce a pdf, this was rather irritating.

My docs do at least print. So I am ahead of the game.

What I do resent is the unfounded claim that the documents cannot be read
by people who are colorblind. If you look, you will see that the Red and
Green buttons in confirm have 'accept' and 'reject' labels. And Bob who has
left the President's advisory doodah is not just red, he has a great big
cross through him.

The use of color in Figure 7 was an oversight. I had corrected the source
document but had not saved the new SVG version. My tool chain does not
support extraction of SVG images from Visio at the moment (it does support
PNG). The tools are only automatic up to the point of producing the HTML
and XML. I have not got round to integrating the push to the web site.

Given that people like me have had to put up with unreadable crud for
decades and nobody seems to have cared, I find the 'concern' for
accessibility rather suspicious. The W3C has been committed to
accessibility for decades with full time staff. They use color in their
documents to make them *more* accessible.

I was going to fix some bugs tonight but now I am going to add support for
PNGs instead. And I am going to enjoy it.

On Wed, Aug 16, 2017 at 9:23 PM, Andrew Sullivan <[email-masked]>
wrote:

> Sure. I was just objecting to the "there's an RFC, shut up and change your
> stuff" message.  The reason not to use colour is because of printing and
> colour blind people, not because The RFC Sez.
>
> A
>
> --
> Andrew Sullivan
> >> Note that at least one IAB member at the time thought the plan was to
> modify the rfcs in question in light of experience.  I believe said IAB
> member made this point at a plenary.
> >
> >
> impact.  However, unless you've found a way to let my laser printer produce
> colors, and additionally come up with a miracle cure for the red-green
> colorblindness that impacts a non-trivial percentage of the general
> population, it's going to be hard arguing that there's experiential reasons
> to revisit this *specific* requirement.
> >
> > /a
> >
>
>

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 16 Aug 2017 23:55:16 -0400

On 8/16/17 6:29 PM, Phillip Hallam-Baker wrote:
> My tools are not yet complete, there are several bugs and glitches to 
> iron out. But I thought people might like to see examples of two new 
> drafts that I think really show why this work is so worthwhile.
> 
> Original Format:
> 

The html renders nicely, but I do have a couple of comments:

1) The TOC is nice as long as the window is wide enough. If I narrow the 
window enough it omits the content of the TOC but leaves its heading 
sort of floating over the main text. That seems fine, but I can't find 
any way to see the content of the TOC without widening the window.

2) In the normative references of draft-hallambaker-mesh-confirm-01 
things get weird for the reference with a long tag. I would expect the 
wrapped content of the reference to align with the wrapped content of 
other references with shorter tags.

	Thanks,
	Paul

---

From: Martin Thomson <[email-masked]>
Date: Thu, 17 Aug 2017 14:30:44 +1000

On 17 August 2017 at 13:55, Paul Kyzivat <[email-masked]> wrote:
> window enough it omits the content of the TOC but leaves its heading sort of
> floating over the main text. That seems fine, but I can't find any way to
> see the content of the TOC without widening the window.

I had the same complaint, but my suggestion was rejected.

https://mailarchive.ietf.org/arch/msg/rfc-interest/KithtbhVtSR1Vl830IeSbqqYEpI

I still prefer the technique we use elsewhere, which is to have the
TOC render inline when the window is narrow.  See for example
https://martinthomson.github.io/http-replay/draft-thomson-http-replay.html

I was going to use
https://martinthomson.github.io/teapot/draft-thomson-teapot.html as an
example, but then I noticed that for some bizarre reason xml2rfc put
the TOC at the end of the document.
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Thu, 17 Aug 2017 00:37:35 -0400

On Wed, Aug 16, 2017 at 11:55 PM, Paul Kyzivat <[email-masked]>
wrote:

>> iron out. But I thought people might like to see examples of two new drafts
>> that I think really show why this work is so worthwhile.
>>
>> Original Format:
>>
> window enough it omits the content of the TOC but leaves its heading sort
> of floating over the main text. That seems fine, but I can't find any way
> to see the content of the TOC without widening the window.
>
> wrapped content of the reference to align with the wrapped content of other
> references with shorter tags.
>
>         Thanks,
>         Paul

I am using the experimental style sheet with minor changes to improve
readability, the headings are coloured and the print version of the text is
black on white rather than the white on white of the original. I am not a
css guru.

​The first is the Toc trying to hide itself to make room on a small display
which is maybe not a bad thing.​ But it maybe should do it better.

The second is just a bug in my view. I don't understand why definition
lists are handled the way they are either. There is a compact style which I
would expect to try to keep the tag and definition on one line. But the
same happens for non compact which is just wrong in my view. I want the
<dd> to start a new line after the <dt>

Something that is just a bug in my processor is that the hypertext links
are not anchorized in the references section. Nor does the processor fill
in URI entries for documents that are missing them.
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Paul Kyzivat <[email-masked]>
Date: Thu, 17 Aug 2017 10:41:56 -0400

On 8/17/17 12:37 AM, Phillip Hallam-Baker wrote:
> 
> 
> On Wed, Aug 16, 2017 at 11:55 PM, Paul Kyzivat <[email-masked] 
> <mailto:[email-masked]>> wrote:
> 
>         My tools are not yet complete, there are several bugs and
>         glitches to iron out. But I thought people might like to see
>         examples of two new drafts that I think really show why this
>         work is so worthwhile.
> 
>         Original Format:
> 
>         <https://www.ietf.org/internet-drafts/draft-hallambaker-mesh-recrypt-02.txt>
> 
>         <https://www.ietf.org/internet-drafts/draft-hallambaker-mesh-confirm-01.txt>
> 
>         New Format:
> 
>         <http://prismproof.org/Documents/draft-hallambaker-mesh-recrypt.html>
> 
>         <http://prismproof.org/Documents/draft-hallambaker-mesh-confirm.html>
> 
>     1) The TOC is nice as long as the window is wide enough. If I narrow
>     the window enough it omits the content of the TOC but leaves its
>     heading sort of floating over the main text. That seems fine, but I
>     can't find any way to see the content of the TOC without widening
>     the window.
> 
>     things get weird for the reference with a long tag. I would expect
>     the wrapped content of the reference to align with the wrapped
>     content of other references with shorter tags.
> 
>              Thanks,
>              Paul
> 
> 
> readability, the headings are coloured and the print version of the text 
> is black on white rather than the white on white of the original. I am 
> not a css guru.
> 
> ​The first is the Toc trying to hide itself to make room on a small 
> display which is maybe not a bad thing.​ But it maybe should do it better.

The concept of it minimizing itself when there isn't enough room seems 
fine to me. The problem is the lack of a way to expand it so it is 
visible without widening the window.

	Thanks,
	Paul

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Thu, 17 Aug 2017 08:57:01 -0700

> distinguishing red and green would find this particular draft

The challenges with color are significant, ranging from accessibility
issues to cultural sensitivities to editorial training.  Nothing in any
of those areas has changed enough for me to be willing to open the
discussion on whether or not we should start allowing color with the new
format. If nothing else, I would like to have a few years of experience
in hammering out the new format before we open up this particular can of
worms.

-Heather