Re: Understanding format updated

On 23/04/2018 11:15 AM, Laura Carlson wrote:
> Hi Michael
>
> Thank you for your work on this.
>
> I noticed that none of the sub-headings <h3>, <h4>, etc are showing up
> on the text spacing document [1] .
>
> Is that part of the well-formedness work? Is there anything we
> could/should be doing to help?
Sort of. The generator enforces a consistent structure for Understanding 
documents, and one thing it does is ignore all but the first heading in 
a section. And for the basic sections like Intent, Examples, etc. it 
replaces headings with a generated one.

The fix here is to use <section> elements where sub-sections are 
intended, i.e., wrap the heading and subsequent text with <section> 
elements. I've done this in the text-spacing branch:

https://github.com/w3c/wcag21/commit/c12ae363277f380562a528f4e33b37c9e300421c

I'm not updating the snapshot right now (may tomorrow after the AG WG 
teleconference), but have confirmed that this causes the generator to 
output those headings.

As an editorial comment, I think this Understanding page has too many 
sub-sections. Most of them have only a paragraph, and a few are the only 
sub-section at their level, both of which are clues to me that 
sub-sections of the larger containing section were not needed. However, 
that's an editorial style thing without hard and fast rules, so I'm just 
pointing out the potential issue for now. At some point I plan to walk 
through the Understanding documents looking for editorial consistency, 
and I'd be likely to raise things like this in that pass, so it might be 
good to look at whether you really need all those sub-sections. But for 
now, the coding of that page will support the output of them on the next 
snapshot generation.

Michael
>
> Thanks again.
>
> Kindest Regards,
> Laura
>
> [1] https://www.w3.org/WAI/WCAG21/Understanding/text-spacing.html
>
> [2] https://rawgit.com/w3c/wcag21/text-spacing/understanding/21/text-spacing.html
>
> On 4/20/18, Michael Cooper <cooper@w3.org> wrote:
>> Over the past few weeks, I've been working on cleaning up the
>> presentation of the Understanding documents for WCAG 2.1, which up to
>> now have been in vanilla HTML. It's involved creating a generator, using
>> the very politically incorrect language XSLT because it's the language I
>> know for manipulating multiple HTML files. This is in the wcag21
>> repository, but automatic generation is not yet turned on. Until that
>> happens, I'll do manual snapshots. I've updated the publication location
>> in preparation for the anticipated WCAG 2.1 PR publication:
>>
>> https://www.w3.org/WAI/WCAG21/Understanding/
>>
>> The styling is a quick borrowing of W3C TR style, combined with elements
>> of our previous style for the 2.0 Understanding, and needs some tweaks.
>> Other elements addressable by the generator, such as inter-page
>> navigation, may also benefit from a look. Let me know if you have
>> thoughts about style or structure of these documents.
>>
>> Because the generator uses XSLT, the Understanding documents must be in
>> well-formed XML, or it won't run. Expect me to go through and make
>> well-formedness fixes from time to time. I did so for a bunch of
>> documents a couple weeks ago.
>>
>> Michael
>>
>>
>>
>

Received on Monday, 23 April 2018 16:58:01 UTC