[css-module-bikeshed] Fix some markup, and add more examples.

Author: tabatkins

css-module-bikeshed/Overview.bs

@@ -1,6 +1,5 @@
-<h1>CSS Foo Module Level N</h1>
-
 <pre class='metadata'>
+Title: CSS Foo Module Level 1
 Shortname: css-foo
 Level: 1
 Status: ED
@@ -11,7 +10,6 @@ Work Status: exploring
 Editor: Name1, Company1, http://example.com/contact
 Editor: Name2, Company2, name2@example.com
 Abstract: This module introduces the 'foo' property and related values, which do bar and baz.
-Ignored Terms: div, dl, dfn
 </pre>
 
 Introduction {#intro}
@@ -33,41 +31,57 @@ Sample section {#sample-topic}
 	See the <a href="https://github.com/tabatkins/bikeshed/blob/master/README.md">documentation</a> for more precise instructions.
 	The companion of this template shows the <a href="Overview.html">processed result</a>.
 
-	To refer to HTML, use [[HTML40]] (note the double square brackets in the source).
+	To refer to HTML, use [[HTML]] (note the double square brackets in the source).
 	To make a normative reference,
 	insert a “!”, like this:
-	[[!CSS3SYN]]
+	[[!CSS-SYNTAX-3]]
 	The currently available <a href="https://www.w3.org/Style/Group/css3-src/biblio.ref">list of bibliographic data</a> can of course be extended.
 
 	We write about a property such as 'foo' like this
 	and about a piece of CSS code like this: ''foo: bar''.
 	(Note that if it looks like a "property: value",
 	it'll automatically link to the property.)
 	Inline HTML and XML are similar,
-	but use the CODE element: <code class=html>&lt;blockquote&gt;...&lt;/blockquote&gt;</code>
-	and <code class=xml>&lt;r:xyz&gt;...&lt;/r:xyz&gt;</code>.
+	but use the CODE element: <code class=lang-html>&lt;blockquote&gt;...&lt;/blockquote&gt;</code>
+	and <code class=lang-xml>&lt;r:xyz&gt;...&lt;/r:xyz&gt;</code>.
 
 	Note: Note that the property will automatically be linked to its definition.
 
-	To define <dfn>terms</dfn> into the <dfn id="dfn-index">index</dfn>,
-	there are many <dfn title="variant">variants</dfn>,
-	but hopefully the <dfn title="simple|simpler|simplest">simplest</dfn>
+	To define <dfn export>terms</dfn> into the <dfn export id="dfn-index">index</dfn>,
+	there are many <dfn export lt="variant">variants</dfn>,
+	but hopefully the <dfn export title="simple|simpler|simplest">simplest</dfn>
 	will be the most common.
+	Note that you need to explicitly export any plain <{dfn}>s you want to be linkable from other specs,
+	but all other types of definition automatically export themselves.
 
 	Note: Note that you can add non-normative notes like this.
 
-	Of course, multi-paragraph notes are also possible: just enclose them in a <a element>div</a>:
+	Of course, multi-paragraph notes are also possible: just enclose them in a <{div}>:
 
 	<div class=note>
 		Note that this note is a multi-paragraph note.
 
 		It doesn't <em>need</em> to have two paragraphs, but it could.
 	</div>
 
+	<details class=note>
+		<summary>A longer note</summary>
+
+		When you want to insert a longer note
+		to provide some useful explanation,
+		but the note itself is not critical to the section it's placed in,
+		use a <{details}> note instead.
+
+		This will hide the note by default,
+		so it's less distracting to the flow of the section.
+		(At least, in browsers that support <{details}>;
+		legacy browsers will get something like a normal note.)
+	</details>
+
 	Displayed examples come in eight different types:
 	CSS examples that need no separate paragraph of explanation are put in a simple PRE:
 
-	<pre class=example>
+	<pre class="example lang-css">
 		EM { font-style: italic }
 	</pre>
 
@@ -77,7 +91,7 @@ Sample section {#sample-topic}
 		The following example is the same as the previous one,
 		but now it is explained:
 
-		<pre>EM { font-style: italic }</pre>
+		<pre class="lang-css">EM { font-style: italic }</pre>
 	</div>
 
 	Illegal CSS examples (examples of errors) are the same,
@@ -106,9 +120,9 @@ Internal display model: the 'foo' property {#the-foo-property}
 	<dl dfn-type="value" dfn-for="foo">
 		<dt><dfn>value-name</dfn>
 		<dd>
-			Define values using a <a element>dl</a>.
-			Note that the <a element>dl</a> wrapper
-			specifies the default <a element>dfn</a> type and what property it's for,
+			Define values using a <{dl}>.
+			Note that the <{dl}> wrapper
+			specifies the default <{dfn}> type and what property it's for,
 			so you don't have to repeat that information in each individual definition.
 	</dl>
 
@@ -120,7 +134,9 @@ Internal display model: the 'foo' property {#the-foo-property}
 	which allows the same text to appear as different types of terms without a collision.
 	The type can often be inferred,
 	but sometimes it needs to be specified,
-	like when you're linking to a <a interface>Foo</a> WebIDL interface.
+	like when you're linking to a {{Foo}} WebIDL interface.
+	(Here, we're using the <em>IDL</em> linking shorthand
+	to make it clear that this is one of the IDL types.)
 
 	And a figure with a caption is done like this:
 
@@ -139,7 +155,7 @@ Internal display model: the 'foo' property {#the-foo-property}
 	Issue: An open issue or editorial remark is OK in a WD,
 	but they should be resolved/removed before the document goes to &ldquo;CR&rdquo;
 	(Candidate Recommendation).
-	Use class=&ldquo;issue&rdquo; on an element,
+	Use <code class=lang-html>class="issue"</code> on an element,
 	or begin a paragraph with &ldquo;Issue:&rdquo;.
 
 	Issue:
@@ -160,6 +176,32 @@ Internal display model: the 'foo' property {#the-foo-property}
 		};
 	</pre>
 
+Shorthands and Descriptors {#shorthands}
+----------------------------------------
+
+Shorthand properties have a smaller set of values to provide:
+
+<pre class="propdef shorthand">
+Name: shorthand-foo
+Value: foo | bar | baz
+</pre>
+
+Adding new values to an existing property? Use a partial:
+
+<pre class="propdef partial">
+Name: foo
+New values: another-icon
+</pre>
+
+Or when defining a descriptor, use a descdef block (partials work here, too):
+
+<pre class=descdef>
+Name: descriptor-foo
+Value: more | values
+Initial: values
+For: @some-at-rule
+</pre>
+
 <h2 class=no-num id=priv-sec>Privacy and Security Considerations</h2>
 
 Issue: Make some considerations about privacy and security.