This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revision | Last revisionBoth sides next revision | ||
| spec:markup [2012/03/23 20:44] – [Stage 4: Notes, Issues, Examples, and other Boxen] fantasai | spec:markup [2012/03/23 20:46] – [Stage 4: Notes, Issues, Examples, and other Boxen] fantasai | ||
|---|---|---|---|
| Line 50: | Line 50: | ||
| The CSSWG uses some colored boxes to delineate special types of information. | The CSSWG uses some colored boxes to delineate special types of information. | ||
| - | ; examples | + | ; <div class=" |
| : Examples are non-normative and relatively self-contained. They often, but not always, illustrate a normative definition immediately before the example. They might contain only text; text and code; text and a figure; text, some code, and a figure; or several repetitions of these. They need to be clearly delineated so that readers can tell that the text is non-normative. They are also things authors like to scan for. | : Examples are non-normative and relatively self-contained. They often, but not always, illustrate a normative definition immediately before the example. They might contain only text; text and code; text and a figure; text, some code, and a figure; or several repetitions of these. They need to be clearly delineated so that readers can tell that the text is non-normative. They are also things authors like to scan for. | ||
| - | ; figures | + | ; <div class=" |
| : Like examples, figures are also used to illustrate the normative text (and in some cases are used in informative sections like examples and notes, too!) They usually come with a caption and must have alternative text for non-sighted readers. ([[http:// | : Like examples, figures are also used to illustrate the normative text (and in some cases are used in informative sections like examples and notes, too!) They usually come with a caption and must have alternative text for non-sighted readers. ([[http:// | ||
| - | ; propdef | + | ; <table class=" |
| : Propdef tables contain the critical information for a property definition. They must be easily scannable. ([[http:// | : Propdef tables contain the critical information for a property definition. They must be easily scannable. ([[http:// | ||
| - | ; notes | + | ; <span class=" |
| : Notes are non-normative sentences (inline) or paragraphs (or multi-paragraphs) that help explain the implications of some normative text. It needs to be clear that they are not normative, but they also should not jump out of the text, as they are not something to scan for but a continuation of the normative discussion. [[http:// | : Notes are non-normative sentences (inline) or paragraphs (or multi-paragraphs) that help explain the implications of some normative text. It needs to be clear that they are not normative, but they also should not jump out of the text, as they are not something to scan for but a continuation of the normative discussion. [[http:// | ||
| - | ; grammar boxes | + | ; <pre class=" |
| : These <pre> boxes are typically normative; they unambiguously define the syntax of a feature in code. They often contain a <dfn> defining a grammar production that is reused later. ([[http:// | : These <pre> boxes are typically normative; they unambiguously define the syntax of a feature in code. They often contain a <dfn> defining a grammar production that is reused later. ([[http:// | ||
| + | ; <span class=" | ||
| + | : Issues are notes from the editor to reviewers. They document areas that need more feedback, and explain problems that are as-yet unresolved in the specs. They are used in Working Drafts: CRs and beyond are not supposed to have issues. | ||