WebHowTo Document Structure

Table of Contents

Appendices


1. Introduction

The DTD WebHowTo.dtd provides in principle a subset of the functionality from the DocBook DTD. In practice it isn't like DocBook at all; but it was inspired by DocBook. Basically I just wanted to use XML to generate web-based how-tos that fulfill my needs. So this WebHowTo DTD is the result.

This XSLT stylesheet WebHowTo.xsl is used to generate HTML. To make life a little easier (pun intended :-) I use a Makefile to validate the XML and to generate the HTML. As you can see it invokes xmlproc_val and xalan to accomplish these tasks.

Notice that the xslt file refers to another xslt file: WebHowTo_vars.xsl. This file contains variables that one would typically like to change between documents, such as the CSS style sheet, the author's name, a favicon, etc. for the document to be generated.

The DTD and stylesheets will mutate somewhat as I work my way through my web tree, converting existing HTML to XML. I am learning as I go, and frequently

Here is a table of the files mentioned above, without the HTML markup. You would have to <shift-click> in mozilla to save them locally using Mozilla:
File NamePurpose

WebHowTo.dtdthe DTD file
WebHowTo.cssthe CSS stylesheet
Makefilethe makefile to aid HTML generation
WebHowTo.xslthe XSLT stylesheet
WebHowTo_vars.xslextra XSLT stylesheet

2. The Major Elements of a WebHowTo XML Document

2.1  WebHowTo

The <WebHowTo/> element is the root element of this XML document type.

2.2  comment

Optional <comment/> elements may precede the main title element. The purpose of the comment elements is add any HTML-style comments to the generated document. They will appear before the first section of the document.

2.3  title

A WebHowTo document must have a <title/> as the first child element.

2.4  section

One or more <section/> elements are required.

2.5  appendices

An optional <appendices/> element follows the <section/> elements.

2.6  footer

The last element must be the <footer/>. Only one is allowed.

3. Description of Major Elements' Children

Most of the major elements of a WebHowTo are constrained - they may only contain other elements. The <title/> tag may only contain parsed character data.

At a deeper level most of the elements contain a <block/> element, which is described in greater detail in a following section.

3.1  The Child Elements of a section Element

3.1.1  title

A section element must have a <title/> as the first child element.

3.1.2  prolog

A <prolog/> element is not required, but if present it must come right after the title element, but before all other section child elements. Only one prolog is allowed per section.

3.1.2.1  The Child Elements of a prolog Element

Only <block/> elements are allowed in a <prolog/> element.

3.1.3  sect2 | block

Either <sect2/> elements or <block/> elements are next allowed as children of a section element. Zero or more of the same element type are allowed.

3.2  The Child Elements of a sect2 Element

3.2.1  title

A sect2 element must have a <title/> as the first child element.

3.2.2  sect3 | block

Either <sect3/> elements or <block/> elements are next allowed as children of a section element. Zero or more of the same element type are allowed.

3.3  The Child Elements of a sect3 Element

3.3.1  title

A sect3 element must have a <title/> as the first child element.

3.3.2  block

Either <sect4/> elements or <block/> elements are next allowed as children of a section element. Zero or more of the same element type are allowed.

3.4  The Child Elements of a sect4 Element

3.4.1  title

A sect4 element must have a <title/> as the first child element.

3.4.2  block

Only <block/> elements are allowed after the title element. Zero or more block elements are allowed.

3.5  The Child Elements of an appendices Element

3.5.1  appendix

One or more <appendix/> elements are the only valid children of the appendices element.

3.6  The Child Elements of an appendix Element

3.6.1  title

An appendix element must have a <title/> as the first child element.

3.6.2  block

Zero or more <block/> elements are the only valid children of the appendix element.

3.7  The Child Elements of a footer Element

3.7.1  date

A footer element has <date/> elements only.

4. Block Elements

4.1  Elements allowed in a block Element

All the major elements which contain other elements reduce to the <block/> element. This section describes the block element.

Aside from simple character data, a block element may contain the following elements.

4.1.1  Tags Constrained to Contain Elements Only

<list/>, <table/>
TagDescription

lista list-based element
tablea tabular element

4.1.2  Tags Containing Both Elements and Character Data

<item/>, <def/>, <output/>, <i/>, <b/>, <u/>, <code/>
TagDescription

itema member of a list
defa term definition in a definition list
outputa text block representing terminal output
iitalics emphasis
bbold emphasis
uunderline emphasis
codefixed-font output

4.1.3  Tags Allowing Only Parsed Character Data

<term/>, <tag/>, <attr/>, <c/>, <f/>, <rpm/>, <url/>, <prompt/>
TagDescription

terma term in a definition list
tagdelineates a bracketed markup tag
attrdesignates an attribute
cindicates a program, a command
findicates a file
rpmindicates an RPM
urlprovides a URI link
promptformatted like a command-line prompt

Appendix A : List of Tags

This is the list of tags referenced in this document:

Appendix B : List of Programs

This is the list of programs referenced in this document:


Contact: http://penguin.triumf.ca/home/
Created: Sun Mar 23 15:11 MET 2003
Last Modified: Mon May 31 17:52 2004 Last Modified: Mon May 31 17:52 2004
Copyright © 2004, Denice Deatrich

Document generation: http://penguin.triumf.ca/xml/WebHowTo.html

Number of sections provided: 4