Project

Profile

Help

Download (18.8 KB) Statistics
| Branch: | Revision:

he / src / userdoc / help-system.xml @ 8ddaa514

1 7fe97548 Norman Walsh
<article id="help-system" title="Using this Documentation">
2
    <h1>Using this Documentation</h1>
3
    <p>This documentation system runs as a single-page web application, exploiting XSLT 3.0 running in the
4
        browser. This section provides extra detail on how to get the most out of the documentation,
5
        along with some extra details on how Saxon-JS is used to run the application.</p>
6
    <nav>
7
        <ul/>
8
    </nav>
9
    <section id="guide" title="User Guide">
10
        <h1>User Guide</h1>
11
        <p>This section outlines the key parts to this application - designed for rendering help
12
            documentation.</p>
13
        <h2>Breadcrumbs</h2>
14
        <p>The breadcrumbs bar is found at the top of the app - it shows where you currently are in
15
            the hierarchy of the documentation. Clicking items on this bar provides quick access to
16
            parent pages.</p>
17
        <h2>Search</h2>
18
        <p>Located at the top-left of the app, the <strong>search box</strong> can be used to enter
19
            in a plain-text search term, press <code>Enter</code> or the <code>search</code> button
20
            to initiate a search.</p>
21
        <p>Two pop-up boxes show the pages found with hits, and the app will navigate to the first
22
            page hit. The first box (top left) shows the number of hits, and the up/down buttons can
23
            be used to move between pages with hits. The second box (bottom left) provides a
24
            scrollable list of links to all page hits, referenced by section name. All matching
25
            words will be highlighted in the rendered document until the pop-up is closed (by
26
            pressing the <code>close</code> button).</p>
27
        <p>To perform a <strong>Java API search</strong> for a class or class-member, prefix the
28
            name of the search item with a '#' character, for example:
29
                <code>#qualifiednamevalue</code>. The name search is not case sensitive but the
30
            search term must match the whole name.</p>
31
        <h2>Collapse All</h2>
32
        <p>Pressing the "collapse all" button (adjacent to the search button) collapes the tree-view
33
            menu.</p>
34
        <h2>Tree-View</h2>
35
        <p>The tree-view menu provides a collapsible hierarchical view of the Table of Contents.
36
            Nodes are expanded or collapsed by either selecting the node itself (which may change
37
            the page selection) or the adjacent arrow icon.</p>
38
        <h3>Page Up/Page Down</h3>
39
        <p>Buttons for page up/down are placed at the right edge of the application footer. Note that the
40
            keyboard <code>PgUp</code> and <code>PgDn</code> keys serve the same purpose.</p>
41
        <h3>Touch Control</h3>
42
        <p>This app should work with any touch-enabled device. The layout is optimised for desktop
43
            or tablet devices in landscape orientation.</p>
44
    </section>
45
    <section id="technical" title="Technical Details">
46
        <h1>Technical Details</h1>
47
        <p>This section provides information on the design of this application. The app has been
48
            updated to run with Saxon-JS rather than Saxon-CE. The stylesheets have been
49
            updated for use with Saxon-JS: to use XSLT 3.0, and new interactive XSLT extensions
50
            available with Saxon-JS.</p>
51
        <!--<p>This section provides information on the design of this application. The major design
52
            considerations are outlined below:</p>
53
        <ul>
54
            <li>Separation of visual style from functionality<ul>
55
                    <li>CSS = Visual Style</li>
56
                    <li>HTML = Visual Tree</li>
57
                    <li>XSLT = Functionality</li>
58
                </ul></li>
59

60
            <li>'Thin Server' design - no build pipeline</li>
61
            <li>Side-effect free transforms</li>
62
            <li>SEO and Accessibility - Restricted static-HTML transformer</li>
63
            <li>Scalability - Lazy loading &amp; processing</li>
64
            <li>Browser history &amp; bookmarkability - simulated client/server split</li>
65
            <li>Three schemas supported<ul>
66
                    <li>HTML5 Article Element Schema</li>
67
                    <li>Function Specification Schema</li>
68
                    <li>JavaDoc Data Schema</li>
69
                </ul></li>
70
            <li>Maintainability - Predominantly coded in XSLT 2.0</li>
71
            <li>State-management and non-standard browser features - Used 'Raw' JS</li>
72
        </ul>-->
73
        <p>For details on the resource files that generate this application, see the next section:</p>
74
        <nav>
75
            <ul/>
76
        </nav>
77
        
78
        <section id="resources" title="Application Resources">
79
            <h1>Application Resources</h1>
80
            <p>This application relies on a number of resource files, these are outlined below</p>
81
            <table border="1">
82
                <tbody>
83
                    <tr>
84
                        <td><p>xsl/viewer_app.sef.xml</p></td>
85
                        <td>
86
                            <p>Stylesheet Export File (SEF) generated from the viewer_app.xsl stylesheet using
87
                                Saxon-EE, for use with Saxon-JS.</p>
88
                            <p/>
89
                        </td>
90
                    </tr>
91
                    <tr>
92
                        <td><p>xsl/viewer_app.xsl</p></td>
93
                        <td>
94
                            <p>The top-level XSLT file - imports other XSLT resources.</p>
95
                            <p>Controls responses to user and system events and imports remaining
96
                                XSLT.</p>
97
                            <p>Responsible for dynamic control over all visual elements in the
98
                                application - except the rendered page.</p>
99
                            <p/>
100
                        </td>
101
                    </tr>
102
                    <tr>
103
                        <td><p>xsl/*.xsl</p></td>
104
                        <td><p>All the imported XSLT files - each one responsible for rendering a
105
                            different document structure or serving a specialist function - such as
106
                            search.</p></td><!--  and link-checking -->
107
                    </tr>
108
                    <tr>
109
                        <td><p>viewer_app.js</p></td>
110
                        <td><p>JavaScript for managing state and for non-standard features like
111
                            text-highlighting.</p></td>
112
                    </tr>
113
                    <tr>
114
                        <td><p>viewer_app.css and saxon-base.css</p></td>
115
                        <td><p>Controls all style and layout aspects of the application.</p></td>
116
                    </tr>
117
                    <tr>
118
                        <td><p>index.html</p></td>
119
                        <td><p>The host HTML page - loads the Saxon-JS processor and contains the
120
                            'skeleton' on which to hang the dynamic elements of the
121
                            application.</p></td>
122
                    </tr>
123
                    <tr>
124
                        <td><p>doc/catalog.xml</p></td>
125
                        <td><p>References all the top-level documents containing article elements -
126
                            represented as top-level nodes in the Table of Contents.</p></td>
127
                    </tr>
128
                    <tr>
129
                        <td><p>doc/*.xml</p></td>
130
                        <td><p>All the top-level documents - each one containing an HTML 5 article
131
                            element with a number of nested section elements.</p></td>
132
                    </tr>
133
                    <tr>
134
                        <td><p>docimg/*.*</p></td>
135
                        <td><p>Container for all media files (such as graphics) referenced
136
                            from within articles or sections.</p></td>
137
                    </tr>
138
                    <tr>
139
                        <td><p>image/*.*</p></td>
140
                        <td><p>Images used by the application - should be kept separate from images
141
                            referenced by the documentation (unless they serve both purposes).</p></td>
142
                    </tr>
143
                    <tr>
144
                        <td><p>javadoc-xml/*.*</p></td>
145
                        <td><p>JavaDoc files for the Saxon Java API.</p>
146
                            <p>All files in this directory should be auto-generated on a Saxon build.
147
                            The build uses a Java doclet to create one 'master' XML file which is
148
                            then processed by XSLT to partition, sort and group the data.</p></td>
149
                    </tr>
150
                    <tr>
151
                        <td><p>javadoc-xml/javadoc-tree.xml</p></td>
152
                        <td><p>Used by the application to show the tree-view of the JavaDoc
153
                            members.</p></td>
154
                    </tr>
155
                    <tr>
156
                        <td><p>javadoc-packages.xml</p></td>
157
                        <td><p>The aggregated and processed well-formed content of HTML pages that
158
                            describe each Saxon Java package and are maintained alongside the
159
                            code.</p></td>
160
                    </tr>
161
                    <tr>
162
                        <td><p>javadoc-types.xml</p></td>
163
                        <td><p>File used as a rough indexing measure to locate Saxon Java types and
164
                            functions.</p></td>
165
                    </tr>
166
                    <tr>
167
                        <td><p>javadoc-xml/packages/*.xml</p></td>
168
                        <td><p>Each XML file represents a Java package with data about each contained
169
                            type, plus authored HTML comments (converted to well-formed XML by
170
                            tagsoup).</p></td>
171
                    </tr>
172
                    <tr>
173
                        <td><p>dotnetdoc-xml/*.*</p></td>
174
                        <td><p>JavaDoc files for the Saxon.NET API. (Similar to javadoc-xml, see
175
                            above.)</p></td>
176
                    </tr>
177
                    <tr>
178
                        <td><p>Saxon-JS/*.*</p></td>
179
                        <td><p>Saxon-JS processor.</p></td>
180
                    </tr>
181
                    <!-- The following are now "external" -->
182
                    <!--<tr>
183
                        <td><p>html/*.*</p></td>
184
                        <td><p>(Optional) Directory for static HTML generated by XSLT 3.0 - run from an
185
                            Ant task.</p></td>
186
                    </tr>-->
187
                    <!--<tr>
188
                        <td><p>to-static</p></td>
189
                        <td><p>Contains resources for creating static HTML rendered from the XML files
190
                            in the doc directory - output goes to the <code>html</code>
191
                            directory.</p></td>
192
                    </tr>-->
193
                </tbody>
194
            </table>
195
        </section>
196
    </section>
197
    <section id="authoring" title="Authoring">
198
        <h1>Authoring Help</h1>
199
        <p>This section is a brief guide to the main elements used in this Saxon documentation which
200
            conforms to the HTML-5 <code>article</code> element.</p>
201
        <p>The <code>article</code> element is the top-level element in the XML document. It must
202
            have an <code>id</code> attribute that corresponds to a <code>ref</code> attribute value
203
            found in the <code>catalog.xml</code> file. The <code>title</code> attribute is what
204
            will be shown in the table of contents and other links.</p>
205
        <p>Introductory text goes inside the top-level article element - normally, this will be
206
            headed by an <code>h1</code> element as the heading for the article (which may be the
207
            same as the <code>title</code> attribute of <code>article</code>). Navigation links can
208
            also be added for all child topics in the article using
209
                <code><![CDATA[<nav><ul/></nav>]]></code>.</p>
210
        <nav>
211
            <ul/>
212
        </nav>
213
        <section id="links" title="Using Links">
214
            <h1>Using Links</h1>
215
            <p>Links are represented using <code>a</code> elements, for example: <code>&lt;a
216
                    href=&quot;/changes"&gt;</code> is used to reference the top-level <a
217
                    href="/changes"> Changes</a> topic. Specific forms include:</p>
218
            <ul>
219
                <li><code>&lt;a
220
                    class="bodylink" href="<em>path</em>"&gt;</code> - internal reference</li>
221
                <li><code>&lt;a
222
                class="bodylink" href="<em>URI</em>"&gt;</code> - external reference</li>
223
                <li><code>&lt;a
224
               class="javalink" href="<em>className</em>(#<em>methodName</em>)?"&gt;</code> - link to Javadoc</li>
225
            </ul>
226
            <p>Relative links can be used also, this can be useful because it makes the links more
227
                resilient when refactoring. So, to access a sibling topic the link
228
                    <code>../graphics</code> can be used to access <a href="../graphics">Using
229
                    Graphics</a>.</p>
230
            <p>For a child topic, just include the topic name, like <code>child</code> to access the
231
                    <a href="child">Child Topic</a> in this section.</p>
232
            <section id="child" title="Child Topic">
233
                <h1>Child Topic</h1>
234
                <p>The text of a child topic.</p>
235
            </section>
236
        </section>
237
        <!-- TODO - link checker not implemented -->
238
        <!--<section id="checking-links" title="Checking Links">
239
            <h1>Checking Links</h1>
240
            <p>For convenience, this help-system includes a client-side link checker. This scans all
241
                internal site links, checking for referential integrity. A summary of all broken
242
                links is shown in a panel displayed at the bottom of the web page. </p>
243
            <p>To display the Page Analyser panel, add the <code>test=ON</code> URL parameter to the
244
                website address URL in the browser.</p>
245
            <samp>http://localhost/viewer_app/<strong>?test=ON</strong>#!help-system/authoring/checking-links</samp>
246
            <p> The link-checker is then started by clicking on the <code>Check Links</code> button.
247
                Broken link details are listed, including a hyperlink to the container page for
248
                each link.</p>
249
        </section>-->
250
        <section id="graphics" title="Using Graphics">
251
            <h1>Using Graphics</h1>
252
            <p>Images should be referenced using the usual </p>
253
            <samp><![CDATA[<img src="/docimg/graphic.jpg"/>]]></samp>
254
            <p>
255
                <img src="/docimg/black-knight.png" alt="picture of a black knight chess piece."/>
256
            </p>
257
            <p>The HTML 5 <code>figure</code> and <code>figcaption</code> elements could be
258
                supported in future</p>
259
            <hr/>
260
            <p>Other resources, such as PDFs may also be referenced using links to internal
261
                resources, for example <a href="/docimg/web-changes.pdf">web-changes.pdf</a></p>
262
        </section>
263
        <section id="markup" title="Using Markup">
264
            <h1>Using Markup</h1>
265
            <p>Code samples use the HTML <code>samp</code> element as follows:</p>
266
            <samp><![CDATA[<html>
267
    <head></head>
268
    <body>
269
        <p>First Para</p>
270
        <p>Second Para</p>
271
    </body>
272
</html>]]></samp>
273
            <p>Text sections that are asides (annotations to the main topic) are marked using the
274
                    <code>aside</code> element:</p>
275
            <aside>
276
                <p>This is an <strong>important</strong> aside</p>
277
                <ul>
278
                    <li>Rendered with highlighted background and italics by default</li>
279
                </ul>
280
            </aside>
281
            <p>The <code>hr</code> element can be used to split sections (see also <a
282
                    href="subtitles">Using Sub-titles</a>).</p>
283
            <hr/>
284
            <p>The <code>code</code> element is used for inline code or
285
                programming-terms. The <code>strong</code> and <code>em</code> elements are
286
                rendered as <strong>bold</strong> and <em>italic</em> respectively by default.</p>
287
            <p>The <code>dfn</code> element is now used instead of the <code>index</code> element to
288
                mark up terms suitable for adding to an index. The block <code>kbd</code> element is
289
                used to highlight command-line entry:</p>
290
            <kbd>java -s -t keyboard-entry</kbd>
291
            <p>See also:</p>
292
            <nav>
293
                <ul/>
294
            </nav>
295
            <section id="tables" title="Using Tables">
296
                <h1>Using Tables</h1>
297
                <p>Tables are rendered as shown.</p>
298
                <table>
299
                    <thead>
300
                        <tr>
301
                            <td>
302
                                <p>small number</p>
303
                            </td>
304
                            <td>
305
                                <p>big</p>
306
                            </td>
307
                        </tr>
308
                    </thead>
309
                    <tbody>
310
                        <tr>
311
                            <td>one</td>
312
                            <td>one thousand<br/>multi-line</td>
313
                        </tr>
314
                        <tr>
315
                            <td>two</td>
316
                            <td>two thousand<br/>multi-line</td>
317
                        </tr>
318
                    </tbody>
319
                </table>
320
            </section>
321
            <section id="lists" title="Using Lists">
322
                <h1>Using Lists</h1>
323
                <p>Ordered or Unordered lists are styled in the usual way:</p>
324
                <ol>
325
                    <li>alpha <ol>
326
                            <li>sub-alpha</li>
327
                            <li>sub-alpha-2</li>
328
                        </ol></li>
329
                    <li>bravo</li>
330
                </ol>
331
332
                <ul>
333
                    <li>alpha <ul>
334
                            <li>sub-alpha</li>
335
                            <li>sub-alpha-2</li>
336
                        </ul></li>
337
                    <li>bravo</li>
338
                </ul>
339
            </section>
340
            <section id="subtitles" title="Using Sub-titles">
341
                <h1>Using Sub-titles</h1>
342
                <p>There is no dedicated element for sub-titles in HTML-5, but a class attribute
343
                    value of <code>subtitle</code> for a header element like <code>h1</code>
344
                    provides the same effect:</p>
345
                <h2 class="subtitle">First Sub-Title</h2>
346
                <p>Text below the sub-title. Sometimes it is more helpful to refactor pages divided
347
                    in such a way into sub-pages by using a child <code>section</code> element.</p>
348
                <h2 class="subtitle">Second Sub-Title</h2>
349
                <p>Text below the sub-title.</p>
350
            </section>
351
        </section>
352
353
    </section>
354
</article>