Re: [docbook-tc] Review of The Definitive Guide for 5.0

[Norman Walsh <ndw@nwalsh.com>]

/ "Mary McRae" <mary.mcrae@oasis-open.org> was heard to say:
| It will need to conform to the latest templates, including a
| Conformance Statement
| http://docs.oasis-open.org/templates/OASISSpecificationTemplateV4.0.html

Oh my! That's awful!

  <p class="title"> [Specification Title Version X.X]</p>

Why isn't a title an H1?

  <p class="subtitle">[Stage]</p>
  <p class="subtitle">[DD Month YYYY]</p>

A date isn't a subtitle!

  <p class="titlepageinfo">Specification URIs:</p>
  <p class="titlepageinfo">This Version:</p>
  <p class="titlepageinfodescription">http://docs.oasis-open.org/[tc-short...
  <p class="titlepageinfodescription">http://docs.oasis-open.org/[tc-short...

Why isn't this description-list arrangement a DL?

  <p class="titlepageinfo"> Abstract:</p>
  <p class="abstract">[Abstract goes here]</p>

  <p class="titlepageinfo">Status:</p>
  <p class="abstract"> This document...</p>
  <p class="abstract">Technical...</p>
  <p class="abstract"> For information...</p>

The status section isn't an abstract! And how are all these sibling paragras
related? Why not use DIV?

  <div>
  <p class="notices">Notices</p>
  <p class="normal">Copyright...</p>
  <p class="normal"> All capitalized terms...</p>
  <p class="normal">This document and ...</p>
  </div>

How does <p class='normal'> differ from <p>?

Anyone looking at a document written with this template using a screen reader,
braille reader, or other technology that doesn't support CSS is going to find
the whole thing an uninterrupted flow of paragraphs.

Can I use real markup instead of this template if I make it look the same?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | No man's knowledge here can go
http://www.oasis-open.org/docbook/ | beyond his experience.--John Locke
Chair, DocBook Technical Committee |

PGP signature