-
Notifications
You must be signed in to change notification settings - Fork 22
/
editing.html
477 lines (402 loc) · 21.2 KB
/
editing.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Editorial guidelines for i18n docs</title>
<meta name="description" content="Helps members of the W3C Internationalization Activity work with GitHub." />
<script>
var f = { }
// AUTHORS should fill in these assignments:
f.directory = 'guidelines'+'/'; // the path to this file, not including /International or the file name
f.filename = 'github'; // the file name WITHOUT extensions
f.authors = 'Richard Ishida, W3C'; // author(s) and affiliations
f.previousauthors = ''; // as above
f.modifiers = ''; // people making substantive changes, and their affiliation
f.searchString = 'level2-github'; // blog search string - usually the filename without extensions
f.firstPubDate = '2015-12-16'; // date of the first publication of the document (after review)
f.lastSubstUpdate = { date:'2016-10-11', time:'07:50'} // date and time of latest substantive changes to this document
f.status = 'notreviewed'; // should be one of draft, review, published, notreviewed or obsolete
f.path = '../' // what you need to prepend to a URL to get to the /International directory
// AUTHORS AND TRANSLATORS should fill in these assignments:
f.thisVersion = { date:'2021-04-27', time:'12:18'} // date and time of latest edits to this document/translation
f.contributors = ''; // people providing useful contributions or feedback during review or at other times
// also make sure that the lang attribute on the html tag is correct!
// TRANSLATORS should fill in these assignments:
f.translators = 'xxxNAME, ORG'; // translator(s) and their affiliation - a elements allowed, but use double quotes for attributes
f.breadcrumb = '';
f.additionalLinks = ''
</script>
<script src="file-data/translations.js"> </script>
<script src="../../i18n-drafts/javascript/doc-structure/article-dt.js"> </script>
<script src="../../i18n-drafts/javascript/boilerplate-text/boilerplate-en.js"></script><!--TRANSLATORS must change -en to the subtag for their language!-->
<script src="../../i18n-drafts/javascript/doc-structure/sitepage.js"> </script>
<script src="../../i18n-drafts/javascript/articletoc-html5.js"></script>
<link rel="stylesheet" href="../../i18n-drafts/style/sitepage-2016.css" />
<style>
table { border-collapse: collapse; }
th, td { text-align: start; }
table tr { border-bottom: 1px solid #ddd; }
table td {
padding: .75em .25em .75em .25em;
vertical-align: top;
}
</style>
<link rel="copyright" href="#copyright"/>
</head>
<body>
<header>
<nav id="mainNavigation"></nav><script>document.getElementById('mainNavigation').innerHTML = mainNavigation</script>
</header>
<h1>Editorial guidelines for i18n docs</h1>
<section id="sidebarExtras">
</section>
<div id="mainLayout">
<section>
<p>The W3C Internationalization Activity uses github for document development. This page provides guidelines to help people contribute content that matches the standard styling and keeps the documents in a state that keeps the publication process straightforward.</p>
<p>The i18n WG works with 3 main types of page: <a href="https://www.w3.org/International/articlelist">article pages</a>, site pages such as this one, and respec documents. They each use different javascript and style files.</p>
<p>If you have comments or suggestions about how to improve this page, feel free to <a href="https://github.com/w3c/i18n-activity/issues">raise a Github issue</a>.</p>
<p>See also the <a href="github">guidelines for working with github</a>.</p>
</section>
<section id="general">
<h2><a href="#general">General principles for editing HTML</a></h2>
<p>You should always bear in mind the following when creating content:</p>
<ul>
<li>HTML pages must <strong>always be valid</strong>! Use the <a href="https://validator.w3.org/">W3C validator</a>.</li>
<li><strong>Use HTML5</strong> markup.</li>
<li>HTML pages must always <strong>use the UTF-8 character encoding</strong>, and this encoding should be declared at the top of the file.</li>
<li>HTML pages must also always <strong>declare the language</strong> of the document as a whole using a <code class="kw" translate="no">lang</code> attribute in the <code class="kw" translate="no">html</code> tag. A range of text in another language inside the document should be tagged for language too, using the <code class="kw" translate="no">lang</code> attribute.</li>
<li>When using bidirectional script content, always <strong>wrap all opposite-direction phrases</strong> in markup using a <code class="kw" translate="no">dir</code> attribute.</li>
<li>When committing changes, <strong>use clear and simple descriptions of changes</strong>. It should be possible to use the commit list as a change log for the document, so think in these terms when wording the initial line of your commit.</li>
</ul>
<p>We recommend adding the standard i18n CSS rules in a file called <code class="kw" translate="no">local.css</code>. These rules can be <a href="#localcss">found below</a>.</p>
<p><strong>Important: </strong>Only make minimal changes to the source code. If you commit an update that has lots of formatting changes in the source code, it obscures the actual substantive changes in the github diff. You must use an editor that doesn't automatically re-layout the source text each time you make changes. If you do want to tidy the source text, do so as a separate commit, with no substantive changes applied, and describe the commit so that people are aware that it is just a source tidy.</p>
<!--p>Editors should also be aware of the information in the <a href="https://www.w3.org/International/docs/styleguide">style guide</a>.</p-->
</section>
<section id="othermarkup">
<h2><a href="#othermarkup">General markup guidelines</a></h2>
<section id="files">
<h3><a href="#files">Javascript & CSS files</a></h3>
<p>New articles must include the following:</p>
<ol>
<li>javascript/doc-structure/article-2022.js</li>
<li>javascript/articletoc-2022.js</li>
<li>style/article-2022.css</li>
</ol>
<p>New site pages must include the following:</p>
<ol>
<li>/i18n-drafts/javascript/doc-structure/sitepage.js</li>
<li>/i18n-drafts/javascript/articletoc-html5.js</li>
<li>/i18n-drafts/style/sitepage-2016.css</li>
</ol>
<p>We use relative links so that pages can be viewed without an internet connection.</p>
<p>Respec provides the appropriate scripting and styling when working in that context.</p>
</section>
<section id="sourcecode">
<h3><a href="#sourcecode">Source code</a></h3>
<p>It isn't required, but it's easier to find things in the source code if you leave several blank lines before each section tag, and single blank lines between block elements such as p, figure, blockquote, etc.</p>
</section>
<section id="headings">
<h3><a href="#headings">Headings</a></h3>
<p>Do not supply numbering for section headings. These will be provided automatically by scripting.</p>
<p>An <code class="kw" translate="no">h1</code>..<code class="kw" translate="no">h6</code> element should be used for headings, and should always be a direct child of a <code class="kw" translate="no">section</code> element. The <code class="kw" translate="no">section</code> element should have an <code class="kw" translate="no">id</code>. The h* element should not have a link around the heading (self links are added automatically by scripting).</p>
<pre id="line1"><section id="mylinkid">
<h3>My header text</h3>
...
</section></pre>
<p>The current styling for TR documents makes it often difficult for readers to quickly find section headings. Use the <a href="#css">styling suggested below</a> in your local.css file in order to open up the space between sections.</p>
<h4>To refer to a section from the text</h4>
<p><span class="leadin">In Respec:</span> use<code>[[[section_id]]]</code>, where section_id is the id of the section you are pointing to. (An alternative is to use <code><a href="#section_id"></a></code>, but the previous approach is better because you are able to see the id in wysiwyg source or if the link fails.)</p>
<p><span class="leadin">In i18n articles:</span> use <code><a class="secref">section_id</a></code>, where section_id is the id of the section you are pointing to. (Only works with articles that use the latest javascript includes.)</p>
<p>The paragraph containing the pointer will be updated automatically with a link to the section you are pointing to, and the link text will be the section heading.</p>
</section>
<section id="figures">
<h3><a href="#figures">Figures</a></h3>
<p>Put pictures, tables, examples, and the like in <code class="kw" translate="no">figure</code> markup. Use the <code class="kw" translate="no">figcaption</code> element when you want a caption. (Caption use is encouraged.)</p>
<h4>To refer to a <code class="kw" translate="no">figure</code> from the text</h4>
<p><span class="leadin">In Respec:</span> use <code>[[[figure_id]]]</code>, where figure_id is the id of the figure you are pointing to. (An alternative is to use <code><a href="#figure_id"></a></code>, but the previous approach is better because you are able to see the id in wysiwyg source.)</p>
<p><span class="leadin">In i18n articles:</span> use <code><a class="figref">figure_id</a></code>, where figure_id is the id of the figure you are pointing to. (Only works with articles that use the latest javascript includes.)</p>
<p>In both cases, the markup will be replaced by a link to 'Figure XX' when the page is viewed. The Figure number will be updated automatically as new figures are added.</p>
</section>
<section id="notes">
<h3><a href="#notes">Notes</a></h3>
<p>To create a block-type note add <code>class="note"</code> to the paragraph if a single para note, or use a <code>div class="note"</code> around the note if it contains multiple paras or blocks.</p>
<p>For editor's notes, put <code>class="issue"</code> on a <code class="kw" translate="no">p</code>, <code class="kw" translate="no">div</code> or <code class="kw" translate="no">span</code> around the text you want to be the editor's note.</p>
</section>
<!--div class="section">
<h3><a name="graphics" id="graphics">Graphics, tables and figures</a></h3>
<p>The implementation of graphics deviates slightly from XMLSpec standard usage. A <code>figure</code> element has also been provided.</p>
<p>All tables and all non-inline pictures should be enclosed in a <code>figure</code> element <em>after</em> the preceding paragraph. </p>
<p>In the generated XHTML, figures can have a caption. If, and only if, a caption is supplied, it will start with "Figure X: " in the XTHML,
where X is the sequential number of the figure in the document. The text "Figure X: " is generated by the XSLT, and you must not add that to the XML.
The use of captions is encouraged.</p>
<p>You should always provide a value for the id attribute, on the <span class="kw">example</span> element (not the head). (See
<a href="#example-ref">how to refer to figures</a> from the text.)</p>
<p>All graphic images included in the text, whether in a figure or within a paragraph, should be created with an <code>image</code> element.
The <span>graphic</span> element that comes with xmlspec must not be used. The <code>image</code> element has two children, <code>img</code> and
<code>alt</code>. <code>img</code> has attributes <code>width</code> and <code>height</code> and you are encouraged to use them; <code>img</code> has
no <code>alt</code> attribute, since an <code>alt</code> <em>element</em> is provided as a child of <code>image</code>. This approach assists
translators, but also allows the alt text to be marked up (eg. with bidi or language information, or <code>ins</code> or <code>del</code> tags). You
should always provide alt text.</p>
<p>All graphics files should be stored in the <code>images</code> directory (eg. the <code>source</code> attribute would point to
<code>images/graphicName.gif</code>).</p>
<p>Note that alt text should describe the picture so that someone unable to see it can derive the same conclusions as someone who can. This
generally means describing the point being made by the picture rather than the visual elements.</p></div-->
<section id="leadin">
<h3><a href="#leadin">Run-in headings</a></h3>
<p>Sometimes it's not necessary to create a new section and heading,
but you may want to highlight a word or sentence at the start of a
series of paragraphs. To do this, use the following markup.</p>
<pre><span class="leadin">highlighted text goes here</span> Rest of paragraph follows...</pre>
</section>
<section id="abbrevs">
<h3><a href="#abbrevs">Abbreviations and acronyms</a></h3>
<p>Use the <span class="kw"><code class="kw" translate="no">abbr</code></span> element for both of these. Spell out the full form in the <span class="kw"><code class="kw" translate="no">title</code></span> attribute.</p>
</section>
<section id="lists">
<h3><a href="#lists">Lists</a></h3>
<p>A colon should be used for a sentence that leads into the list.</p>
<p>If a list is expressed as a single sentence each list item should
begin with a lower case letter and end with a comma or ", and".
The
last list item should end with a full stop.</p>
<p>Example:</p>
<div class="example">
<p>Every W3C specification <span class="rfc2119">MUST</span>:</p>
<ol>
<li>conform to the requirements applicable to specifications, </li>
<li>specify that implementations MUST conform to the requirements applicable to software, and </li>
<li>specify that content created according to that specification MUST conform to the requirements applicable to content.</li>
</ol>
</div>
<p>Otherwise, each list element should begin with an uppercase letter and end with a full stop.</p>
<p>Example</p>
<div class="example">
<p>Some aspects of Unicode that require additional specification for the Web include:</p>
<ul>
<li>Choice of encoding forms (UTF-8, UTF-16, UTF-32). </li>
<li>Counting characters, measuring string length in the presence of variable-length encodings and combining characters). </li>
<li>Duplicate encodings (e.g. precomposed vs decomposed). </li>
<li>Use of control codes for various purposes (e.g. bidirectionality control, symmetric swapping, etc.).</li>
</ul>
</div>
</section>
<section id="changes">
<h3><a href="#changes">Change markup</a></h3>
<p>To show changes to the text use <code class="kw" translate="no">ins</code> and <code class="kw" translate="no">del</code>. However, remember that if you do commits carefully, such markup is not needed. People will be able to see the changes by looking at the diff for the commit on the Github site.</p>
</section>
</section>
<section id="inline">
<h2><a href="#inline">Marking up inline content</a></h2>
<p>The following table suggests conventions for marking up inline
content. The presentation column applies to the
English version. Any translated version may change the presentation
(eg. a Japanese version may substitute underlining for bold).</p>
<table>
<thead>
<tr>
<th>Type of in-line content</th>
<th>Example</th>
<th>Markup to use</th>
</tr>
</thead>
<tbody>
<tr>
<td>emphasis (general)</td>
<td>In keyboard input it is <em>not</em> always the case that...</td>
<td>em</td>
</tr>
<tr>
<td>emphasis (stronger)</td>
<td>you must <strong>absolutely not</strong> do that!</td>
<td>strong</td>
</tr>
<tr>
<td>new term introduction</td>
<td>The set of characters is called a <dfn>repertoire</dfn>.</td>
<td>dfn id="def_<termName>" title="<termName>"</td>
</tr>
<tr>
<td>reference to a term definition</td>
<td>The <a class="termref" href="#def_repertoire">repertoire</a> of UTF-8 includes all characters you're likely to need.</td>
<td>a class="termref" href="#def_<termName>"</td>
</tr>
<tr>
<td>document title</td>
<td>see <cite>Requirements for String Identity Matching</cite>.</td>
<td>cite</td>
</tr>
<tr>
<td>quoted term</td>
<td>The word <span class="qterm">character</span> is used in many contexts.</td>
<td>span class="qterm"</td>
</tr>
<tr>
<td>quoted term / phrase expressing dubious usage</td>
<td>ie. numeric <span class="quote">positions</span> within a string</td>
<td>span class="quote"</td>
</tr>
<tr>
<td>quoted text</td>
<td>such as <q>...as it may from time to time be revised or amended.</q></td>
<td>q</td>
</tr>
<tr>
<td>quoted character (refers to typically one, but occasionally more, specific characters).</td>
<td>The character <span class="qchar">ç</span> is common in French.</td>
<td>span class="qchar"</td>
</tr>
<tr>
<td>quoted sample output (cf. HTML SAMP)</td>
<td>The string <samp>artículo</samp> is subject to different representations</td>
<td>samp</td>
</tr>
<tr>
<td>quoted code</td>
<td><code>suc&#xE7;on</code></td>
<td>code translate="no"</td>
</tr>
<tr>
<td>quoted keyboard input (cf. HTML KBD)</td>
<td>a user typing <kbd>çé</kbd> on a traditional French-Canadian keyboard</td>
<td>kbd</td>
</tr>
<tr>
<td>element name</td>
<td>a user agent that looks for <code class="name">artículo</code> elements</td>
<td>span class="el" translate="no"</td>
</tr>
<tr>
<td>attribute name or value</td>
<td>the <code class="kw" translate="no">section</code> element</td>
<td>code class="kw" translate="no"</td>
</tr>
<tr>
<td>function name</td>
<td>The <code class="kw" translate="no">doit</code> function returns interesting results.</td>
<td>code class="kw" translate="no"</td>
</tr>
<tr>
<td>key word in a markup or programming language</td>
<td>the IANA <code class="kw" translate="no">charset</code> value</td>
<td>code class="kw" translate="no"</td>
</tr>
<tr>
<td>variable name</td>
<td></td>
<td>var</td>
</tr>
<tr>
<td>conformance related word based on rfc2119</td>
<td>All references to Unicode <span class="rfc2119">MUST</span> refer to...</td>
<td>span class="rfc2119"</td>
</tr>
<tr>
<td>acronyms & abbreviations</td>
<td>More and more <abbr title="Application Programming Interface">API</abbr>s are defined,</td>
<td> abbr title="..."</td>
</tr>
<tr>
<td>Unicode name</td>
<td>Use <span class="uname">U+0338 COMBINING LONG SOLIDUS OVERLAY</span> for that.</td>
<td>span class="uname"</td>
</tr>
<tr>
<td>an URL that doesn't have a link on it</td>
<td>https://github.com/w3c/repoName/</td>
<td><span class="url">https://github.com/w3c/repoName/</span></td>
</tr>
</tbody>
</table>
<p>If you use <code class="kw" translate="no">b</code> or <code class="kw" translate="no">i</code> tags, use a class name with them, so that semantically different
usages can be styled differently (esp. for documents with
translations!).</p>
</section>
<section id="localcss">
<h2><a href="#localcss">Suggested styling for local.css</a></h2>
<p>The following styles can be used as the base for the <code class="kw" translate="no">local.css</code> file. They contain style rules for the approaches mentioned in this styleguide.</p>
<pre>h2 {
margin-top: 3em;
margin-bottom: 0em;
}
.head h2, #abstract h2, #sotd h2 {
margin-top: 0;
}
h3 {
margin-top: 3em;
}
h4 {
font-size: 100%;
font-weight: normal;
color: #005a9c;
margin-top: 2em;
}
.leadin {
font-weight: bold;
}
ins {
background-color: #99FF99;
text-decoration: none;
}
del {
display: inline;
color: silver;
}
figure {
margin-bottom: 2em;
text-align: center;
}
figcaption {
text-align: center;
margin: 0.5em 2em;
font-style: italic;
font-size: 90%;
}
.figno:after {
content: ':\00A0 ';
}
a.termref:link {
color:#C60;
text-decoration:none;
border-bottom: 1px dotted #FC0;
}
a.termref:hover {
color:#C60;
text-decoration:none;
border-bottom: 1px dotted #FC0;
}
a.termref:visited {
color:#C60;
text-decoration:none;
border-bottom: 1px dotted #FC0;
}
a.termref:active {
color:#C60;
text-decoration:none;
border-bottom: 1px dotted #FC0;
}
.qterm:before, .qchar:before { content: "'"; }
.qterm:after, .qchar:after { content: "'"; }
.quote:before { content: '"'; }
.quote:after { content: '"'; }
code {
color: #A52A2A;
font-family: Consolas, "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", Monaco, "Courier New", monospace;
font-size: 100%;
}
samp, kbd {
font-family: Consolas, "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", Monaco, "Courier New", monospace;
font-size: 100%;
}
.uname {
text-transform: uppercase;
font-size: 85%;
letter-spacing:0.03em;
}
</pre>
</section>
</div>
<br style="clear: both;" />
<footer id="thefooter"></footer><script>document.getElementById('thefooter').innerHTML = g.bottomOfPage</script>
<script>completePage()</script>
</body>
</html>