Editorial guidelines for i18n docs

Javascript & CSS files

New articles must include the following:

1. javascript/doc-structure/article-2022.js
2. javascript/articletoc-2022.js
3. style/article-2022.css

New site pages must include the following:

1. /i18n-drafts/javascript/doc-structure/sitepage-2022.js
2. /i18n-drafts/javascript/articletoc-2022.js
3. /i18n-drafts/style/sitepage-2022.css

New articles and site pages with syntax highlighting must include the following:

1. javascript/prism.js
2. style/prism.css

We use relative links so that pages can be viewed without an internet connection.

Respec provides the appropriate scripting and styling when working in that context.

Source code

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.

Headings

Do not supply numbering for section headings. These will be provided automatically by scripting.

An h1..h6 element should be used for headings, and should always be a direct child of a section element. The section element should have an id. The h* element should not have a link around the heading (self links are added automatically by scripting).

<section id="mylinkid">
<h3>My header text</h3>
...
</section>

The current styling for TR documents makes it often difficult for readers to quickly find section headings. Use the styling suggested below in your local.css file in order to open up the space between sections.

Figures

Put pictures, tables, examples, and the like in figure markup. Use the figcaption element when you want a caption. (Caption use is encouraged.)

To refer to a figure from the text

In Respec: use [[[#figure_id]]], where figure_id is the id of the figure you are pointing to. (An alternative is to use <a href="#figure_id"></a>, but the previous approach is better because you are able to see the id in wysiwyg source.)

In i18n articles: use <a class="figref">figure_id</a>, where figure_id is the id of the figure you are pointing to. (Only works with articles that use the latest javascript includes.)

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.

Notes

To create a block-type note add class="note" to the paragraph if a single para note, or use a div class="note" around the note if it contains multiple paras or blocks.

For editor's notes, put class="issue" on a p, div or span around the text you want to be the editor's note.

Run-in headings

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.

<span class="leadin">highlighted text goes here</span> Rest of paragraph follows...

Abbreviations and acronyms

Use the abbr element for both of these. Spell out the full form in the title attribute.

Syntax highlighting

In Respec: use triple-backticks to create code blocks.

```css
p { color: red }
```

In i18n articles and site pages: use a pre element with a code element inside to mark up a code block for syntax highlighting, like so:

<pre><code class="language-css">p { color: red }</code></pre>

Inline code snippets are done like this:

<code class="language-css">p { color: red }</code>

Note: you have to escape all < and & characters inside code elements (code blocks and inline snippets) with < and & respectively. If you have large portions of HTML code, you can use the Unicode code converter to escape these characters.

Lists

A colon should be used for a sentence that leads into the list.

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.

Example:

Otherwise, each list element should begin with an uppercase letter and end with a full stop.

Example

Change markup

To show changes to the text use ins and del. 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.

Codepoints

Use the following markup to represent a character. For certain languages, it may be necessary to style the bdi element with a font-family and font-size.

<span class="codepoint" translate="no"><bdi lang="XX">&#xXXXX;</bdi><code class="uname">U+XXXX UNICODE_CHARACTER_NAME</code></span>

For example:

<span class="codepoint" translate="no"><bdi lang="en">&#x00E9;</bdi><code class="uname">U+00E9 LATIN SMALL LETTER E WITH ACUTE</code></span>

That will produce: éU+00E9 LATIN SMALL LETTER E WITH ACUTE.

The easiest way to create this markup is to choose an appropriate character app, type or paste the character in the large box, and click on Character markup. Then click on the icon to the right to copy the result to your clipboard. Note that the character app can also convert characters to NFD using the control lower down the page.

A similar approach can be used for character sequences (and can also be produced easily using the character apps). The normal pattern is:

<span class="codepoint" translate="no"><bdi lang="XX">&#xXXXX;&#xYYYY;</bdi><code class="uname">U+XXXX UNICODE_CHARACTER_NAME</code> + <code class="uname">U+YYYY UNICODE_CHARACTER_NAME</code></span>

For example:

<span class="codepoint" translate="no"><bdi lang="fr">&#x0065;&#x0301;</bdi><code class="uname">U+0065 LATIN SMALL LETTER E</code> + <code class="uname">U+0301 COMBINING ACUTE ACCENT</code></span>

That will produce: éU+0065 LATIN SMALL LETTER E + U+0301 COMBINING ACUTE ACCENT.

When referring to an invisible character you may want to simply omit the bdi element, or you can use an image. The image should be stored in a local directory. It is important to style the size of the image, so that it fits inline (especially when using an SVG image). The default style sheet applies a height of 1.6em, but this can be changed inline where needed.

<span class="codepoint" translate="no"><img alt="NBSP" src="images/00A0.png"><code class="uname">U+00A0 N0-BREAK SPACE</code></span>

That will produce: U+00A0 N0-BREAK SPACE.

Other inline markup

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).

If you use b or i tags, use a class name with them, so that semantically different usages can be styled differently (esp. for documents with translations!).

Suggested styling for local.css

The following styles can be used as the base for the local.css file. They contain style rules for the approaches mentioned in this styleguide.

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%; 
    }
.codepoint bdi {
  line-height: 1em;
  font-size: 1.25em;
	padding-inline: 0.25em;
	}
.codepoint img {
	height: 2em;
	margin-inline: 0.25em;
	vertical-align: bottom;
	}
.uname {
	font-family: Arial, monospace;
	font-size: 0.75em;                    
	letter-spacing: 0.03em;
	color: brown;
  }

Creating a new article

To create a new article take an existing page's code as a template and modify it as needed.