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.

* It's ok to use <TABLE>.

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

************
To suppress page numbers in generated PS:
************

(1) Use Arnaud's patched html2ps
(2) Add class="noxref" to your link.

************
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
************
The following line in the source file:

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

(1) Will generate a property definition based on the definition
    in properties/properties.db and the output of bin/pextr.
    [Analogous for descriptors].

(2) Will generate an entry in the properties index [TO BE DONE].


Note:  To get the property name in the TOC, it must be put in a
       header.


* To mark up a property instance so that it will generate
  a link to its definition, write:

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

* You cannot put any <span>s inside the <span> around the property
  instance.

* html2ps will normally indicate the generated link by inserting a
  page number after it. To suppress that, add "noxref":

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

  (The way this works is that the addlinks script copies the "noxref"
  to the <a> tag it generates, and html2ps looks at that <a> tag.)


************
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 < marks. (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 < marks *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"><b>value</b></a>
   </span>

* You cannot put any <span>s
  inside the <span> around the value definition.

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>

* You cannot put any <span>s
  inside the <span> around the value instance.

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>

* html2ps will normally indicate the generated link by inserting a
  page number after it. To suppress that, add "noxref":

  <span class="value-inst-value noxref">value</span>

************
Indexes
************
* Index markup appears within a <span> element or a <dfn> element.
* Definitions are marked up with class="index-def"
  [Decided in NYC] The content of index definitions should be
  marked within <em>..</em>
* Non-definitions are marked up with class="index-inst".
* The title attribute determines the index keys:

  a)  title="keyword" produces in the index: 
          
              ... 
              keyword, n
              ...     

      where n refers to the nth appearance of that keyword
      in the index. If keyword is a definition, n will be 
      rendered specially

  b)  title="keyword::subkey" produces in the index:

             ...
             keyword
                    subkey, n
             ...           

  c)  title="keyword1|keyword2" puts both keywords in the index.


  * You may have as many alternate entries in a span as you want, 
    separating all of them with a "|".

  * You may only have one level of subkey (i.e., a::b::c is illegal).

For example:

   <span class="index-def" title="mydef">mydef text</span>
   <span class="index-def" title="mydef::subpart">mydef text</span>
   <span class="index-def" 
         title="mydef::subpart|subpart of mydef">mydef text</span>

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

* This markup is converted into an anchor during processing. However,
  the processor looks to see whether an anchor has already been
  defined within the span and reuses it if it has. Thus,  

   <span class="index-def" title="mydef"><a name="foo">..</a></span>
  
  will work, as will any markup that generates an anchor 
  with "name" set. (the index  is processed after the other stuff).

* You may not, however, embed index markup. You don't need to,
  however, since the "|" mechanism allows any number of index
  keys at the same place.

* [TODO] In the printed version, the links are printed as page
numbers.


************
Examples
************

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

* Markup CSS examples with the classes "example",
"deprecated-example", "illegal-example".

* Markup HTML examples with the classes "html-example",
"deprecated-html-example", "illegal-html-example".

* Markup XML examples with the classes "xml-example",
"deprecated-xml-example", "illegal-xml-example".


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


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

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

* Indentation of examples? [HAKON TODO]

**********
References
**********
* References. *All* references to WWW pages, books, etc. will appear in
a single file: refs.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). 

References in refs.src should either be marked normative
or informative and should be specified in the proper section.

A normative reference is marked as class="normref":

<dt><strong><a name="ref-FLEX" class="normref">[FLEX]</a></strong>
<dd>"Flex: The Lexical Scanner Generator", Version 2.3.7, ISBN 1882114213.

An informative reference is marked as class="informref".

Please put the "name" attribute before the "class" attribute.

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

   [[SYMBOL]]
or
   [[-SYMBOL]]

The latter forces the reference to be informative ('informref').
This will automatically be expanded to something like:

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

Note the appearance of class="normref" | class="informref" 
at the end of the anchor start tag. It is possible to
have an informative link to a normative reference, but you
should not have a normative link to an informative reference.

You can check to see that links to refs.src are ok with respect
to normref/informref by running "make checkrefs".

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

<!DOCTYPE HTML SYSTEM "http://www.w3.org/TR/WD-html40/sgml/HTML4.dtd">
<html lang="en">
<!-- $Id: CONVENTIONS,v 1.15 1998-05-05 18:01:10 bbos Exp $ -->
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<TITLE>CSS2 Specification</TITLE>
<!-- *Don't* put next, prev, and stylesheet links, they are automatic -->
</HEAD>
<BODY>
<H1 align="center">CSS2 Specification</H1>
</BODY>
</HTML>

**********
Images
**********
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.
 
 *Images should be centered (in a <P>)


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.