CONVENTIONS

**************
Global structure
***************
* Each .src document should contain head, body, title, and link tags
  to the next .src file to be printed.


* The TOC and Indexes will be generated by the magic scripts of ALH.
  The DTD fragments that appear in the body of the specification will
  have links from attribute names to their definitions. 

* It's ok to use <TABLE>.

* It's ok to include GIF files in the spec.

************
TABLE OF CONTENTS
************
The toc will be generated from H? markup. Headers should not
contain anchors unless those anchors follow a ":". For
example the following is ok:

<h3>Margin properties: <a href="...">, <a href="...></h3>

And "Margin properties" will be replaced by an anchor whose content
is "Margin properties" and a heading number.

************
Properties
************
In source file:

  <!-- #include src=properties/propname.srb -->

The following will be generated:

  <DIV class="propdef">
  <P><a name="propdef-propname" class="propdef-title"><strong>'propname'</strong></a></P>
  <TABLE class="propinfo">
  <TR><TH>Property name:<TD>
      <span title="propname" class="index-def">'propname'</span></TR>
  <TR><TH>Value:<TD>...</TR>
  <TR><TH>Initial:<TD>...</TR>
  <TR><TH>Applies to:<TD>...</TR>
  <TR><TH>Inherited:<TD>...</TR>
  <TR><TH>Percentage values:<TD>...</TR>
  </TABLE>
  </DIV>

  Can we generated section numbers in front of 'propname' (printed
  and electronic): Arnaud says yes.

 - An index will be generated from the property definitions. 
 - Property names will also appear in the TOC. They may be
   abbreviated (e.g., "border-*" -> border properties). They may
   be listed in a paragraph (not a vertical list).
 - Therefore: Two links will be generated: one in the index, one in the TOC.

* To mark up property instances:

  <span class="propinst-propname">'propname'</span>

  (Can't use id since there are several instances)

  This will generate:

 <a href="..." class="propinst">
    <span class="propinst-propname">'propname'</span>
  </a>

  - Property instances will link to the definitions.

************
Value types
************
There are three types of value types:
(1) Key words
(2) Basic
(3) Other

Each Value specification in a property definition will include
some combination of these three. 

 - Basic values will be delimited by single <'s. (E.g., <length>)
   and will link to their definitions in syndata.src

 - Other values will be defined below the property definition. They
   will be indicated by single "<'s" *and* 
   by <em>. They will link to their definitions.

MarkUp all value definitions with:

   <span class="index-def" title="value, definition of">
         <a name="value-def-value" class="value-def">value</a>
   </span>

Note that the name attribute is first.
  
MarkUp all value instances with:

   <span class="index-inst" title="value">
         <span class="value-inst-value">value</span>
   </span>

The "value" in the text may be marked up (e.g., &lt;value&gt;)

This will generate the same thing with an A element around the inner
span:

  <a href="..." class="value-inst">
     <span class="value-inst-value">value</span>
  </a>

************
Indexes
************
* <span> will be used to markup the source. Index entries will 
  be generated from this markup. 

* One class name will be used to specify which index the information
  is destined for and whether an entry is the defining instance.
  For the CSS2 spec:

	index-def
	index-inst

* If the title attribute is not set, the span content goes in the
  index (alphabetized) and links to the marked-up source. This
  practice is supported, but discouraged since markup may appear
  in the content. Markup cannot occur in a title attribute.
  
* If the title attribute is set, it becomes the index entry key. The
  attribute value is a "|" separated list of index entries. Each index
  entry may be either a single key or a primary key separated from
  a secondary key.

For example:
--
  <span class="index-def"
        title="word-spacing, definition of|ian's second key">
	Word spacing is defined as ...</span>
  <span class="index-inst"
	title="word-spacing, use with blah">
	In the context of blah blah, word spacing ...</span>

  Discussion of <span class="index-inst">foo bar</span>
--
* Generated anchors:

  The "name" used for anchors and links may be generated numbers since
  each link only refers to one anchor.

* For index keys that point to several locations in the spec, the
  formatting of the keys in the spec must be considered.

************
Examples
************
* In accordance with the HTML spec, use uppercase for
  HTML element names and lowercase for HTML attribute names.

<div class="example"><P>
<pre>
...
</pre>
</div>

Deprecated examples should be as follows:

<div class="deprecated-example"><P>
<span class="example-title">DEPRECATED EXAMPLE:</span><br>
<pre>
...
</pre>
</div>

Illegal examples should be as follows:

<div class="illegal-example"><P>
<span class="example-title">ILLEGAL EXAMPLE:</span><br>
<pre>
...
</pre>
</div>

<div class="note"><P>
<em><strong>Note.</strong> ...</em>
</div>

**********
References
**********
* References. *All* references to WWW pages, books, etc. will appear in
a single file: ref/references.src. Each reference entry will contain
an anchor whose name has the prefix "ref-". If the reference is to a
document online, the URL of the document will be displayed as well
as linked to (for printing). 

All references within the rest of the specification will point to
the appropriate entry in references.src. These links should have the
following syntax:

   <a rel="biblioentry" 
      href="<path>/ref/references.html#ref-SYMBOL"</a>[SYMBOL]</a>

**********
Document HEAD
**********

<!DOCTYPE HTML SYSTEM "http://www.w3.org/TR/WD-html40/sgml/HTML4.dtd">
<html lang="en">
<!-- $Id: CONVENTIONS,v 1.11 1997-10-03 20:52:40 ian Exp $ -->
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>CSS2 Specification</TITLE>
<LINK rel="next" href="?.html">
<LINK rel="previous" href="?.html">
<LINK rel="STYLESHEET" href="style/default.css" type="text/css">
</HEAD>
<BODY>
<H1 align="center">CSS2 Specification</H1>
</BODY>
</HTML>


**********
Images
**********
The working group has deemed that images are better than ascii
art for the spec.

Style guidelines from From Bert:

 *Choose one font (Helvetica or Helvetica Narrow)
 *Choose three colors (black, white, red)
 *Choose two line thicknesses (1px, 3px)
 *Choose two line styles (solid, dotted)
 *Choose two image sizes (large: as wide as the page, and small: half as
  wide)

 *If one of us turns out to be a good cartoonist, we can liven up the
  pictures a bit with one human or animal figure per picture, and maybe
  even one or two free-hand curves, but better not force ourselves here.

From Chris:

  Ian wrote:
  > As I begin to think about replacing ASCII art with
  > images, I would like to raise the following issue: what
  > tools/formats do we use for these images?

  Whatever tools are handy and do the job correctly. As to formats,
  bitmapped images should be available in PNG and GIF for paletted images
  and JPEG for suitable 24bit images; we should also retain a lossless master
  image (24bit PNG). If the artwork was generated from a vector format, the
  vector master should also be retained.