The document must be written and saved in utf-8.
Most links to the W3C site should start with "/" (eg. /International/style/..."). This allows the links to work on a local test server.
ALWAYS check the article for valid XHTML 1.0, run a link checker, a spell checker and a CSS validator before finishing work on it.
You should start an HTML version of an article by using a copy of the template. Note that this is a PHP file, and much of the boilerplate text will be added or generated as the document is served.
The template contains instructions and examples of possible use.
You need to start by filling in the values of several PHP variables at the top of the page. Do not disturb the PHP code otherwise. Things that need to be changed typically contain 'xxx', though there are a few variables that should be left as is and will be used by translators (these are clearly marked).
It is best to create section and paragraphs by taking copies of the example text in the template and adapting, then remove the template example sections at the last minute.
At the end, search for 'xxx' in the source to check that you haven't missed anything that needs attention.
Don't forget to adapt the title element.
Don't forget to adapt the description and keywords meta elements. For FAQ articles, the description usually contains 'W3C i18n FAQ: ' followed by a copy of the text of the question the article is answering. For other articles, use "W3C i18n article: " followed by a very brief description of the article.
Leave the PHP alone that says 'admin will complete this'. This is for linking later to translations of the document.
You can add document-specific styling immediately between "php echo $standardsStylesheet ?>" and "</style>" in the code <style type='text/css' media="all" title="standardsStylesheet"> <?php echo $standardsStylesheet ?> </style>.
No style information should be added to the body or any other element tag. Idiosynchratic styling should appear at the top and be linked to the appropriate tag using an id or class. One exception to this is the placement of page-break rules, added at the end to achieve a reasonable pagination during print.
The contentstart fragment identifier must appear at the beginning of the actual content (see below).
If you add markup to the $additionalLinks variable, it will appear in the sidebar on the right just after the links to the indexes. Each group of information should start with a h2 and be wrapped in a div class="noprint". Normally you will not need to do this. If you do, try not to make this sidebar too long, as it may overlap an area where you want to include a call-out or sidenote. Bear in mind that the first part of the text will always be competing with this sidebar for space for such things, and that as the page flexes the length of the sidebar does also. This is not usually an issue.
Items in the sidebar will often not be relevant for the printed version of the article. Anything wrapped in a div class="noprint" will not be printed.
The h1 heading should have the first letter of all significant words capitalised.
Immediately after the h1 you should have a div class="navigation". Here you provide internal navigation links to the h2 section headings for the document. Delete, add or change links as necessary. This is set up, by default, for an faq, and should rarely need to be changed for such an article.
Note how the link text is kept short, and the title attribute carries more information or the full heading text. Note also that after each </a> there should immediately follow a &xA0; (non-breaking space) and a hyphen, except for the last item in the list. Note also that spaces are replaced by between words inside a link.
Note also the accesskey="n" in the first item for WAI.
(This may be converted to a ul element with li elements in the future, although it will still look the same when displayed.)
You may wish to add a preface before the first section div. If you do so, ensure that you wrap it in its own div class="section", and add the following at the beginning of the text:
<a id="contentstart" name="contentstart"></a>
All non-h1 headings should uppercase only the first letter in the heading. If different casing is to be displayed this should be achieved by the stylesheet.
h2 headings should be the first item inside a div with class="section". h3 headings should be the first item inside a div with class="section2".
The divs described in the previous paragraph should enclose the whole section or subsection that they are related to.
The following table outlines conventions for markup and presentation used for in-line labelling in the document. The presentation used in the examples is typical of the English version, and may be changed by a localized style sheet.
| Type | Example | Markup to use |
|---|---|---|
| emphasis (general) | In keyboard input it is not always the case that ... | em |
| strong emphasis | strong | |
| new term introduction | The set of characters is called a repertoire. | span class="newterm" |
| document title | see Requirements for String Identity Matching. | span class="titleref" |
| quoted term | The word 'character' is used in many contexts. | span class="qterm"surrounded by single quotes (note 1) |
| quoted term / phrase expressing dubious usage | ie. numeric "positions" within a string | span class="quote" surrounded by double quotes |
| quoted text | such as "... as it may from time to time be revised or amended." | span class="quote" surrounded by double quotes |
| quoted character (refers typically to one, but occasionally more, specific characters) | 'ç' | span class="qchar" surrounded by single quotes |
| quoted sample output | The output string "artículo" is subject to different representations. | samp surrounded by double quotes |
| quoted code | match = "p[@class = 'start']" |
code |
| quoted keyboard input | a user typing çé on a traditional French-Canadian keyboard ... | kbd |
| keyword, variable, element, attribute, function name | the link element can be useful for... | span class="kw" |
| conformance word based on rfc2119 | All references to Unicode MUST refer to | span class="rfc2119" and upper case in English |
| acronyms, abbreviations | More and more APIs are defined | abbr with expansion in title attribute |
| Unicode character name | COMBINING LONG SOLIDUS OVERLAY | span class="uname" |
| editorial notes | You should do this or should you?? | span class="ed" |
note 1: In an XML context you should never type in quotation marks. These would be provided by the style sheet. In HTML, however, the markup and styling for dealing with quotation marks is unfortunately not well implemented. For this reason it is regrettably necessary to use quote marks with this markup. You should, however, always put the quote marks immediately on the outside of the span markup.
All language changes should be marked up.
There are a number of additional possibilities that have not yet been implemented:
| Type | Example | Markup to use |
|---|---|---|
| in-document link | tbd | |
| external link | tbd | |
| glossary link | tbd | |
| term definition | tbd | |
| annotation | probably sup |
Do not use any attributes with tables. Use the stylesheet, or create additional styling linked by the id, if necessary.
Tables will currently be displayed left aligned and will flow out into the right margin where necessary. If you wish to indent the table slightly to the right, use a blockquote element.
Tables often require idiosynchratic styling. If this is the case, use the style element at the top of the page, identifying each table or part of a table that needs identification with an id.
It is possible to easily add notes, icons or other items to the right margin using the following method. (You should probably just copy the example in the template and adapt.)
Enclose the paragraph or block element you want the note to appear alongside in a div class="sidenoteGroup". Put the note itself in a div class="sidenote" at the end of the sidenoteGroup div. Extend the sidenoteGroup div to the right amount so that a user without stylesheets enabled or using a voice browser will hear the note at the appropriate point.
Side notes are floated to the right, so take care not to use them too near the top, when they could be moved down by the navigation and links information, or somewhere where they might be overwritten by a table that extends into the margin. It is not easy to give precise information about when that will occur, because of the way text flexes in browsers and from browser to browser, but it is not too difficult to manage.
pre elements will also bleed into the right margin.
The sidebar at the top will typically contain links to the topic index and task index (automatically generated from the PHP variables you give values to). There should typically also be a section at the bottom of the page entitled "Further information".
Try to add links to the Further Reading section that will [1] list sources of the information in the article, and [2] lead the reader on to further detail.
Links in the "Further information" section at the bottom of a page include additional text that is only visible when printed. A typical entry looks as follows:
<li> <p><a href="/International/questions/qa-lang-priorities">FAQ: Setting language preferences in a browser</a> helps you set your language preferences <span class="uri">http://www.w3.org/International/questions/qa-lang-priorities</span> </p> </li>
Version: $Id: article-styleguide.html,v 1.5 2007/11/21 13:06:31 rishida Exp $