oreillymedia · sandersk · Apr 16, 2013 · Apr 16, 2013 · Apr 16, 2013 · Apr 16, 2013
@@ -1,19 +1,51 @@
 === HTMLBook
 
-Let's write books in HTML!
-
-HTMLBook is built on the premise that:
+Let's write books in HTML! HTMLBook is an open HTML5-based XML standard for the authoring and production of both print and digital books. HTMLBook is built on the following premises::
 
 * Books are timeless. The basic "book" structure has persisted for hundreds of years and will continue to persist for our lifetimes, be it in digital or print form. 
 * HTML is the markup language of the world for the foreseeable future.
 * Single-source document processing will remain valuable for the foreseeable future.
 
 As such, HTMLBook can be characterized in the following ways:
 
-* HTMLBook is a subset of XHTML5.
-* HTMLBook will contain no additional elements or attributes outside of the HTML5 specification.
-* All HTMLBook is HTML5, but not all HTML5 is HTMLBook.
+* HTMLBook is a subset of XHTML5. All HTMLBook is HTML5, but not all HTML5 is HTMLBook.
+* HTMLBook contains no additional elements or attributes outside of the HTML5 specification.
 * HTMLBook is semantically tailored to the structure of a "book" (including more complex content used in technical and reference documents).
-* HTMLBook is defined with with an XML schema/DTD.
-* HTMLBook templates will be written in CSS.
-* HTMLBook supports both full-fledged book content, as well as shorter-form content—e.g., articles.
+* HTMLBook is defined with and can be validated against an XML schema.
+* HTMLBook templates can be written in CSS.
+
+=== Getting Started with HTMLBook
+
+* Read the Working Draft of the HTMLBook Specification here:
+
+https://github.com/oreillymedia/HTMLBook/blob/master/specification.asciidoc
+
+* Get the HTMLBook schema here:
+
+https://github.com/oreillymedia/HTMLBook/tree/master/schema
+
+The main HTMLBook Schema file is +htmlbook.xsd+, which imports Schemas (via W3C) for MathML and SVG validation.
+
+You can validate HTML documents against +htmlbook.xsd+ on the command line using +xmllint+:
+
+----
+$ xmllint --noout --schema htmlbook.xsd <your_html_filename>.html
+----
+
+Alternatively, to validate in a GUI XML editor like oXygen, add a +xsi:schemaLocation+ declaration to the root +<html>+ element as follows:
+
+----
+<html xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.w3.org/1999/xhtml ../schema/htmlbook.xsd"
+ xmlns="http://www.w3.org/1999/xhtml">
+----
+
+=== Notes on HTMLBook
+
+* The HTMLBook specification is currently in Working Draft status, and will continue to be developed and revised for the foreseeable future.
+
+* If you have any bugs or feature requests for HTMLBook, please submit them via the Issues tab in GitHub
+
+* In the coming months, we will be adding additional tools to the HTMLBook project for authoring and producing books with HTMLBook: CSS stylesheets, scripts for generating EPUB/Mobi, etc.
+
+* If you would like to contribute to the HTMLBook project, send us a pull request!
@@ -1,4 +1,4 @@
 W3C MathML XML Schema, via http://www.w3.org/Math/XMLSchema/
 
-ORM Note: Some tiny tweaks made to annotation-xml content model (in mathml3-common.xsd) to ensure it was determinist;
+Note: Some tiny tweaks made to annotation-xml content model (in mathml3-common.xsd) to ensure it was determinist;
 see https://github.com/oreillymedia/HTMLBook for file history
@@ -41,13 +41,13 @@
    </xs:element>
    <xs:complexType name="annotation-xml.model">
       <xs:choice minOccurs="0" maxOccurs="unbounded">
-         <!-- ORM: removing ref="m:MathExpression", as it's redundant given the reference to m:anyElement, and violates determinist content model -->
+         <!-- HTMLBook Note: removing ref="m:MathExpression", as it's redundant given the reference to m:anyElement, and violates determinist content model -->
          <xs:group ref="m:anyElement"/>
       </xs:choice>
    </xs:complexType>
    <xs:group name="anyElement">
       <xs:choice>
-         <!-- ORM: switching namespace to "##any" to cover everything -->
+         <!-- HTMLBook Note: switching namespace to "##any" to cover everything -->
          <xs:any namespace="##any" processContents="skip"/>
       </xs:choice>
    </xs:group>
@@ -98,4 +98,4 @@
          <xs:pattern value="\s*((-?[0-9]*([0-9]\.?|\.[0-9])[0-9]*(e[mx]|in|cm|mm|p[xtc]|%)?)|(negative)?((very){0,2}thi(n|ck)|medium)mathspace)\s*"/>
       </xs:restriction>
    </xs:simpleType>
-</xs:schema>
+</xs:schema>
@@ -1,5 +1,5 @@
 W3C SVG XML Schema, via http://www.w3.org/TR/2002/WD-SVG11-20020108/SVG.xsd
-(with local mods for validity by Sanders; see https://github.com/oreillymedia/HTMLBook for file history)
+(with some local mods for validity; see https://github.com/oreillymedia/HTMLBook for file history)
 
 Dependencies also included:
 

@@ -254,7 +254,7 @@
       <documentation>'preserveAspectRatio' attribute specification</documentation>
     </annotation>
     <restriction base="string">
-      <!-- ORM: Revised pattern to be more accurate and match default values -->
+      <!-- HTMLBook Note: Revised pattern to be more accurate and match default values -->
       <pattern value="\s*x(Min|Mid|Max)Y(Min|Mid|Max)(\s+(meet|slice)\s*)?"/>
     </restriction>
   </simpleType>
@@ -333,7 +333,7 @@
       <documentation>All elements have an ID</documentation>
     </annotation>
     <attribute name="id" type="ID" use="optional"/>
-    <!-- ORM: dropped invalid type attr on below element -->
+    <!-- HTMLBook Note: dropped invalid type attr on below element -->
     <attribute ref="xml:base" use="optional"/>
   </attributeGroup>
   <attributeGroup name="langSpaceAttrs">
@@ -835,7 +835,7 @@
   </attributeGroup>
   <attributeGroup name="animElementAttrs">
     <attributeGroup ref="svg:xlinkRefAttrs"/>
-    <!-- ORM: Dropped invalid type attr on below element -->
+    <!-- HTMLBook Note: Dropped invalid type attr on below element -->
     <attribute ref="xlink:href" use="optional"/>
   </attributeGroup>
   <attributeGroup name="animAttributeAttrs">
@@ -911,7 +911,7 @@
   </attributeGroup>
   <group name="descTitleMetadata">
     <annotation>
-      <!-- ORM Note: switched here from invalid xs:all based content model (which can't be used for particles as was being done)
+      <!-- HTMLBook Note: switched here from invalid xs:all based content model (which can't be used for particles as was being done)
            to xs:choice-based content model, which allows for one or more desc/title/metadata elements at the beginning of all content models in which 
            descTitleMetadata is referenced -->
       <documentation>A bit simpler than the DTD, but see commented-out alternative</documentation>