Overview.bs

<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.

Value Definitions {#values}
---------------------------

	This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]
	using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].
	Value types not defined in this specification are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].
	Combination with other CSS modules may expand the definitions of these value types.

	In addition to the property-specific values listed in their definitions,
	all properties defined in this specification
	also accept the <a>CSS-wide keywords</a> as their property value.
	For readability they have not been repeated explicitly.

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
		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.