Skip to content

Commit 851f9b8

Browse files
author
Sanders Kleinfeld
committed
Merge pull request #36 from oreillymedia/readme
Updated README and reorganized repo
2 parents feb1b82 + d6ab690 commit 851f9b8

File tree

12 files changed

+50
-18
lines changed

12 files changed

+50
-18
lines changed

‎README.asciidoc

Lines changed: 41 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,51 @@
11
=== HTMLBook
22

3-
Let's write books in HTML!
4-
5-
HTMLBook is built on the premise that:
3+
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::
64

75
* 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.
86
* HTML is the markup language of the world for the foreseeable future.
97
* Single-source document processing will remain valuable for the foreseeable future.
108
119
As such, HTMLBook can be characterized in the following ways:
1210

13-
* HTMLBook is a subset of XHTML5.
14-
* HTMLBook will contain no additional elements or attributes outside of the HTML5 specification.
15-
* All HTMLBook is HTML5, but not all HTML5 is HTMLBook.
11+
* HTMLBook is a subset of XHTML5. All HTMLBook is HTML5, but not all HTML5 is HTMLBook.
12+
* HTMLBook contains no additional elements or attributes outside of the HTML5 specification.
1613
* HTMLBook is semantically tailored to the structure of a "book" (including more complex content used in technical and reference documents).
17-
* HTMLBook is defined with with an XML schema/DTD.
18-
* HTMLBook templates will be written in CSS.
19-
* HTMLBook supports both full-fledged book content, as well as shorter-form content—e.g., articles.
14+
* HTMLBook is defined with and can be validated against an XML schema.
15+
* HTMLBook templates can be written in CSS.
16+
17+
=== Getting Started with HTMLBook
18+
19+
* Read the Working Draft of the HTMLBook Specification here:
20+
21+
https://github.com/oreillymedia/HTMLBook/blob/master/specification.asciidoc
22+
23+
* Get the HTMLBook schema here:
24+
25+
https://github.com/oreillymedia/HTMLBook/tree/master/schema
26+
27+
The main HTMLBook Schema file is +htmlbook.xsd+, which imports Schemas (via W3C) for MathML and SVG validation.
28+
29+
You can validate HTML documents against +htmlbook.xsd+ on the command line using +xmllint+:
30+
31+
----
32+
$ xmllint --noout --schema htmlbook.xsd <your_html_filename>.html
33+
----
34+
35+
Alternatively, to validate in a GUI XML editor like oXygen, add a +xsi:schemaLocation+ declaration to the root +<html>+ element as follows:
36+
37+
----
38+
<html xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
39+
xsi:schemaLocation="http://www.w3.org/1999/xhtml ../schema/htmlbook.xsd"
40+
xmlns="http://www.w3.org/1999/xhtml">
41+
----
42+
43+
=== Notes on HTMLBook
44+
45+
* The HTMLBook specification is currently in Working Draft status, and will continue to be developed and revised for the foreseeable future.
46+
47+
* If you have any bugs or feature requests for HTMLBook, please submit them via the Issues tab in GitHub
48+
49+
* 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.
50+
51+
* If you would like to contribute to the HTMLBook project, send us a pull request!

‎htmlbook.xsd renamed to ‎schema/htmlbook.xsd

File renamed without changes.

‎mathml3/README renamed to ‎schema/mathml3/README

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
W3C MathML XML Schema, via http://www.w3.org/Math/XMLSchema/
22

3-
ORM Note: Some tiny tweaks made to annotation-xml content model (in mathml3-common.xsd) to ensure it was determinist;
3+
Note: Some tiny tweaks made to annotation-xml content model (in mathml3-common.xsd) to ensure it was determinist;
44
see https://github.com/oreillymedia/HTMLBook for file history

‎mathml3/mathml3-common.xsd renamed to ‎schema/mathml3/mathml3-common.xsd

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,13 +41,13 @@
4141
</xs:element>
4242
<xs:complexType name="annotation-xml.model">
4343
<xs:choice minOccurs="0" maxOccurs="unbounded">
44-
<!-- ORM: removing ref="m:MathExpression", as it's redundant given the reference to m:anyElement, and violates determinist content model -->
44+
<!-- HTMLBook Note: removing ref="m:MathExpression", as it's redundant given the reference to m:anyElement, and violates determinist content model -->
4545
<xs:group ref="m:anyElement"/>
4646
</xs:choice>
4747
</xs:complexType>
4848
<xs:group name="anyElement">
4949
<xs:choice>
50-
<!-- ORM: switching namespace to "##any" to cover everything -->
50+
<!-- HTMLBook Note: switching namespace to "##any" to cover everything -->
5151
<xs:any namespace="##any" processContents="skip"/>
5252
</xs:choice>
5353
</xs:group>
@@ -98,4 +98,4 @@
9898
<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*"/>
9999
</xs:restriction>
100100
</xs:simpleType>
101-
</xs:schema>
101+
</xs:schema>

‎mathml3/mathml3-content.xsd renamed to ‎schema/mathml3/mathml3-content.xsd

File renamed without changes.

‎mathml3/mathml3-presentation.xsd renamed to ‎schema/mathml3/mathml3-presentation.xsd

File renamed without changes.

‎mathml3/mathml3-strict-content.xsd renamed to ‎schema/mathml3/mathml3-strict-content.xsd

File renamed without changes.

‎mathml3/mathml3.xsd renamed to ‎schema/mathml3/mathml3.xsd

File renamed without changes.

‎svg/README renamed to ‎schema/svg/README

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
W3C SVG XML Schema, via http://www.w3.org/TR/2002/WD-SVG11-20020108/SVG.xsd
2-
(with local mods for validity by Sanders; see https://github.com/oreillymedia/HTMLBook for file history)
2+
(with some local mods for validity; see https://github.com/oreillymedia/HTMLBook for file history)
33

44
Dependencies also included:
55

‎svg/SVG.xsd renamed to ‎schema/svg/SVG.xsd

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -254,7 +254,7 @@
254254
<documentation>'preserveAspectRatio' attribute specification</documentation>
255255
</annotation>
256256
<restriction base="string">
257-
<!-- ORM: Revised pattern to be more accurate and match default values -->
257+
<!-- HTMLBook Note: Revised pattern to be more accurate and match default values -->
258258
<pattern value="\s*x(Min|Mid|Max)Y(Min|Mid|Max)(\s+(meet|slice)\s*)?"/>
259259
</restriction>
260260
</simpleType>
@@ -333,7 +333,7 @@
333333
<documentation>All elements have an ID</documentation>
334334
</annotation>
335335
<attribute name="id" type="ID" use="optional"/>
336-
<!-- ORM: dropped invalid type attr on below element -->
336+
<!-- HTMLBook Note: dropped invalid type attr on below element -->
337337
<attribute ref="xml:base" use="optional"/>
338338
</attributeGroup>
339339
<attributeGroup name="langSpaceAttrs">
@@ -835,7 +835,7 @@
835835
</attributeGroup>
836836
<attributeGroup name="animElementAttrs">
837837
<attributeGroup ref="svg:xlinkRefAttrs"/>
838-
<!-- ORM: Dropped invalid type attr on below element -->
838+
<!-- HTMLBook Note: Dropped invalid type attr on below element -->
839839
<attribute ref="xlink:href" use="optional"/>
840840
</attributeGroup>
841841
<attributeGroup name="animAttributeAttrs">
@@ -911,7 +911,7 @@
911911
</attributeGroup>
912912
<group name="descTitleMetadata">
913913
<annotation>
914-
<!-- ORM Note: switched here from invalid xs:all based content model (which can't be used for particles as was being done)
914+
<!-- HTMLBook Note: switched here from invalid xs:all based content model (which can't be used for particles as was being done)
915915
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
916916
descTitleMetadata is referenced -->
917917
<documentation>A bit simpler than the DTD, but see commented-out alternative</documentation>

‎svg/xlink.xsd renamed to ‎schema/svg/xlink.xsd

File renamed without changes.

‎svg/xml.xsd renamed to ‎schema/svg/xml.xsd

File renamed without changes.

0 commit comments

Comments
 (0)