kbd/specs/template/issues


Issues For and Questions About the a11yspec Template

Contents


General Issues Which Need to Be Addressed for All Specifications

  1. boilerplate "copyright" and "licensing" verbiage -- get from from LF?
  2. is there a boilerplate LF template?
    • no
  3. should the boilerplate template be Open A11y specific?
    • status: yes, to the greatest extent possible
  4. we obviously want to use the Open A11y logo -- what about the LF logo? is it required?
    • status: use of the LF is not, required but appreciated
  5. is verbiage needed re: trademarks of companies, interested parties, implementors?
    • status: no boilerplate text available from LF
  6. need boilerplate "status of this document" declarations
    • status: under consideration
  7. is any other boilerplate material needed?
    • status: under consideration


General Issues Which Have Been Answered

  • the feedback address for all Open A11y specifications will be accessibility-rfc@lists.linux-foundation.org
    • the feedback address will be included in each specification's Introduction (after verbiage such as "this specification was developed by the LF/Open A11y Keyboard Committee/Subgroup/SIG. To provide feedback, report errors or inquiries, please send email to accessibility-rfc@a11y.org" and in the ADDRESS section of the specification.


KAFS-specific Issues

  1. in the auto-generated version of the spec, 'class' is used extensively as a pseudo-semantic attribute -- that practice can be continued, but it is best if the anchors have some meaning in and of themselves rather than an alphanumeric code, as is currently the case. the other options is to use RDFa or simply use the id/name binding? i have removed the "emphasis" class from the I elements and converted them to EM tags to which specific styling can be applied; for example the I element was used to demarcate concepts such as StickyKeys, BounceKeys, etc. was classed as "emphasis" -- this should be classed as "spec-term" or "concept" or something similar
  2. we want to (at least) use dublin core markup in the HEAD via the meta element, right? (note that empty content fields are those i felt better populated by the editors)

  <meta name="DC.Title" content="Keyboard Access Functional Specification, RC2" />
  <meta name="DC.Title.Alternative" content="" />
  <meta name="DC.Creator.PersonalName" 
  content="Earl Johnson, Sun Microsystems, Inc." />
  <meta name="DC.Creator.PersonalName" 
  content="Bill Haneman, Sun Microsystems, Inc." />
  <meta name="DC.Creator.PersonalName" 
  content="Mark Novak, University of Wisconsin, Madison" />
  <meta name="DC.Creator.PersonalName" 
  content="Willie Walker, Sun Microsystems, Inc." />
  <meta name="DC.Subject" content="Functional Specification" />
  <meta name="DC.Subject" content="Keyboard" />
  <meta name="DC.Subject" content="Keyboard Input" />
  <meta name="DC.Subject" content="Alternative Input" />
  <meta name="DC.Subject" content="system pointer" />
  <meta name="DC.Subject" content="keyboard accessibility support" />
  <meta name="DC.Subject" content="keyboard notification" />
  <meta name="DC.Subject" content="Configuration and Setting Requirements" />
  <meta name="DC.Subject" content="End-User Notification Requirements" />
  <meta name="DC.Subject" content="Keyboard Invocation Requirements" />
  <meta name="DC.Subject" content="Pointer Emulation Requirements" />
  <meta name="DC.Subject" content="Feature Behavior Requirements" />
  <meta name="DC.Subject" content="StickyKeys" />
  <meta name="DC.Subject" content="MouseKeys" />
  <meta name="DC.Subject" content="RepeatKeys" />
  <meta name="DC.Subject" content="SlowKeys" />
  <meta name="DC.Subject" content="BounceKeys" />
  <meta name="DC.Subject" content="ToggleKeys" />
  <meta name="DC.Subject" content="Linux Foundation (LF)" />
  <meta name="DC.Subject" content="LF" />
  <meta name="DC.Subject" content="LF Certified" />
  <meta name="DC.Subject" content="X Windowing System" />
  <meta name="DC.Subject" content="" />
  <meta name="DC.Subject" content="" />
  <meta name="DC.Subject" content="" />
  <meta name="DC.Description" content="This functional specification 
  defines the support that must be built into the system. The 
  capabilities provided by the features in it define the pointer 
  based events and capabilities that must be emulated by the system 
  as well as how the system should interpret and process a user's 
  keypresses. For the most part, defining and/or specifying the exact 
  user interface[s] these features are presented in is beyond the scope 
  of this specification. The one exception area is keyboard shortcuts 
  that are already considered de facto standards.  These shortcuts are 
  explicitly defined." />
  <meta name="DC.Publisher" 
  content="Open Accessibility (A11y) Workgroup of the Linux Foundation" />
  <meta name="DC.Rights" content="" />
  <meta name="DC.Type" content="Text" />
  <meta name="DC.Format" content="text/html" />
  <meta name="DC.Identifier" 
  content="http://accessibility.linux-foundation.org/a11yspecs/kbd/keyboard-access-func-spec.html" />
  <meta name="DC.Language" content="us-en" />

  • we still need to locate the current home (if any) of the XBE document referenced in the specification (and our CSUN 2008 proposal) -- i extensively searched all of the ftp.x.org mirrors, but could not find:
  • http://ftp.x.org/pub/R6.4/xc/doc/specs/XKB/XKBlib/allchaps.ps
    http://web.archive.org/web/20020528232134/ftp.x.org/pub/R6.4/xc/doc/specs/XKB/XKBlib/

    when last this issue was discussed, the closest thing GJR had found to a "stable" reference was an 18 November 1997 date-stamped WayBackMachine archived copy of the original directory, complete with both: allchaps.ps and allchaps.pdf which
    can be found at:

    http://web.archive.org/web/20020528232134/http://ftp.x.org/pub/R6.4/xc/doc/specs/XKB/XKBlib/allchaps.ps



    Specific MarkUp Issues

    • the document-type of Open A11y specifications will be XHTML 1.0 Strict
      • all tables used in a specification must contain (at least): a summary, headers/id bindings, scope and a CAPTION; styling of tables should be handled with CSS, rather than be hard-coded into the TABLE
    • expansions must be provided for all acronyms and abbreviations
    • all Open A11y specifications '''must''' contain an ADDRESS element, containing: contact information, means of providing feedback, reporting errors, etc.. The ADDRESS will also contain boilerplate Open A11y/Linux Foundation verbiage as far as copyright and permissions are concerned, as is common at the bottom of technical specs
    • all Open A11y specifications need a normative references section. For example, to document RFC2119 in the text, the string RFC2119 should point to an entry in the Normative References section. This will assist in the stability, longevity and maintenance of the document, as the links contained in the text will not be broken when a resource moves or a URI changes, but can document when the resource was accessed and make it easier to universally effect a change to a single URI through an accompanying errata document. (a note on the example: this is supposed to be an example of code contained in a DL, but since the wiki allows certain HTML/XHTML markup without using HTML containers normally used to insert straight markup into a wiki page, and i have yet to be able to get the markup example to be rendered correctly)
       
    [RFC2119]</dt>
    <a href="http://www.rfc-editor.org/rfc/rfc2119.txt" >Key words for use in RFCs to indicate requirement levels</a>, RFC 2119, S. Bradner, March 1997.
    Available at: http://www.rfc-editor.org/rfc/rfc2119.txt</dd>
    • a unified "look-and-feel" (as well as sounds for aural styling, which can be added later without affecting the spec) needs to be established
    • it is strongly recommended that CSS be used for controlling the printed version of the spec when printed from the XHTML document?



    Syntaxic Conventions for Open A11y Specifications

    • all Open A11y specifications will conforms to RFC2119 to specify declarative, normative keywords, for example:
      • The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
    • all anchor values must be lower-case
    • any anchor name/id must be human-parseable
      • when a term is defined, the anchor to that definition should take the form def-foo, where foo is the concept's name; for example, def-mousekeys


    Groups: