csswg-drafts/css-module-bikeshed/Overview.bs at 8fa7adc286c6d928372a67637a4dd1a41927430a · w3c/csswg-drafts · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
<pre class='metadata'>
Title: CSS Foo Module Level 1
Shortname: css-foo
Level: 1
Status: ED
Group: csswg
TR: https://www.w3.org/TR/css-foo/
ED: https://drafts.csswg.org/css-foo/
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.
</pre>

Introduction {#intro}
=====================

	<em>This section is not normative.</em>

	Due to the need to have example specifications,
	the CSS community found a great need to have a 'foo' property.
	This specifications addresses this need in
	a very simply way.
	While it provides a very limited set of features for authors,
	it effectively demonstrates how to write a CSS specification.

Sample section {#sample-topic}
==============================

	Look at the mark-up in this section for examples.
	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 [[HTML]] (note the double square brackets in the source).
	To make a normative reference,
	insert a “!”, like this:
	[[!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=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 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 <{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 lang-css">
		EM { font-style: italic }
	</pre>

	CSS examples that need extra text need a DIV.

	<div class=example>
		The following example is the same as the previous one,
		but now it is explained:

		<pre class="lang-css">EM { font-style: italic }</pre>
	</div>

	Illegal CSS examples (examples of errors) are the same,
	but with class "illegal example".
	Examples of HTML and XML code have class "html" and "xml" respectively,
	but are otherwise ditto.

	A formal definition of a property looks like this:

Internal display model: the 'foo' property {#the-foo-property}
--------------------------------------------------------------

	<pre class='propdef'>
		Name: foo
		Value: inline-inside | block-inside | table | ruby | icon
		Initial: text
		Applies to: all elements
		Inherited: no
		Percentages: n/a
		Media: visual
		Computed value: specified value
		Animatable: no
		Canonical order: per grammar
	</pre>

	<dl dfn-type="value" dfn-for="foo">
		<dt><dfn>value-name</dfn>
		<dd>
			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>

	<dfn>Cross-references</dfn> are created by enclosing a term or phrase in &lt;dfn>
	(like the word <a>cross-references</a> earlier in this sentence).
	Then an &lt;a> without an <code>href=""</code> attribute
	with the same text content will automatically be linked.
	Both &lt;dfn>s and &lt;a>s are typed,
	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 {{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:

	<figure>
		<img src="corner.png" alt="A table with a caption above it; both have margins and the margins between them are collapsed, as is normal for vertical margins.">

		<figcaption>
			Just a random image.
			Use SVG if you can.
			Otherwise, W3C prefers PNG over GIF (obviously, since PNG is a W3C Rec).
		</figcaption>
	</figure>

	Don't forget to write the alt.

	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 <code class=lang-html>class="issue"</code> on an element,
	or begin a paragraph with &ldquo;Issue:&rdquo;.

	Issue:
	Inline issues will be copied into an <a href="#issues-index">Issues Index</a> at the end of the document,
	for easy reference.

	<pre class='idl'>
		/* Write WebIDL in a &lt;pre class="idl"> as plain text. */
		interface Foo {
			readonly attribute CSSOMString bar;
			boolean baz(FooDict Arg1, (CSSOMString or Foo) Arg2);
		};

		dictionary FooDict {
			sequence&lt;Foo> foos;
			boolean bar;
			CSSOMString baz = "qux";
		};
	</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>

(A required descriptor can use `Initial: n/a</code>.)

<h2 class=no-num id=priv-sec>Privacy and Security Considerations</h2>

Issue: Make some considerations about privacy and security.