Skip to content

Commit

Permalink
editorial: initial (mostly empty) PDF-AAM doc (#2356)
Browse files Browse the repository at this point in the history
  • Loading branch information
@cookiecrook
cookiecrook authored Oct 18, 2024
1 parent 4826ae1 commit a175b70
Show file tree
Hide file tree
Showing 4 changed files with 369 additions and 1 deletion.
7 changes: 6 additions & 1 deletion .github/labeler.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,4 +46,9 @@ spec:svg-aam:
spec:mathml-aam:
- any:
- changed-files:
- 'mathml/aam/**/*'
- 'mathml/aam/**/*'

spec:pdf-aam:
- any:
- changed-files:
- 'pdf-aam/**'
4 changes: 4 additions & 0 deletions pdf-aam/.pr-preview.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"src_file": "index.html",
"type": "respec"
}
4 changes: 4 additions & 0 deletions pdf-aam/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@

# Specification 'pdf-aam'

This is the repository for PDF Accessibility API Mappings (pdf-aam), which is part of the [ARIA suite](https://www.w3.org/WAI/ARIA/deliverables). General information about editing specifications is in the [main ARIA repository readme](https://github.com/w3c/aria/).
355 changes: 355 additions & 0 deletions pdf-aam/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,355 @@
<!doctype html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
<head>
<title>PDF Accessibility API Mappings 1.0</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
<script src="../common/script/resolveReferences.js" class="remove"></script>
<script src="../common/script/utility.js" class="remove"></script>
<script src="../common/biblio.js" class="remove" defer></script>

<link href="../common/css/mapping-tables.css" rel="stylesheet" type="text/css" />
<link href="../common/css/common.css" rel="stylesheet" type="text/css" />

<!-- note: may need to move the core-aam style sheet to common at some point -->
<link href="../core-aam/css/core-aam.css" rel="stylesheet" type="text/css" />

<script class="remove">
var respecConfig = {
github: "w3c/pdf-aam",
doJsonLd: true,
lint: true,

// specification status (e.g., WD, LC, NOTE, etc.). If in doubt use ED.
specStatus: "ED",
crEnd: "2023-01-02",
implementationReportURI: "https://w3c.github.io/test-results/core-aam-1.2/",

//perEnd: "2013-07-23",
//publishDate: "2013-08-22",

// the specifications short name, as in http://www.w3.org/TR/short-name/
shortName: "pdf-aam-1.0",

// if you wish the publication date to be other than today, set this
//publishDate: "2014-12-11",
copyrightStart: "2024",

// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
//previousPublishDate: "2014-06-12",
//previousMaturity: "FPWD",
//prevRecURI: "https://www.w3.org/TR/pdf-aam-1.0/",
//previousDiffURI: "http://www.w3.org/TR/2014/REC-wai-aria-implementation-20140320/",

// if there a publicly available Editors Draft, this is the link
edDraftURI: "https://w3c.github.io/pdf-aam/",

// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2012-02-21",

// editors, add as many as you like
// only "name" is required
editors: [
{
name: "Paul Rayius",
company: "Allyant",
companyURL: "https://www.allyant.com",
/* todo: add w3cid */
},
{
name: "Zak Kinsey",
company: "Target Stream",
companyURL: "https://www.targetstream.com",
/* todo: add w3cid */
},
],
formerEditors: [
],

// authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// only "name" is required. Same format as editors.

authors: [
{
name: "Paul Rayius",
company: "Allyant",
companyURL: "https://www.allyant.com",
/* todo: add w3cid */
},
{
name: "Zak Kinsey",
company: "Target Stream",
companyURL: "https://www.targetstream.com",
/* todo: add w3cid */
},
{
name: "James Craig",
company: "Apple, Inc.",
companyURL: "https://apple.com/accessibility",
w3cid: 42459,
},
],

// Working group info
group: "aria",

tocIntroductory: true,
//maxTocLevel: 4,

// Spec URLs
ariaSpecURLs: {
CR: "https://w3c.github.io/aria/",
CRD: "https://w3c.github.io/aria/",
PR: "https://www.w3.org/TR/wai-aria/",
REC: "https://www.w3.org/TR/wai-aria/",
},
accNameURLs: {
CR: "https://w3c.github.io/accname/",
CRD: "https://w3c.github.io/accname/",
PR: "https://www.w3.org/TR/accname-1.2/",
REC: "https://www.w3.org/TR/accname-1.2/",
},

preProcess: [linkCrossReferences],
postProcess: [addPlatformMaintainers],
xref: ["dom", "accname", "wai-aria", "infra"],

/* todo: add core-aam refs */

};
</script>
</head>
<body>
<section id="abstract">
<p>
This document describes how [=user agents=] should expose semantics of PDF content to <a class="termref">accessibility <abbr title="Application Programming Interfaces">APIs</abbr></a
>. This helps users with disabilities to obtain and interact with information using <a class="termref">assistive technologies</a>. Documenting these mappings promotes interoperable exposure of
roles, states, properties, and events implemented by accessibility APIs and helps to ensure that this information appears in a manner consistent with author intent.
</p>
</section>
<section id="sotd">
<p>
The Accessible Rich Internet Applications Working Group seeks feedback on any aspect of the specification. When submitting feedback, please consider issues in the context of the companion
documents. To comment, <a href="https://github.com/w3c/pdf-aam/issues/new">file an issue in the <abbr title="World Wide Web Consortium">W3C</abbr> pdf-aam GitHub repository</a>. If this is
not feasible, send email to <a href="mailto:[email protected]?subject=Comment%20on%20PDF-AAM%201.2">[email protected]</a> (<a href="http://lists.w3.org/Archives/Public/public-aria/"
>comment archive</a
>). In-progress updates to the document may be viewed in the <a href="http://w3c.github.io/pdf-aam/">publicly visible editors' draft</a>.
</p>
</section>
<section id="intro" class="informative">
<h2>Introduction</h2>
<p>
TBD. Some from Core-AAM.
</p>
<section id="intro_aapi">
<h3>Accessibility <abbr title="Application Programming Interfaces">APIs</abbr></h3>
<p>TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?</p>
</section>
<section>
<h4>Comparing Accessibility APIs</h4>
<p>TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?</p>
<section>
<h5>Accessible Names and Descriptions</h5>
<p>TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?</p>
</section>
</section>
</section>
<section id="conformance">
<section>
<h3>RFC-2119 Keywords</h3>
<p>
RFC-2119 keywords are formatted in uppercase and contained in a <code>strong</code> element with <code>class="rfc2119"</code>. When the keywords shown above are used, but do not share this format, they do not convey formal information in the RFC 2119 sense, and are merely explanatory, i.e., informative. As much as possible, such usages are avoided in this specification.
</p>
</section>
<section>
<h3>Normative and Informative Sections</h3>
<p>The indication whether a section is normative or non-normative (informative) applies to the entire section including sub-sections.</p>
<p>
Informative sections provide information useful to understanding the specification. Such sections may contain examples of recommended practice, but it is not required to follow such recommendations in order to conform to this specification.
</p>
</section>
</section>
<section class="informative" id="glossary">
<h2>Important Terms</h2>
<div>
<p>TBD. Can we add only PDF-specific terms here and cross-reference the others from common dir?</p>
<dl class="termlist">
<dt><dfn data-export="">term 1</dfn></dt>
<dd>
<p>
definition 1
</p>
</dd>
<dt><dfn data-export="">term 2</dfn></dt>
<dd>
<p>
definition 2
</p>
</dd>
</dl>
</div>
</section>
<section id="mapping">
<h2>Mapping <abbr title="Accessible Rich Internet Application">WAI-ARIA</abbr> to Accessibility <abbr title="Application Programming Interfaces">APIs</abbr></h2>
<p>TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?</p>


<section id="mapping_role">
<h2>Role mapping</h2>
<p>TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?</p>

<section id="roleMappingGeneralRules">
<h2>General rules</h2>
<p>TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?</p>
</section>

<section id="mapping_role_table">
<h3>Role Mapping Tables</h3>
<h4 id="role-map-example"><code>example</code></h4>
<table aria-labelledby="role-map-example">
<tbody>
<tr>
<th>ARIA Specification</th>
<td>
<a class="role-reference" href="#example"><code>example</code></a>
</td>
</tr>
<tr>
<th>MSAA + IAccessible2</th>
<td>
<span class="property">Role: <code>ROLE_SYSTEM_EXAMPLE</code></span><br>

</td>
</tr>
<tr>
<th><abbr title="User Interface Automation">UIA</abbr></th>
<td>
<span class="property">Control Type: <code>Example</code></span><br>
</td>
</tr>
<tr>
<th><abbr title="Accessibility Toolkit">ATK</abbr>/<abbr title="Assistive Technology - Service Provider Interface">AT-SPI</abbr></th>
<td>
<span class="property">Role: <code>ROLE_EXAMPLE</code></span><br>
</td>
</tr>
<tr>
<th>
<abbr title="macOS Accessibility Protocol">AX API</abbr><sup>[<a href="#ftn.note1">Note 1</a>]</sup>
</th>
<td>
<span class="property">AXRole: <code>AXxample</code></span><br>
<span class="property">AXSubrole: <code></code></span><br>
</td>
</tr>
</tbody>
</table>


<div class="note" id="ftn.note1">
<p>
<sup>[Note 1]</sup>
Footnote content
</p>
</div>

</section>
</section>

<section id="mapping_state-property">
<h2>State and Property Mapping</h2>
<p>This section describes how to expose PDF <a class="termref">states</a> and [=ARIA/properties=].</p>
<section id="statePropertyMappingGeneralRules">
<h2>General rules</h2>
<p>TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?</p>
</section>
<section id="mapping_state-property_table">
<h3>State and Property Mapping Tables</h3>
<section id="not_mapped">
<h4>Not Mapped</h4>
<p>
There are a number of occurrences in the table where a given state or property is declared "Not mapped". In some cases, this occurs for the default value of the state/property, and is equivalent to its absence. User agents might find it quicker to map the value than check to see if it is the default. For computational efficiency, user agents MAY expose the state or property value if doing so is equivalent to not mapping it. These cases are marked with an asterisk.
</p>
<p>
In other cases, it is mandatory that the state/property not be mapped, since exposing it implies a related affordance. An example is
<a class="state-reference" href="#aria-grabbed"><code>aria-grabbed</code></a
>. Its absence not only indicates that the accessible object is not grabbed, but further defines it as not grab-able. These cases are marked as "Not mapped" without an asterisk.
</p>
</section>

<h4 id="ariaExample"><code>aria-example</code>=<code>true</code></h4>
<table aria-labelledby="ariaExample">
<tbody>
<tr>
<th>ARIA Specification</th>
<td>
<a class="property-reference" href="#aria-atomic"><code>aria-example</code></a
>=<code>true</code>
</td>
</tr>
<tr>
<th>MSAA + IAccessible2</th>
<td>
<span class="property">Object Attribute: <code>example: true</code></span><br>
</td>
</tr>
<tr>
<th><abbr title="User Interface Automation">UIA</abbr></th>
<td>
<span class="property">Property: <code>example</code>: <code>true</code></span><br>
</td>
</tr>
<tr>
<th><abbr title="Accessibility Toolkit">ATK</abbr>/<abbr title="Assistive Technology-Service Provider Interface">AT-SPI</abbr></th>
<td>
<span class="property">Object Attribute: <code>example:true</code></span><br>
</td>
</tr>
<tr>
<th><abbr title="macOS Accessibility Protocol">AX API</abbr></th>
<td>
<span class="property">Property: <code>AXExample</code>: <code>YES</code></span><br>
</td>
</tr>
</tbody>
</table>

</section>
</section>
<section id="mapping_additional">
<h2>Special Processing Requiring Additional Computation</h2>
<p>TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?</p>
</section>
<section id="mapping_actions">
<h2>Actions</h2>
<p>TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?</p>

</section>
</section>

<section>
<h2>Privacy considerations</h2>
<p>TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?</p>
</section>
<section>
<h2>Security considerations</h2>
<p>This specification introduces no new security considerations.</p>
</section>

<section class="appendix" id="changelog">
<h2>Change Log</h2>
<p>TBD. Should we duplicate or cross-reference this content from the corresponding Core-AAM section?</p>
</section>
<section class="appendix informative section" id="acknowledgements">
<h3>Acknowledgments</h3>
<p>The following people contributed to the development of this document.</p>
<ul id="gh-contributors">
<!-- list of contributors will appear here, along with link to their GitHub profiles -->
</ul>
<div data-include="../common/acknowledgements/aria-wg-active.html" data-include-replace="true"></div>
<div data-include="../common/acknowledgements/funders.html" data-include-replace="true"></div>
</section>
</body>
</html>

0 comments on commit a175b70

Please sign in to comment.