- From: fantasai <fantasai.lists@inkedblade.net>
- Date: Fri, 22 Jul 2016 13:24:05 -0400
- To: "Heather Flanagan (RFC Series Editor)" <rse@rfc-editor.org>, "www-archive@w3.org" <www-archive@w3.org>
On 10/29/2015 03:55 AM, Heather Flanagan (RFC Series Editor) wrote:
>
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
>
> Hi fantasai,
>
> If you get bored and want to do me a HUGE favor, any comments you have
> regarding the HTML and CSS requirements drafts for the new RFC format,
> I'd be grateful. The idea, particularly for the CSS, is to give a
> designer enough information to know what we need without telling a
> designer how to do their job.
>
> HTML - https://datatracker.ietf.org/doc/draft-hildebrand-html-rfc/
> CSS - https://datatracker.ietf.org/doc/draft-flanagan-rfc-css/
Argh!!
I totally neglected to send comments on this! dbaron just reminded me.
Here's comments:
https://tools.ietf.org/html/draft-iab-rfc-css-01
Overall comment:
Many of these classes do not seem to be following CSS+HTML
best practice, which is to separate structure and style.
> Lists should provide ample whitespace between list elements for
> legibility unless a 'compact' class is specified (e.g., .dlCompact,
> .ulCompact, .olCompact).
There should only be one class: .compact. If the CSS needs to
make a distinction, it can use tag selectors like
ol.compact
> 7.1. .alignCenter
>
> To be used with '.artwork' to indicate the figure should align in the
> center of the page flow.
>
> 7.2. .alignRight
>
> To be used with '.artwork' to indicate the figure should align on the
> right of the page flow.
It's unclear from the description whether you're intending these
to float or just align. It also seems from the description of
.artwork that these are centered by default, in which case the
.alignCenter class is unnecessary but .alignLeft might be needed.
If you're expecting to host any translations to Hebrew or Arabic,
btw, then you also need left-alignment control, as in rtl scripts
the default alignment is right, not left.
> 7.3. .artwork
>
> These classes will mostly be styled as part of .artwork. Specific
> classes may include '.art-ascii-art' and '.art-svg'. Artwork will be
> held in its own block of space, centered in the page flow, and will
> not float. Images should have a max width of 100% so views will
> scale properly across a variety of screens and devices.
You need to define whether this will be set on a container of
the artwork or on the artwork itself, or both will be allowed.
E.g. consider <figure class="artwork">, <img class="artwork">,
<svg class="artwork">, and <pre class="artwork">...
If you are using <figure> on all of your artwork, though, then
this class would be unnecessary. :)
> 7.3.1. .art-ascii-art
>
> Must use a mono-spaced font.
This should be unnecessary. Such artwork should be using <pre>.
> 7.3.2. .art-logo
>
> No visible changes to the natural language content; keep in default
> style. Note that such images are not currently allowed in RFCs.
The purpose of this is unclear.
> 7.4. .cref
>
> A comment within an I-D; should be visually distinct.
>
> For I-Ds only; not for RFCs.
>
> 7.5. .crefAnchor
>
> A comment within an I-D; should be visually distinct.
>
> For I-Ds only; not for RFCs.
>
> 7.6. .crefSource
>
> A comment within an I-D; should be visually distinct.
>
> For I-Ds only; not for RFCs.
These descriptions are totally unclear.
> 7.7. .dlCompact
>
> Use less spacing on a definition list than the default.
>
> 7.8. .dlHanging
>
> Use the standard hanging indent for a definition list; indent terms.
>
> 7.9. .dlParallel
>
> Do not use the standard hanging indent for a definition list; align
> terms and definitions along left side.
As mentioned above, these should be dl.compact, dl.hanging,
and dl.parallel. Also if the default is hanging, there need
be no class for it.
> 7.10. .docInfo
>
> Hide from visible content.
But render to speech and non-CSS UAs? If this is just a comment
that is not intended to be read, then it should be a comment in
the markup and not a class in CSS.
> 7.11. .eref
>
> Standard link formatting (underlined, change in color).
Why not just select on a[href]?
> 7.12. .finalized
>
> Hide from visible content.
How is this different from .docInfo?
> 7.13. .note
>
> Notes should be emphasized and distinct from normal paragraph text.
Notes, in W3C specs, are non-normative text. They are not emphasized
in particular, but they are distinct from normal paragraph text.
I'm not sure what notes are used for in IETF documents, but if they
are for non-normative explanations, then emphasizing them doesn't
seem like the right instructions to the stylist.
> 7.13.1. .rfcEditorRemove
>
> An RFC Editor note may be added after the standard boilerplage. It
> should be visually distinct to highlight final removal of the note by
> the RFC Editor.
I do not understand from this description what is this class is for.
> 7.14. .olCompact
>
> Use less spacing on a numbered list than the default.
Again, this should be ol.compact
> 7.15. .olPercent
>
> If the style attribute from the source XML contains a percent sign, a
> particular style setting will be required to make this setting behave
> like an HTML ordered list.
This description is also unclear. What do percentages have to do
with ordered lists?
> 7.18. .rendered
>
> Hide from visible content.
I can't distinguish this from .docInfo or .finalized.
> 7.19. .sourcecode
>
> Code examples or components should be in a fixed-width font if the
> human language used has an available fixed-width font option, and
> should be visually distinct. If no fixed-width font is available,
> use the default font for that human language.
I think most languages have a fixed-width font option. :)
You should just specify a fixed-width font; in most cases
source code is ASCII-based, and if there are a few characters
that are not available in the fixed-width font, CSS will
automatically fall back to what's available for those
characters
> 7.22. .ulCompact
>
> Use less spacing on a bulleted list than the default.
This should be ul.compact.
> 7.23. .ulEmpty
>
> Indent from the margin of the previous paragraph.
I don't understand this directive.
> 7.24. .url
>
> Should be clearly distinguished as links.
>
> 7.25. .xref
>
> Should be clearly distinguished as links.
Why not just select a[href]?
You might consider having some kind of “example” class;
the W3C documents do this and it is useful for separating
out informative examples from the normative prose; and
also for helping people visually connect the various pieces
of a long example.
https://tools.ietf.org/html/draft-iab-html-rfc-03
> Some HTML constructs (such as <section>) will use
> multiple instances of these identifiers.
I'm not sure what this means. HTML does not allow for
duplicate IDs.
> The pilcrow will normally be invisible unless the
> element it is attached to is moused over.
Or if the pilcrow link is focused; this is necessary for
keyboard a11y.
> <meta name="author" content="Joe Hildebrand">
> <meta name="author" content="JOE HILDEBRAND">
> <meta name="author" content="Heather Flanagan">
I don't understand why Joe Hildebrand is listed twice.
Heather Flanagan is not.
> Note: the HTML <meta> tag does not contain a closing slash.
This note is unnecessary... If you think it's a point of
confusion, maybe just point out 6 or 6.1 that the HTML
serialization does not include closing slashes for empty
elements?
> 6.4. Page Headers and Footers
>
> In order to simplify printing by HTML renderers that implement
> [W3C.WD-css3-page-20130314], a hidden HTML <table> tag of class
> "ears" is added at the beginning of the HTML <body> tag, containing
> HTML <thead> and <tfoot> tags, each of which contains an HTML <tr>
> tag, which contains three HTML <td> tags with class "left", "center",
> and "right", respectively.
>
> The <thead> corresponds to the top of the page, the <tfoot> to the
> bottom. The string "[Page]" can be used as a placeholder for the
> page number. In practice, this must always be in the <tfoot>'s right
> <td>, and no control of the page number formatting is implied.
This seems extremely weird. I don't know what a CSS processor
would do with this table. If you're referencing CSS3 Paged
Media... you should instead add to the CSS, e.g.
@page {
@top-left { content: "Internet-Draft"; }
@top-center { content: "HTML RFC"; }
@top-right { content: "March 2016"; }
@bottom-left { content: "Hildebrand"; }
@bottom-center { content: "Expires 2 September 2016"; }
@bottom-left { content: counter(page); }
}
> Information about the document as a whole will appear as the first
> child of the HTML <body> element, embedded in an HTML <dl> element
> with id="identifiers". The defined terms in the definition list are
> "Workgroup:", "Series:", "Status:", "Published:", and "Author:" or
> "Authors:" (as appropriate). For example:
The source here should not append colons. It's already in a <dt>; this
is sufficient to distinguish it. If the stylist decides that colons are
appropriate, they can be added via CSS.
dl.identifiers > dt::after { content: ":"; }
Btw, why “identifiers” and not “metadata”?
> <nav> element that contains a <ul> element for each depth of the
> section hierarchy
Technically, a table of contents is an ordered list (<ol>)
not an unordered list (<ul>). (If you scramble the list,
it will no longer make sense.)
> Each <nav>, <ul>, and <li> element will have the class "toc".
This seems excessive. If you just have class="toc" on the
parent <nav>, it will be sufficient for styling purposes
and your markup will be shorter and easier to read.
Btw, your example seems to be missing the # from its fragment identifiers.
> <h2>Index</h2>
> <div class="index">
> <div class="indexIndex">
> <a href="#rfc.index.C">C</a>
> <a href="#rfc.index.P">P</a>
> </div>
This is a list, right? Shouldn't it use list markup? The list items
can easily be formatted inline via CSS, if that's desired.
> A few bits of metadata about the document that are less important to
> most readers are included after the author information. These are
> gathered together into a <div> of class "docInfo".
Seems to me that this would be a good candidate for <dl>, not <div>.
> Text artwork is rendered inside an HTML <pre> element, which is
> contained by a <div> element for consistency with SVG artwork.
...
> SVG artwork will be included inline. The SVG is wrapped in a <div>
> element with CSS classes "artwork" and "art-svg".
It seems to me that <figure> would be better than <div>.
A <figure> is not required to contain a <figcaption>, if
one does not exist.
> <img alt="IETF logo"
> src="data:image/gif;charset=utf-8;base64,...">
Alt text is a replacement for the image, not a description of it.
If you're using a logo, usually you just want the text of the logo
in the alt, not the word "logo"...
> <span class="editor">Ed.</span>
Shouldn't this be <abbr title="Editor">Ed.</abbr>?
In which case, if you need to style it, you can select on
[title=Editor]
in place of
.editor
> <span class="bcp14">MUST</span>
Maybe this should be <em class="bcp14">must</em>?
If the source text has correct capitalization, then the stylist
can use
em.bcp14 { font-variant: small-caps; }
to give a better presentation. If it is in all-caps, then
em.bcp14 { text-transform: lowercase; font-variant: small-caps; }
would work in most cases; it would fail to correctly capitalize
if the word happens to appear as the first word in a sentence,
though.
> <span class="crefSource">--life</span>
Did you mean for this to be an em dash?
> <div>
> <span>Email:</span>
> <a class="email" href="mailto:joe@example.com">joe@example.com</a>
> </div>
As the other components of author addresses don't have labels,
and email addresses are self-evident as such, is there really
a need for the label? It would be cleaner and just as usable
to leave it off.
Also class="email" is unnecessary; you can always select using
[href^="maito:"]
> <div>
> <span>Phone:</span>
> <a class="tel" href="tel:+1-720-555-1212">+1-720-555-1212</a>
> <span class="type">VOICE</span>
> </div>
Same comments as for email.
> The text is surrounded by quotes inside the
> <span>.
>
> <span class="refTitle">"Tags for Identifying Languages"</span>
These should be “curly quotes”.
> <div>URI:
> <a href="http://www.example.com"
> class="url">http://www.example.com</a>
> </div>
Same comments as for email.
This message is archived at
https://lists.w3.org/Archives/Public/www-archive/2016Jul/0003.html
for your convenience.
~fantasai
Received on Friday, 22 July 2016 17:24:39 UTC