Styleguide for i18n TR documents

This document provides guidelines for editors of Rec-track or Note documents edited in HTML in the W3C Internationalization Activity.

Use new tools

Use the respec template to create a new document. This saves a lot of trouble when it comes to publishing the document.

Publish the document in a github repository, and recommend the use of github issues for feedback, rather than email.

Use HTML5 markup.

i18n stuff

The language of W3C specifications is en-US. This should be set on the html element using lang.

The encoding, of course, should always be utf-8.

Local CSS styling

You should declare any CSS that is specific to your document in a file called local.css, in the same directory as Overview.html or index.html.  A set of base styles for local.css, which address the suggestions in this style guide, is listed below.

Feedback instructions

Documents published in a github repository should encourage feedback to be sent via the github issues list for that repo. It is currently not possible to change the generated respec text that points reviewers to an email list, so when providing information for the SoD section in a respec document you should add the following note (adapting the URIs and email addresses):

<div id="sotd">
   ...
<p class="note">If you wish to make comments regarding this document, 
    please <a href="https://github.com/w3c/doc-short-name/issues" style="font-size: 120%;">raise a github issue</a>. 
    If you are unable to use github issues, you may also send
    email to the list mentioned below. Please include <q>[doc-short-name]</q> at the start of your
    email's subject. To make it easier to track comments, please raise
    separate issues or send separate emails for each comment. All comments
    are welcome.</p>
    </div>

You should also add the following line to the Javascript declarations at the top of your respec source text (again, change the URIs to suit):

bugTracker: { new: "https://github.com/w3c/clreq/issues", open: "https://github.com/w3c/clreq/issues" } ,

In-line markup conventions

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

Type of in-line content Example Markup to use
emphasis (general) In keyboard input it is not always the case that... em
emphasis (stronger)you must absolutely not do that! strong
new term introduction The set of characters is called a repertoire. dfn id="def_<termName>" title="<termName>"
reference to a term definition The repertoire of UTF-8 includes all characters you're likely to need. a class="termref" href="#def_<termName>"
document title see Requirements for String Identity Matching. cite
quoted term The word character is used in many contexts. span class="qterm"
quoted term / phrase expressing dubious usage ie. numeric positions within a string span class="quote"
quoted text such as ...as it may from time to time be revised or amended. q
quoted character (refers to typically one, but occasionally more, specific characters). The character ç is common in French. span class="qchar"
quoted sample output (cf. HTML SAMP) The string artículo is subject to different representations samp
quoted code suc&#xE7;on code translate="no"
quoted keyboard input (cf. HTML KBD) a user typing çé on a traditional French-Canadian keyboard kbd
element name a user agent that looks for artículo elements span class="el" translate="no"
attribute name or value the section element code class="kw" translate="no"
function name The doit function returns interesting results.code class="kw" translate="no"
key word in a markup or programming languagethe IANA charset valuecode class="kw" translate="no"
variable name var
conformance related word based on rfc2119 All references to Unicode MUST refer to... span class="rfc2119"
acronyms & abbreviations More and more APIs are defined, abbr title="..."
Unicode name Use U+0338 COMBINING LONG SOLIDUS OVERLAY for that. span class="uname"

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

Figures

Put pictures, tables, examples, and the like in figure markup. Use the figcaption element when you want a caption.

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="ednote" on a p, div or span around the text you want to be the editor's note.

Headings

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

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 to it.

Surround the text of the heading with a link to the id in the section tag, to make it easier to find the id.

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

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

[Add something about how to refer to sections from the text.]

Lead-in text

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

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

Abbreviations and acronyms

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

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:

Every W3C specification MUST:

  1. conform to the requirements applicable to specifications,
  2. specify that implementations MUST conform to the requirements applicable to software, and
  3. specify that content created according to that specification MUST conform to the requirements applicable to content.

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

Example:

Some aspects of Unicode that require additional specification for the Web include:

Change markup

To show changes to the text use ins and del.

Editorial notes

Use class="issue".

Suggested styles for local.css file

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%; 
    }
.uname {
	text-transform: uppercase;
	font-size: 85%;
	letter-spacing:0.03em;
	}


Richard Ishida, 2005-07-17 17:26

Version: $Id: styleguide.html,v 1.4 2005/07/28 11:49:41 rishida Exp $

Previous version of this style guide.