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.
+The i18n WG works with 3 main types of page: article pages, site pages such as this one, and respec documents. They each use different javascript and style files.
If you have comments or suggestions about how to improve this page, feel free to raise a Github issue.
See also the guidelines for working with github.
Editorial guidelines for i18n docs
General principles for editing HTML
You should always bear in mind the following when creating content:
-
-
- HTML pages much always be valid! Use the W3C validator. +
- HTML pages must always be valid! Use the W3C validator.
- Use HTML5 markup.
- HTML pages must always use the UTF-8 character encoding, and this encoding should be declared at the top of the file.
- HTML pages must also always declare the language of the document as a whole using a
langattribute in thehtmltag. A range of text in another language inside the document should be tagged for language too, using thelangattribute.
@@ -90,31 +91,98 @@ - javascript/doc-structure/article-2022.js +
- javascript/articletoc-2022.js +
- style/article-2022.css +
- /i18n-drafts/javascript/doc-structure/sitepage.js +
- /i18n-drafts/javascript/articletoc-html5.js +
- /i18n-drafts/style/sitepage-2016.css +
General principles for editing HTML
General markup guidelines
- -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, just use an empty a element, with href pointing to the id of the figure element, eg. <a href="#figure_id"></a>. Respec will automatically add the figure number to the link text when the page is displayed.
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.
General markup guidelines
+ + + +Javascript & CSS files
+ +New articles must include the following:
+ +-
+
New site pages must include the following:
+ +-
+
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 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.
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> +Headings
+ +Do not supply numbering for section headings. These will be provided automatically by scripting.
+ +An
+ +h1..h6element should be used for headings, and should always be a direct child of asectionelement. Thesectionelement should have anid. 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 to quickly find section headings. Use the styling suggested below in your local.css file in order to open up the space between sections.
-To refer to a section from the text, just use an empty
+ +aelement, withhrefpointing to theidof thesectionelement, eg.<a href="#section_id"></a>. Respec will automatically add the section number and heading to the link text when the page is displayed.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.
+ +To refer to a section from the text
+ +In Respec: use
+ +[[[section_id]]], where section_id is the id of the section you are pointing to. (An alternative is to use<a href="#section_id"></a>, but the previous approach is better because you are able to see the id in wysiwyg source or if the link fails.)In i18n articles: use
+ +<a class="secref">section_id</a>, where section_id is the id of the section you are pointing to. (Only works with articles that use the latest javascript includes.)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.
+
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.