Subject: [rfc-i] Request for feedback: the new CSS

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Thu, 1 Dec 2016 11:21:35 -0800

Hello all,

A first draft of the CSS that will be embedded in the new HTML output
format is ready for feedback. The developer and I do not consider this
done. In particular, things that need work include:

* Mobile layouts will need further polish.
* The index is not aligned with the other sections.
* Compact lists have been given only a preliminary treatment. (And lists
in general could use a bit more attention.)
* Notes have not been given any treatment
* Certain classes have not been accounted for (e.g. ".finalized").

Given the restrictions around JavaScript, features like hamburger menus
(those three or four lines that appear when the display is too small to
show something like a table of contents or sidebar) are not available.

Sample document:
https://rfc-format.github.io/draft-iab-rfc-css-bis/sample.html

If you have suggestions or recommendations, please add them as an issue
in github.

Issue tracker:
https://github.com/rfc-format/draft-iab-rfc-css-bis/issues

If you have time and interest, you can be of even more assistance by
creating additional sample files according to the HTML spec so that the
CSS developer has more content to test against.

Thanks for your time and attention!
Heather Flanagan, RSE
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Ted Lemon <[email-masked]>
Date: Thu, 1 Dec 2016 14:33:40 -0500

This looks good.   I submitted some comments in the github tracker.   Dunno if I’m right about any of the comments, but hopefully they do more harm than good. :)

---

From: Ted Lemon <[email-masked]>
Date: Thu, 1 Dec 2016 14:34:11 -0500

On Dec 1, 2016, at 2:33 PM, Ted Lemon <[email-masked]> wrote:
>  hopefully they do more harm than good. :)

Er, less harm than good…

---

From: Dan York <[email-masked]>
Date: Thu, 1 Dec 2016 20:45:43 +0000

Heather,

On Dec 1, 2016, at 2:21 PM, Heather Flanagan (RFC Series Editor) <[email-masked]<mailto:[email-masked]>> wrote:

Sample document:

Very nice!  I like what I see.  One minor thing I like is how the TOC will be fixed over on the right side if your window is large enough, but then goes back into the flow of the document if you shrink the window.  Very nice touch!

I will. Don't have time today to spend more than the quick scan, but will try to do so.

I might have a few cycles next week to help here, but need a bit more guidance on what you need. How do you want these files created?

Very cool to see all this,
Dan

--
Dan York
Senior Content Strategist, Internet Society
[email-masked]<mailto:[email-masked]>   +1-802-735-1624
Jabber: [email-masked]<mailto:[email-masked]>
Skype: danyork   http://twitter.com/danyork

http://www.internetsociety.org/

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Thu, 1 Dec 2016 12:55:18 -0800

On 12/1/16 12:45 PM, Dan York wrote:
> Heather,
> 
>> On Dec 1, 2016, at 2:21 PM, Heather Flanagan (RFC Series Editor)
>> <[email-masked] <mailto:[email-masked]>> wrote:
>>
>> Sample document:
> Very nice!  I like what I see.  One minor thing I like is how the TOC
> will be fixed over on the right side if your window is large enough, but
> then goes back into the flow of the document if you shrink the window.
>  Very nice touch!
> 

Much appreciated!

> I might have a few cycles next week to help here, but need a bit more
> guidance on what you need. How do you want these files created?

If you just take the sample.html that we have in github and fill it with
real data (e.g., the text, tables, figures, etc., from a real I-D) that
would be an enormous help.

If you want bonus points, read the XML and HTML format drafts (just
finishing up AUTH48 now) and try anything else that you think can be
done within those specs.

Thanks!
Heather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Thu, 1 Dec 2016 13:18:31 -0800

On 12/1/16 1:07 PM, Russ Housley wrote:
> Heather, > >> On Dec 1, 2016, at 2:21 PM, Heather Flanagan (RFC Series Editor)
>> <[email-masked] <mailto:[email-masked]>> wrote: >> >> Sample
document: >>
https://rfc-format.github.io/draft-iab-rfc-css-bis/sample.html > > I
think that the index haven multiple columns is strange since > nothing
else does. >

It's not unprecedented in the publishing world, but I can see your
point. Would you like this to go in github?

-Heather

---

From: Russ Housley <[email-masked]>
Date: Thu, 1 Dec 2016 16:17:08 -0500

Heather,

> On Dec 1, 2016, at 2:21 PM, Heather Flanagan (RFC Series Editor) <[email-masked]> wrote:
> 
> Sample document:

I think that the index haven multiple columns is strange since nothing else does.

Russ

---

From: "Adrian Farrel" <[email-masked]>
Date: Fri, 2 Dec 2016 08:51:13 -0000

Thanks for this Heather,

> If you have suggestions or recommendations, please add them as an issue

No, it's alright, I'll just raise them in an email (this email) for discussion
on the mailing list as normal so other only have to look in one place for the
conversation :-)

1. You have some embedded code fragments. Is it your intention that these will
still be visibly marked <CODE BEGINS> and <CODE ENDS>?

2. It would be lovely if you could address the "Contributors" section (current
schema means that the section has to be created by hand). An "obvious" solution
is allow a new 'role' value of 'contributor' in 'author' and pull that out into
the separate section.

Thanks,
Adrian

---

From: Yoav Nir <[email-masked]>
Date: Fri, 2 Dec 2016 11:28:14 +0200

> On 2 Dec 2016, at 10:51, Adrian Farrel <[email-masked]> wrote:

<snip />

> is allow a new 'role' value of 'contributor' in 'author' and pull that out into

I prefer crafting the Acknowledgement section by hand, because often it is not just a list of names. “Thanks to Jane for contributing the test vectors. Special thanks to Julian for contributing the ABNF”.

Yoav

---

From: Martin Thomson <[email-masked]>
Date: Fri, 2 Dec 2016 20:32:37 +1100

> I prefer crafting the Acknowledgement section by hand, because often it is not just a list of names. “Thanks to Jane for contributing the test vectors. Special thanks to Julian for contributing the…

Yeah, frankly I think that this is a bit of a mess:
https://tlswg.github.io/tls13-spec/#contributors  Yes, all those
people deserve acknowledgment (except me), but it's almost the longest
section in the document now.
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Martin J. Dürst <[email-masked]>
Date: Fri, 2 Dec 2016 19:58:09 +0900

Hello Heather, others,

On 2016/12/02 04:21, Heather Flanagan (RFC Series Editor) wrote:
> format is ready for feedback.

Great start. See more comments below.

> The developer and I do not consider this

Here are copies of my github issues for those who prefer the mailing list:

#10: Indentation from left edge needs more work

Currently, there are (too!!!) many different amounts of indentation from 
the left edge of the page. That "Index" is less indented than anything 
else seems to be a clear error. But the bigger problem is that block 
text is indented more than headings. This may be a direct influence from 
the text format, but it looks really out of place in the new format 
where headings stand out clearly because of their larger size and 
heavier weight. I have just at random checked a wide variety of books in 
my bookshelves, and none of them indents text blocks more than headings.

#11: Duplication of alternate address info in header unnecessary for 
Latin script

This may not be a CSS issue; if not, please reroute.
I have tried to explain this many times, and I was under the expression 
that I was successful, but apparently not:
"ɟ. H̭ildebrand (J. Hildebrand)" and "Čisco Śystems, Inc. (Cisco 
Systems, Inc.)" in the header look totally silly, not because they are 
constructed examples, but because they are useless overkill, different 
from any other serious publisher going back centuries.
Please fix.

#12: References use e.g. "BCP47, RFC5646", should be "BCP 47, RFC 5646"

This may not be a CSS issue; if not, please reroute.
In the reference section, there are missing spaces. Example:
[LANG-TAGS]
Phillips, A. and M. Davis, "Tags for Identifying Languages", BCP47, 
RFC5646, September 2009, http://www.rfc-editor.org/info/rfc5646.
It's clear that there should be no spaces in the URI (and the doi, which 
is missing in this case), but otherwise, there should be spaces after 
"BCP", "RFC", and so on, as there are spaces in the current RFC format 
in these places (see e.g. https://www.rfc-editor.org/rfc/rfc6497.txt).

In addition, I think there's a translation error, in that the "author" 
field of [GOST3410], "Государственный стандарт Российской Федерации", 
would translate into something like "Official Standard of the Russian 
Federation", but the equivalent field reads "Federal Agency on Technical 
Regulating and Metrology", which according to Wikipedia would be 
"Федеральное агентство по техническому регулированию и метрологии".

> CSS developer has more content to test against.

I'd like to start converting a bis version of RFC 6068 to the new 
format, including some really internationalized examples. Any pointers 
to how to do that? (I'd want to generate the HTML from XML.)

> Thanks for your time and attention!

Thank you (and everybody else involved) for your hard work!

Regards,  Martin.

---

From: Joe Hildebrand <[email-masked]>
Date: Fri, 2 Dec 2016 10:09:38 -0700

> On Dec 2, 2016, at 1:51 AM, Adrian Farrel <[email-masked]> wrote:
> 
> Thanks for this Heather,
> 

As far as I know, those markings are optional, right?  The idea is that extracting code from the XML should be much easier than parsing the text for <CODE BEGINS> and <CODE ENDS>.

> is allow a new 'role' value of 'contributor' in 'author' and pull that out into

That's an interesting idea for the next rev.  I've added an issue to ensure we come back to it:

https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/2

-- 
Joe Hildebrand

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 2 Dec 2016 20:32:44 +0100

(One minor point:)

> On 2 Dec 2016, at 11:58, Martin J. Dürst <[email-masked]> wrote:
> 
> "ɟ. H̭ildebrand (J. Hildebrand)" and "Čisco Śystems, Inc. (Cisco Systems, Inc.)" in the header look totally silly

"É. HÌ­ildebrand (J. Hildebrand)" and "Äisco Åystems, Inc. (Cisco Systems, Inc.)” look less silly (which is what you get when Swissôtel sends you a booking confirmation, or some other UTF-8-incompetent system got their hands on the bits).

Grüße, Carsten

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 3 Dec 2016 08:34:42 +1300

On 03/12/2016 06:09, Joe Hildebrand wrote:
> As far as I know, those markings are optional, right?

Not exactly. And they aren't our choice - they are defined in the IETF Trust
legal provisions:

>>> License to Code Components.
>>> 
>>> Definition. IETF Contributions and IETF Documents often include
>>> components intended to be directly processed by a computer (“Code Components”).
>>> A list of common Code Components can be found at http://trustee.ietf.org/license-info/. 
>>> 
>>> Identification. Text in IETF Contributions and IETF Documents of the types
>>> identified in Section 4.a above shall constitute “Code Components”. In addition,
>>> any text found between the markers <CODE BEGINS> and <CODE ENDS>, or otherwise
>>> clearly labeled as a Code Component, shall be considered a “Code Component”.

So regardless of what would be most elegant in XML2RFCv3, authors must be able
to include these labels explicitly.

> The idea is that extracting code from the XML should be much easier than parsing the text for <CODE BEGINS> and <CODE ENDS>.
> 

    Brian

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 3 Dec 2016 08:40:41 +1300

>> I prefer crafting the Acknowledgement section by hand, because often it is not just a list of names. “Thanks to Jane for contributing the test vectors. Special thanks to Julian for contributing th…

Who says you can't do that? The formal Contributors section is usefulfor people who
don't quite make it into the Authors section, because of the policy of limiting
the number of auhors. https://tools.ietf.org/html/rfc7322#section-4.11

> section in the document now.

That is *not* the intended use of the Contributors section IMHO.
https://tools.ietf.org/html/rfc7322#section-4.10

    Brian

---

From: "John Levine" <[email-masked]>
Date: 2 Dec 2016 22:19:19 -0000

>to include these labels explicitly.

I see the phrase "or otherwise clearly labeled as a Code Component"
which suggests to me that we don't have to use the ugly bracket things
if the document says something like all the blocks of fixed pitch text
are code components.  They're still coded in the XML so mechanical
extraction is no problem.

For that matter, I'd argue that since the XML is the canonical format,
the XML code markings clearly label the code and we're done.

R's,
John

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 3 Dec 2016 11:37:23 +1300

> the XML code markings clearly label the code and we're done.

Yes, that *ought* to be the case, but I would much prefer to see the Trust legal
provisions modified accordingly. It's going to be complicated enough persuading
lawyers and judges that XML is more canonical than plain text, without also
expecting them to re-interpret the Trust text as well.

   Brian

---

From: "John R Levine" <[email-masked]>
Date: 2 Dec 2016 17:39:38 -0500

> expecting them to re-interpret the Trust text as well.

I'm a trustee, I can bring it up.

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
Please consider the environment before reading this e-mail. https://jl.ly
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 3 Dec 2016 11:53:03 +1300

> I'm a trustee, I can bring it up.

That's great John, thanks. I think a very few words can fix it. Let me know
if I can help in any way.

   Brian

---

From: "John R Levine" <[email-masked]>
Date: 2 Dec 2016 18:07:01 -0500

> expecting them to re-interpret the Trust text as well.

Actually, it works the other way.  If a lawyer wants an authenticated copy 
of an IETF document, he writes to us (or if he's dumb he subpoenas us) and 
we send him a boilerplate response.  See for example what we sent to Sony 
and Samsung:

https://iaoc.ietf.org/subpoenas.html

So if we say the XML is the definitive version, that's it.

Regards,

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 3 Dec 2016 12:49:31 +1300

> So if we say the XML is the definitive version, that's it.

Good to know, although of course there might be a corner case somewhere.

     Brian

---

From: Russ Housley <[email-masked]>
Date: Mon, 5 Dec 2016 12:18:48 -0500

> expecting them to re-interpret the Trust text as well.

There are many, many RFCs that do not use <CODE BEGINS> … <CODE ENDS>.  That is the reason that these marks are optional in the Trust Legal Provisions.

I think it is pretty clear when ABNF, YANG, ASN.1, C, Perl, and so on are used.  I do not think we want to make a change to the Trust Legal Provisions based on the ability of the use a different style as an alternative way to mark code.

Russ

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 6 Dec 2016 08:16:52 +1300

> I think it is pretty clear when ABNF, YANG, ASN.1, C, Perl, and so on are used.  I do not think we want to make a change to the Trust Legal Provisions based on the ability of the use a different st…

I understand that. I think there's a broader issue though. Throughout the TLP the word "text" is used to refer to the contents
of an IETF document. IANAL but don't we need some words that will prevent
ambiguity when the canonical form changes from plain text? (Yes, you and I know that XML
is written in text, but I'm not sure that all lawyers, judges and even juries will get that,
or be prepared to treat XML tags as part of the "text".)

    Brian

---

From: "Scott O. Bradner" <[email-masked]>
Date: Mon, 5 Dec 2016 14:17:14 -0500

I asked Jorge and he said the same thing - the tags are optional

Scott

> On Dec 5, 2016, at 12:18 PM, Russ Housley <[email-masked]> wrote:
> 
>

---

From: "John Levine" <[email-masked]>
Date: 5 Dec 2016 19:32:46 -0000

>I understand that. I think there's a broader issue though. Throughout the TLP the word "text" is used to refer to
>the contents of an IETF document. IANAL but don't we need some words that will prevent
>ambiguity when the canonical form changes from plain text?

IANAL, but no.  The TLP is in effect a contract, and contracts are
interpreted by humans, not by computers.

R's,
John

---

From: "Scott O. Bradner" <[email-masked]>
Date: Mon, 5 Dec 2016 14:40:54 -0500

I have asked Jorge what he thinks 

Scott

> On Dec 5, 2016, at 2:32 PM, John Levine <[email-masked]> wrote:
>

---

From: "Scott O. Bradner" <[email-masked]>
Date: Mon, 5 Dec 2016 19:35:38 -0500

Jorge pointed out that, at least for the foreseeable future, the courts will be seeing paper printouts
of the documents, whatever their formats so the question of “text” is not likely to be an issue

Scott

> On Dec 5, 2016, at 2:40 PM, Scott O. Bradner <[email-masked]> wrote:
>

---

From: "John R Levine" <[email-masked]>
Date: 5 Dec 2016 19:43:56 -0500

> of the documents, whatever their formats so the question of “text” is not likely to be an issue

That hasn't been my experience.  In recent years in depos and I think in 
Federal court we've looked at stuff on screens.  But I still think it'd be 
adequate to send them the XML and PDF and tell them we're pretty sure they 
say the same thing.

Regards,

---

From: Martin J. Dürst <[email-masked]>
Date: Tue, 6 Dec 2016 13:32:52 +0900

> "É. HÌ­ildebrand (J. Hildebrand)" and "Äisco Åystems, Inc. (Cisco Systems, Inc.)” look less silly (which is what you get when Swissôtel sends you a booking confirmation, or some other UTF-8-incompe…

There are two issues here. The first is on the appropriate choice of 
accents and variant letters for examples like these. This is what 
Carsten seems to comment on.

The second one is that there's no point in repeating ASCII-only 
equivalents immediately after the real stuff if the real stuff is 
(extended) Latin (and is correctly shown, which is easy to make sure in 
for HTML). That was my point.

Regards,   Martin.

---

From: Larry Masinter <[email-masked]>
Date: Wed, 7 Dec 2016 05:28:45 +0000

> adequate to send them the XML and PDF and tell them we're pretty
> sure they say the same thing.

Does it help in this case that the XML will be *in* the PDF?
At least to reduce the risk of sending things that don't match?

---

From: "John R Levine" <[email-masked]>
Date: 7 Dec 2016 08:10:07 -0500

> At least to reduce the risk of sending things that don't match?

It couldn't hurt, but I don't know of any case law.

Regards,

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Wed, 14 Dec 2016 13:54:09 -0800

Hello all,

I've created a second sample HTML file for the developer, using the text
(with some modification to use the non-ASCII characters in the examples)
and structure from RFC 7700.

https://rfc-format.github.io/draft-iab-rfc-css-bis/sample2.html

I've got a third sample in progress, using the text and structure from
RFC 7642. The figure will be converted to SVG for that sample. If my
brain doesn't melt from handcrafting all this HTML, the fourth sample
will be from RFC 7049.

I will post when we have an updated CSS. Feedback remains quite welcome,
either to this list or to the issue tracker on github
(https://github.com/rfc-format/draft-iab-rfc-css-bis/issues).

-Heather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Wed, 14 Dec 2016 14:02:55 -0800

> (https://github.com/rfc-format/draft-iab-rfc-css-bis/issues).

I should note that in creating these HTML files, I have found and filed
a bug re: the document info.

https://github.com/rfc-format/draft-iab-html-rfc-bis/issues/4

If you create a sample file, you'll need to change that initial set of
details in the file.

-Heather

---

From: Martin Thomson <[email-masked]>
Date: Thu, 15 Dec 2016 09:51:58 +1100

One thing that turned up was an error in the toc (I have a PR that
attempts to correct many of the HTML errors that came up).  That
manifested as a slight style difference.  In looking into this, I
discover that draft-iab-rfc-html recommends the following
construction:

<ul>
  <li>1. Section</li>
  <ul>
    <li>1.1. Section</li>
  </ul>
</ul>

This is really just exploiting the fault tolerance of HTML.
https://html.spec.whatwg.org/multipage/semantics.html#the-ul-element
says that <ul> contains <li>.  I would prefer if we could mandate
that.  That is,

<ul>
  <li>1. Section
    <ul>
      <li>1.1. Section</li>
    </ul>
  </li>
</ul>

I note that xml2rfc (the python thing) has produced the former
construction.  Julian Reschke's XSLT-based transform produces the
latter form.  I find that styling the latter is easier; dealing with
the former is a nuisance.

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Thu, 15 Dec 2016 09:38:54 -0800

On 12/2/16 2:58 AM, Martin J. Dürst wrote:
> "ɟ. H̭ildebrand (J. Hildebrand)" and "Čisco Śystems, Inc. (Cisco Systems,
> Inc.)" in the header look totally silly, not because they are

Where I ended up with this was to say that extended Latin without the
parenthetical ASCII equivalent is ok in company names. It is not (yet)
OK for person names. This is me being conservative and wanting to be
absolutely clear re: person names, which allowing a bit of
experimentation with company names. I recognize that other publishers
don't treat this kind of thing the same way. We will adapt over time as
technology evolves and this guidance re: using nonASCII characters in
RFCs will almost certainly evolve too.

The characters must work for more than just browsers, and I'm having
rather mixed results with text readers for even extended latin characters.

-Heather

---

From: Julian Reschke <[email-masked]>
Date: Thu, 15 Dec 2016 19:58:36 +0100

On 2016-12-15 18:38, Heather Flanagan (RFC Series Editor) wrote:
> ...
> ...

"text readers" == "programs displaying plain text files"?