Skip to content

Commit

Permalink
Add links to review comments. (More may be added later as comments ar…
Browse files Browse the repository at this point in the history 
…e labelled.)

Also moved the last 3 subsections in the Language section below a Declaring Language heading.
  • Loading branch information
@r12a
r12a committed Jul 15, 2022
1 parent 9160ecc commit 390a096
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 11 deletions.
77 changes: 67 additions & 10 deletions index.html
View file
Expand Up @@ -206,6 +206,8 @@ <h4>Language metadata about the resource as a whole</h4>
<section id="sec_lang_values" class="subtopic">
<h3>Defining language values</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Alang_values" target="_blank">See related review comments.</a></p>

<aside class="links" id="lang_values_links">
<p class="links_title">Useful background and overviews for this section</p>

Expand Down Expand Up @@ -294,8 +296,13 @@ <h3>Defining language values</h3>



<section id="sec_lang_mixed" class="subtopic">
<h3>Declaring language at the resource level</h3>
<section id="sec_lang_declaration" class="subtopic">
<h3>Declaring language</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Alang_declaration" target="_blank">See related review comments.</a></p>

<section id="sec_lang_mixed">
<h4>Declaring language at the resource level</h4>

<p>Here we are talking about an independent unit of data that contains structured text. Examples may include a whole HTML page, an XML document, a JSON file, a WebVTT script, an annotation, etc.</p>

Expand Down Expand Up @@ -349,8 +356,8 @@ <h3>Declaring language at the resource level</h3>



<section id="lang_block" class="subtopic">
<h3>Establishing the language of a content block</h3>
<section id="lang_block">
<h4>Establishing the language of a content block</h4>

<div class="xref"><span class="seealso">See also</span>
<p>[[[#sec_lang_values]]].</p>
Expand Down Expand Up @@ -379,8 +386,12 @@ <h3>Establishing the language of a content block</h3>
</section>


<section id="lang_inline" class="subtopic">
<h3>Establishing the language of inline runs</h3>




<section id="lang_inline">
<h4>Establishing the language of inline runs</h4>

<p>In this section we refer to information that needs to be provided for a range of characters in the middle of a paragraph or string.</p>

Expand All @@ -397,7 +408,7 @@ <h3>Establishing the language of inline runs</h3>

<p>Where a switch in language can affect operations on the content, such as spell-checking, rendering, styling, voice production, translation, information retrieval, and so forth, it is necessary to indicate the range of text affected and identify the language of that content.</p>
</section>

</section>
</section>


Expand Down Expand Up @@ -598,6 +609,8 @@ <h4>Base direction and language</h4>
<section id="sec_bidi_values" class="subtopic">
<h3>Base direction values</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Abidi_values" target="_blank">See related review comments.</a></p>

<div class="req" id="bidi_values">
<p class="advisement">Values for the default base direction should include left-to-right, right-to-left, and auto.</p>
</div>
Expand All @@ -616,6 +629,8 @@ <h3>Handling direction in markup</h3>
<p>This section is about defining approaches to bidi handling that work with resources that organizes content using markup. Some of the recommendations are different from those for handling strings on the Web (see [[[#sec_bidi_strings]]]).</p>


<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Abidi_markup" target="_blank">See related review comments.</a></p>

<aside class="links" id="links_bidi_markup">
<p class="links_title">Useful background and overviews for this section</p>
<ul>
Expand Down Expand Up @@ -711,6 +726,8 @@ <h3>Handling base direction for strings</h3>

<p class="note">The information in this section is pulled from <a href="https://w3c.github.io/string-meta/">Requirements for Language and Direction Metadata in Data Formats</a>. That document is still being written, so these guidelines are likely to change at any time.</p>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Abidi_strings" target="_blank">See related review comments.</a></p>

<aside class="links" id="links_bidi_strings">
<p class="links_title">Useful background and overviews for this section</p>
<ul>
Expand Down Expand Up @@ -979,6 +996,7 @@ <h2>UTF-8 Character Encoding Form</h2>
<section id="char_def" class="subtopic">
<h3>Choosing a definition of 'character'</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Achar_def" target="_blank">See related review comments.</a></p>

<p>The term character is used differently in a variety of contexts and often leads to confusion when used outside of these contexts. In the context of the digital representations of text, a character can be defined as a small logical unit of text. Text is then defined as sequences of characters. While such an informal definition is sufficient to create or capture a common understanding in many cases, it is also sufficiently open to create misunderstandings as soon as details start to matter. In order to write effective specifications, protocol implementations, and software for end users, it is very important to understand that these misunderstandings can occur.</p>

Expand Down Expand Up @@ -1173,6 +1191,8 @@ <h3>Defining a Reference Processing Model</h3>
<section id="char_ranges" class="subtopic">
<h3>Including and excluding character ranges </h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Achar_ranges" target="_blank">See related review comments.</a></p>

<aside class="links" id="links_char_ranges">
<p class="links_title">Useful background and overviews for this section</p>
<ul>
Expand Down Expand Up @@ -1284,6 +1304,8 @@ <h3>Using the Private Use Area</h3>
<section id="char_choosing" class="subtopic">
<h3>Choosing character encodings</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Achar_choosing" target="_blank">See related review comments.</a></p>




Expand Down Expand Up @@ -1418,6 +1440,8 @@ <h3>Identifying character encodings</h3>
<h3>Designing character escapes</h3>


<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Achar_escapes" target="_blank">See related review comments.</a></p>

<aside class="links" id="links_char_escapes">
<p class="links_title">Useful background and overviews for this section</p>
<ul>
Expand Down Expand Up @@ -1616,6 +1640,8 @@ <h3>Defining 'string'</h3>
<section id="char_ref_Unicode_char" class="subtopic">
<h3>Referring to Unicode characters</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Achar_ref" target="_blank">See related review comments.</a></p>

<div class="req" id="char_ref_Uchar">
<p class="advisement">Use U+XXXX syntax to represent Unicode code points in the specification.</p>
</div>
Expand All @@ -1631,6 +1657,7 @@ <h3>Referring to Unicode characters</h3>
<section id="char_unicoderef" class="subtopic">
<h3>Referencing the Unicode Standard</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Achar_unicoderef" target="_blank">See related review comments.</a></p>

<aside class="links" id="links_char_unicoderef">
<p class="links_title">Useful background and overviews for this section</p>
Expand Down Expand Up @@ -1701,6 +1728,9 @@ <h2>Text-processing</h2>
<section id="char_indexing" class="subtopic">
<h3>Choosing text units for segmentation, indexing, etc.</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Achar_indexing" target="_blank">See related review comments.</a></p>



<div class="xref"><span class="seealso">See also</span>
<p>[[[#char_string]]].</p>
Expand Down Expand Up @@ -1800,6 +1830,8 @@ <h3>Choosing text units for segmentation, indexing, etc.</h3>
<section id="string_match" class="subtopic">
<h3>Matching string identity for identifiers and syntactic content</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Astring_match" target="_blank">See related review comments.</a></p>


<aside class="links" id="links_">
<p class="links_title">Useful background and overviews for this section</p>
Expand Down Expand Up @@ -1861,6 +1893,8 @@ <h3>Matching string identity for identifiers and syntactic content</h3>
<section id="text_n11n" class="subtopic">
<h3>Working with Unicode Normalization</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Atext_n11n" target="_blank">See related review comments.</a></p>


<aside class="links" id="links_text_n11n">
<p class="links_title">Useful background and overviews for this section</p>
Expand Down Expand Up @@ -1987,6 +2021,8 @@ <h4>Specifying Unicode Normalization</h4>
<section id="text_case" class="subtopic">
<h3>Case folding</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Atext_case" target="_blank">See related review comments.</a></p>

<aside class="links" id="links_text_case">
<p class="links_title">Useful background and overviews for this section</p>
<ul>
Expand Down Expand Up @@ -2043,7 +2079,9 @@ <h3>Case folding</h3>


<section id="char_truncation" class="subtopic">
<h3>Truncating or limiting the length of strings</h3>
<h3>Truncating or limiting the length of strings</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Achar_truncation" target="_blank">See related review comments.</a></p>

<aside class="links" id="links_char_truncation">
<p class="links_title">Useful background and overviews for this section</p>
Expand Down Expand Up @@ -2218,6 +2256,8 @@ <h3>Working with file and path names</h3>
<section id="char_sort" class="subtopic">
<h3>Specifying sort and search functionality</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Achar_sort" target="_blank">See related review comments.</a></p>

<aside class="links" id="links_char_sort">
<p class="links_title">Useful background and overviews for this section</p>
<ul>
Expand Down Expand Up @@ -2290,6 +2330,8 @@ <h2>Resource identifiers</h2>
<section id="sec_resid_basic" class="subtopic">
<h3>Basics</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Aresid_basic" target="_blank">See related review comments.</a></p>

<aside class="links" id="links_sec_resid_basic">
<p class="links_title">Useful background and overviews for this section</p>
<ul>
Expand Down Expand Up @@ -2370,6 +2412,8 @@ <h3>Defining elements and attributes</h3>
<section id="markup_identifiers" class="subtopic">
<h3>Defining identifiers</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Amarkup_identifiers" target="_blank">See related review comments.</a></p>

<p>A common feature of document formats is the definition of various identifiers. This includes reserved keywords as well as user-defined values. To foster interoperability, implementations need to be able to match identifier values reliably and consistently. For a detailed look at this problem, see <cite>Character Model: String Matching</cite> [[CHARMOD-NORM]].</p>

<div class="req" id="identifier_content_internal_id">
Expand Down Expand Up @@ -2501,6 +2545,8 @@ <h2>Typographic support</h2>
<section id="text_decoration" class="subtopic">
<h3>Text decoration</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Atext_decoration" target="_blank">See related review comments.</a></p>

<aside class="links" id="links_text_decoration">
<p class="links_title">Useful background and overviews for this section</p>
<ul>
Expand Down Expand Up @@ -2615,9 +2661,11 @@ <h3>Setting box positioning coordinates when text direction varies</h3>



<section id="ruby" class="subtopic">
<section id="typ_ruby" class="subtopic">
<h3>Ruby text annotations</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Atyp_ruby" target="_blank">See related review comments.</a></p>

<aside class="links" id="links_ruby">
<p class="links_title">Useful background and overviews for this section</p>
<ul>
Expand Down Expand Up @@ -2660,6 +2708,8 @@ <h3>Ruby text annotations</h3>
<section id="typ_misc" class="subtopic">
<h3>Miscellaneous</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Atyp_misc" target="_blank">See related review comments.</a></p>

<div class="req" id="type_line_height">
<p class="advisement">Line heights must allow for characters that are taller than English.</p>
</div>
Expand Down Expand Up @@ -2755,6 +2805,8 @@ <h3>Working with locale-affected values</h3>
<section id="loc_time" class="subtopic">
<h3>Working with time</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Aloc_time" target="_blank">See related review comments.</a></p>


<div class="req" id="loc_time_preCE">
<p class="advisement">When defining calendar and date systems, be sure to allow for dates prior to the common era, or at least define handling of dates outside the most common range.</p>
Expand Down Expand Up @@ -2816,6 +2868,8 @@ <h3>Working with time</h3>
<section id="loc_names" class="subtopic">
<h3>Working with personal names</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Aloc_names" target="_blank">See related review comments.</a></p>


<p>Developers who create applications that use personal names (in web forms, databases, ontologies, and so forth) are often unaware of how different names can be in other countries. They build their forms or databases in a way that assumes too much on the part of foreign users. This section provides guidelines for working with personal names from around the world.</p>
<aside class="links" id="links_loc_names">
Expand Down Expand Up @@ -3208,6 +3262,8 @@ <h2>Navigation</h2>
<section id="lang_negotiation" class="subtopic">
<h3>Providing for content negotiation based on language</h3>

<p class="reviewComments"><a href="https://github.com/w3c/i18n-activity/labels/t%3Alang_negotiation" target="_blank">See related review comments.</a></p>

<div class="req" id="lang_neg">
<p class="advisement">In a multilingual environment it must be possible for the user to receive text in the language they prefer. This may depend on implicit user preferences based on the user's system or browser setup, or on user settings explicitly negotiated with the user.</p>
</div>
Expand All @@ -3219,7 +3275,8 @@ <h3>Providing for content negotiation based on language</h3>
<h2> Revision Log</h2>
<p>The following summarises substantive changes since the previous publication, but the material is still subject to significant flux as it develops. This should not be a reason not to use the document. What it so far contains is useful, and any shortfalls can be reported or discussed.</p>
<ol>
<li>The checklist generator tool was moved to the top of the document.</li>
<li>Links were added below section headings that point to lists of review comments related to that section. These comments provide details useful to developers and reviewers.</li>
<li>The checklist generator tool was moved to the top of the document.</li>
<li>The table of contents now reports 3 levels of heading.</li>
<li>Lists of links to documents that provide useful background or an overview of a section have been moved to the start of that section. So also have 'see also' links.</li>
<li>Each advisement now carries its own set of links. This makes the links more relevant and more easily noticeable. It also makes it easier to list multiple links, and because the links indicate the target document title, readers do not have to follow the link to know whether they have already read the document pointed to.</li>
Expand Down
11 changes: 10 additions & 1 deletion local.css
View file
Expand Up @@ -376,4 +376,13 @@ aside h4 {
.dumpBox {
width: 100%;
height: 400px;
}
}

.reviewComments {
font-size: 90%;
padding: 1em;
background-color: #EFEFF9;
border-radius: 5px;
margin-block: 0;
font-style: italic;
}

0 comments on commit 390a096

Please sign in to comment.