[css2] Bug fixes, new toc mechanism, new index mechanism, new CONVENTIONS, updated (pretty will ) with respect to HTML

--HG--
extra : convert_revision : svn%3A73dc7c4b-06e6-40f3-b4f7-9ed1dbc14bfc/trunk%40490

Author: ianbjacobs

css2/DOC/CONVENTIONS

@@ -6,13 +6,18 @@ Global structure
 
 
 * 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.
 
+************
+To suppress page numbers in generated PS:
+************
+
+(1) Use Arnaud's patched html2ps
+(2) Add class="noxref" to your link.
+
 ************
 TABLE OF CONTENTS
 ************
@@ -28,47 +33,28 @@ is "Margin properties" and a heading number.
 ************
 Properties
 ************
-In source file:
+The following line in the source file:
 
   <!-- #include src=properties/propname.srb -->
 
-The following will be generated:
+(1) Will generate a property definition based on the definition
+    in properties/properties.db and the output of bin/pextr.
+    [Analogous for descriptors].
 
-  <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>
+(2) Will generate an entry in the properties index [TO BE DONE].
 
-  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.
+Note:  To get the property name in the TOC, it must be put in a
+       header.
 
-* To mark up property instances:
 
-  <span class="propinst-propname">'propname'</span>
+* To mark up a property instance so that it will generate
+  a link to its definition, write:
 
-  (Can't use id since there are several instances)
-
-  This will generate:
-
- <a href="..." class="propinst">
-    <span class="propinst-propname">'propname'</span>
-  </a>
+  <span class="propinst-propname">'propname'</span>
 
-  - Property instances will link to the definitions.
+* You cannot put any <span>s inside the <span> around the property
+  instance.
 
 ************
 Value types
@@ -81,19 +67,22 @@ There are three types of value types:
 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>)
+ - 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 "<'s" *and* 
+   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">value</a>
+         <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:
@@ -102,6 +91,9 @@ MarkUp all value instances with:
          <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
@@ -114,48 +106,71 @@ span:
 ************
 Indexes
 ************
-* <span> will be used to markup the source. Index entries will 
-  be generated from this markup. 
+* 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 "|".
 
-* 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:
+  * You may only have one level of subkey (i.e., a::b::c is illegal).
 
-	index-def
-	index-inst
+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. 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.
+  in the content. 
 
-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>
+* 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,  
 
-  Discussion of <span class="index-inst">foo bar</span>
---
-* Generated anchors:
+   <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).
 
-  The "name" used for anchors and links may be generated numbers since
-  each link only refers to one anchor.
+* 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.
 
-* 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.
 
@@ -187,29 +202,53 @@ Illegal examples should be as follows:
 <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: ref/references.src. Each reference entry will contain
+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:
 
    <a rel="biblioentry" 
-      href="<path>/ref/references.html#ref-SYMBOL"</a>[SYMBOL]</a>
+      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.11 1997-10-03 20:52:40 ian Exp $ -->
+<!-- $Id: CONVENTIONS,v 1.12 1997-12-09 00:08:30 ijacobs Exp $ -->
 <HEAD>
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <TITLE>CSS2 Specification</TITLE>
@@ -222,13 +261,9 @@ Document HEAD
 </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)
@@ -240,7 +275,11 @@ Style guidelines from From Bert:
 
  *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.
+  even one or two free-hand curves, but better not force ourselves
+  here.
+ 
+ *Images should be centered (in a <P>)
+
 
 From Chris: