forked from bbcarchdev/docbook-html5
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
143 lines (130 loc) · 7.87 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta charset="utf-8" />
<!--[if lt IE 9]><script>document.createElement('header');document.createElement('nav');document.createElement('section');document.createElement('article');document.createElement('aside');document.createElement('footer');</script><![endif]-->
<title>docbook-html5</title><link rel="stylesheet" type="text/css" href="//bbcarchdev.github.io/painting-by-numbers/style.css"/><link rel="stylesheet" type="text/css" href="//bbcarchdev.github.io/painting-by-numbers/print.css" media="print"/><link rel="stylesheet" type="text/css" href="//cloud.typography.com/6699852/732262/css/fonts.css"/><link rel="stylesheet" type="text/css" href="//fonts.googleapis.com/css?family=Roboto:300,500,300italic,500italic|Inconsolata|Arapey"/><link rel="stylesheet" type="text/css" href="local.css"/><meta name="viewport" content="width=device-width,initial-scale=1,minimum-scale=1"/><!--[if lt IE 9]><link rel="stylesheet" type="text/css" href="//bbcarchdev.github.io/painting-by-numbers/ie78.css" /><![endif]--><!--[if lt IE 9]><script src="//bbcarchdev.github.io/res/js/respond.js"></script><![endif]--><script src="//bbcarchdev.github.io/res/js/modernizr.js"></script>
</head>
<body class="refentry"><header><nav class="global"><div class="inner"><ul>
<li class="logo"><a href="https://bbcarchdev.github.io/res/"><abbr title="Research & Education Space">RES</abbr></a></li>
<li><a href="https://bbcarchdev.github.io/res/education">Education</a></li>
<li><a href="https://bbcarchdev.github.io/res/collections">Collections</a></li>
<li><a href="https://bbcarchdev.github.io/res/products">Products</a></li>
<li><a href="https://bbcarchdev.github.io/res/faq">FAQ</a></li>
</ul></div></nav>
<div class="masthead"></div>
<nav class="secondarynav"><div class="inner"><ul>
<li><a href="https://bbcarchdev.github.io/res/guides">Guides</a></li>
<li><a href="http://acropolis.org.uk">Developer API</a></li>
<li><a href="https://bbcarchdev.github.io/res/tools">Tools</a></li>
<li><a href="https://bbcarchdev.github.io/res/code">Source code</a></li>
</ul></div></nav><h1>docbook-html5</h1></header><section class="legalnotice">
<p>Copyright © 2014 BBC.</p>
<p>docbook-html5 is licensed under the terms of the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a> and is available to browse or download via <a href="https://github.com/bbcarchdev/docbook-html5">GitHub</a>.</p>
<p>The text of this document is licensed under the terms of the <a href="http://www.nationalarchives.gov.uk/doc/open-government-licence/version/2/">Open Government Licence, v2.0</a>.</p>
</section><article>
<section class="refsect1"><h1>Introduction</h1>
<p>
The <a href="https://github.com/bbcarchdev/docbook-html5">docbook-html5 project</a>
is a set of
<a href="http://www.w3.org/TR/xslt">XSLT</a> stylesheets for
transforming <a href="http://www.docbook.org/tdg5/en/html/docbook.html">DocBook 5</a>
XML into (X)HTML5 documents, developed as part of the
<a href="http://bbcarchdev.github.io/res/">Research & Education Space</a>
project in order to produce specific mark-up from our DocBook 5 sources.
</p>
<p>
The stylesheets have no direct connection to the extremely
comprehensive
<a href="http://docbook.sourceforge.net/release/xsl/current/doc/">official DocBook XSL stylesheets</a>,
and don't have the same level of element coverage, but you
may find them easier to modify to suit your needs than the official XSL
package thanks to to their relative simplicity.
</p>
</section>
<section class="refsect1"><h1>Usage</h1>
<p>
If your XSLT processor supports it, docbook-html5 can be used either
remotely, or you can include a copy in your project (for example, as
a <a href="http://git-scm.com/book/en/Git-Tools-Submodules">git submodule</a>),
and used locally.
</p>
<p>
Examples given here use <a href="http://xmlsoft.org/XSLT/xsltproc.html"><kbd class="command">xsltproc</kbd></a>,
an open source cross-platform XSLT processor included with most Linux
and Unix distributions.
</p>
<p>
To use docbook-html5 remotely:—
</p>
<pre class="output"><samp><samp class="output prompt">$ </samp> <kbd>xsltproc --xinclude -o OUTPUT.html http://bbcarchdev.github.io/docbook-html5/docbook-html5.xsl INPUT.xml</kbd></samp></pre>
<p>
To use docbook-html5 locally, simply specify the filesystem path to
<code class="filename">docbook-html5.xsl</code> in place of the URL:—
</p>
<pre class="output"><samp><samp class="output prompt">$ </samp> <kbd>xsltproc --xinclude --nonet -o OUTPUT.html http://bbcarchdev.github.io/docbook-html5/docbook-html5.xsl INPUT.xml</kbd></samp></pre>
<p>
When using the stylesheets locally, the --nonet option may
be supplied, which prevents <kbd class="command">xsltproc</kbd> from performing any
requests to remote network hosts.
</p>
<aside class="tip">
Many XSLT processors have the concept of a <i class="firstterm">catalog</i>,
where remote URLs are redirected to a local cache of resources—typically
DTDs and XSLT. This capability allows you to consistently use the
remote URL to the stylesheets, but a local copy will be used instead if
present and configured properly. See your XSLT processor’s documentation
for more information on configuring the catalog.
</aside>
</section>
<section class="refsect1"><h1>Parameters</h1>
<p>
The stylesheets support a number of parameters which alter the output
which is produced.
</p>
<dl>
<dt><var>html.linksfile</var></dt>
<dd>
Specifies the URL of an XML file whose contents will be substituted
into the output document’s <code class="tag"><head></code> element,
and typically contains <code class="tag"><link></code> and
<code class="tag"><meta></code> elements. See
<a href="https://github.com/bbcarchdev/docbook-html5/blob/gh-pages/links-sample.xml"><code class="filename">links-sample.xml</code></a>
for an example. Note that the URL specified will be interpreted as
relative to the stylesheets URL, and so you may need to specify
an absolute <code class="literal">file:///</code> URL.
</dd>
<dt><var>html.navfile</var></dt>
<dd>
Specifies the URL of an XML file whose contents will be substituted
into the output document’s global <code class="tag"><nav></code> element
(which appears, if this parameter is specified, within the
document-level <code class="tag"><header></code>). See
<a href="https://github.com/bbcarchdev/docbook-html5/blob/gh-pages/nav-sample.xml"><code class="filename">nav-sample.xml</code></a>
for an example. Note that the URL specified will be interpreted as
relative to the stylesheets URL, and so you may need to specify
an absolute <code class="literal">file:///</code> URL.
</dd>
<dt><var>html.ie78css</var></dt>
<dd>
Specifies the URL of the CSS stylesheet which targets Microsoft
Internet Explorer 7 and 8, and will be referenced by
a <code class="tag"><link></code> element within the HTML document’s
<code class="tag"><head></code> element, and is emitted as a
<a href="http://msdn.microsoft.com/en-us/library/ms537512(v=vs.85).aspx">conditional comment</a>
which is ignored by other web browsers.
</dd>
</dl>
</section>
<section class="refsect1"><h1>Example</h1>
<pre class="output"><samp><samp class="output prompt">$ </samp> <kbd>xsltproc --xinclude \
-o OUTPUT.html \
--param html.linksfile "'file://`pwd`/links-sample.xml'" \
--param html.navfile "'file://`pwd`/nav-sample.xml'" \
--param html.ie78css "'http://docs.example.com/stylesheets/ie78.css'" \
/path/or/url/to/docbook-html5/docbook-html5.xsl \
INPUT.xml</kbd></samp></pre>
</section>
</article></body>
</html>