"xsltdoc" notes                                        Revised: 120707
----------------------------------------------------------------------

1. Overview.

1.1. XSLT is both an  XML-based language  and  a way to transform XML-
based data files into files of other types. It (XSLT) can be used, for
example, to  convert  a book or article  that's stored in an XML-based
document format to an HTML web page.

Since XSLT programs  (also known as XSLT stylesheets)  can  generate a
number of output formats, they may simplify the process of maintaining
documentation for a project.  The basic idea is that a document can be
written once, in an XML-based format,  and then transformed  to  other
formats as necessary.

This approach to documentation isn't unique to XSLT.  LaTeX, Restruct-
ured Text, and other frameworks can be used for similar purposes.  But
XML-based  formats are  quite common,  for documents  as well as  data
files in general,  and  XSLT is  uniquely suited  for work on files of
this type.

Additionally,  the major  web  browsers support XSLT internally.  This
means that, theoretically,  web pages can be written in XML plus XSLT,
displayed directly by browsers, and converted to other formats through
the use of alternate XSLT stylesheets.

1.2. This project is  the start of an XSLT tutorial and  the core of a
documentation toolset that may grow over time. It provides two related
XSLT stylesheets that can be   used to transform XML documents written
using  a  simple XML-based format into DokuWiki and HTML,  respective-
ly:

      xmldoc2dokuwiki.xsl - XSLT file that converts XML to DokuWiki

      xmldoc2html.xsl     - XSLT file that converts XML to HTML

1.3. "xsltdoc" was created by OldCoder:

      Site:    http://oldcoder.org/
      Mail:    oldcoder@yahoo.com
      GitHub:  https://github.com/OldCoder/
      Repo:    https://github.com/OldCoder/xsltdoc.git

The license used for the current version is MIT/X.

----------------------------------------------------------------------

2. Screenshots.

Two screenshots are included.  They're in the  "images" directory that
comes with this README file:

xsltdoc-screenshot-dokuwiki.png - This  image  shows  sample  DokuWiki
output produced by this package as displayed by the Epiphany web brow-
ser.

xsltdoc-screenshot-html.png - This  image  shows sample HTML output as
displayed by the same browser.

The same XML input file was used in both cases.

----------------------------------------------------------------------

3. Development.

3.1. Source code.

Full source code  for the project is provided in the same directory as
this README file. The code consists simply of the two XSLT stylesheets
listed in part 1 above (Overview).

3.2. Requirements.

3.2.1. XSLT 1 processor.

For basic operation, requirements are Linux, the two XSLT stylesheets,
and a standard tool  named "xsltproc".  "xsltproc" is provided by most
major Linux distros;  in some cases, it's preinstalled, and in others,
it can be obtained from distro repositories.

You  can  use Xalan instead of "xsltproc". Note that usage is slightly
different for Xalan; for more information, see part 4 below (Usage).

Note:  Presently,  the XSLT stylesheets  are written in XSLT 1;  i.e.,
they don't rely  on  XSLT 2 features.  Therefore,  an XSLT 2 processor
isn't needed.

3.2.2. Miscellaneous tools.

If you'd  like  to  produce PDF output,  a program named "wkhtmltopdf"
should be installed.  For more information about  the program in ques-
tion, visit:

      http://code.google.com/p/wkhtmltopdf/

To use the "Makefile" provided in the "examples" directory  (which re-
builds some sample output) you'll need  "make" in addition  to  "xslt-
proc" and possibly "wkhtmltopdf".

3.2.3. Displaying the output.

To display HTML output, you'll need a web browser that supports modern
CSS standards.

To view DokuWiki output, you'll need both a web browser and a DokuWiki
server or website. The DokuWiki server or website will need to include
the DokuWiki "xterm" plugin.

The Linux programs "evince", "epdfview", and "xpdf" (among others) may
be used to show PDF output.

3.3. Installation.

No "build" is needed.

To install  the package,  simply copy the two ".xsl" files provided to
wherever you'd like to store them.

If you'd like to work with the examples provided,  store the directory
tree that contains this README file somewhere  in its entirety.  Note:
The directory structure must be preserved.

----------------------------------------------------------------------

4. Usage.

4.1. Using "xmldoc2dokuwiki.xsl".

"xmldoc2dokuwiki.xsl" is an XSLT stylesheet  that converts  XML-format
documentation to DokuWiki format.

To use this stylesheet under Linux,  execute an "xsltproc" CLI command
of the form:

      xsltproc xmldoc2dokuwiki.xsl input.xml > output.dokuwiki

"input.xml"  should be  an XML file containing  documentation or text.
The XML file should conform to the format described in Appendix A.

Substitute an appropriate pathname for the ".xsl" file if necessary.

4.2. Using "xmldoc2html.xsl".

"xmldoc2html.xsl" is an XSLT stylesheet that converts XML-format docu-
mentation to HTML format.  The HTML output  is styled by  embedded CSS
code.

To use this stylesheet under Linux,  execute an "xsltproc" CLI command
of the form:

      xsltproc xmldoc2html.xsl input.xml > output.html

"input.xml"  should be  an XML file containing  documentation or text.
The XML file should conform to the format described in Appendix A.

Substitute an appropriate pathname for the ".xsl" file if necessary.

4.3. Xalan.

In most cases,  "Xalan"  should work as a  substitute for  "xsltproc".
Note that the order of the arguments is reversed for "Xalan":

Xalan DokuWiki example:

      Xalan input.xml xmldoc2dokuwiki.xsl > output.dokuwiki

Xalan HTML example:

      Xalan input.xml xmldoc2html.xsl     > output.html

4.4. Examples.

This project  provides an "examples" directory that  includes a sample
XML input file, sample output files  (in  DokuWiki, HTML, and PDF for-
mat), and a "Makefile" that can rebuild the output files. For more in-
formation,  go  to the "examples" directory and see the following file
there:

      README-EXAMPLES

----------------------------------------------------------------------

5. Technical notes.

5.1. For more information on DokuWiki, visit:

      http://en.wikipedia.org/wiki/Dokuwiki

5.2. "xmldoc2dokuwiki.xsl" knows how to "escape" the most common Doku-
Wiki markup sequences if they happen to occur inside input-text nodes.
For example, 'C' declarations of the following form:

      int **foo;

will be replaced with:

      int *////*foo;

----------------------------------------------------------------------

Appendix A. XML input format.

A.1. XML core input elements.

The following  XML input elements  should be  sufficient for many pur-
poses:

code        - Defines a block of code. Used as follows:

              <code>lines of code</code>

              For HTML, maps to a CSS-styled  "div" named "code".  For
              DokuWiki, maps to ''lines of code''.

function    - Defines a function block. Used as follows:

              <function name="foo">
                  related elements go here
              </function>

              For HTML,  maps to a  CSS-styled  "div" named "function"
              that includes a  function-name line.  For DokuWiki, maps
              to a "=== name ===" block.

label       - Defines text that should be treated as a label;  i.e., a
              name that should be emphasized. Used as follows:

              <label name="x_counter" />

              For HTML, maps to a CSS-styled "span" named "label". For
              DokuWiki, maps to **name**.

link        - Defines a hyperlink. Used as follows:

              <link target="http://foo/" name="Short description" />

              For HTML, maps to a standard  "<a>" element.  For  Doku-
              Wiki, maps to a "[[target|name]]" construct.

note        - Defines text that should be treated as a note (for exam-
              ple, as an FYI or a warning). Used as follows:

              <note>One or more lines of text</note>

              For HTML, maps to a CSS-styled "span" named "note".  For
              DokuWiki, maps to //text//.

section     - Defines a section block. Used as follows:

              <section title="Popular Recipes">
                  <section title="Meat">
                      ...
                  </section>
                  <section title="Vegetarian">
                      ...
                  </section>
              </section>

              For HTML,  maps to a  CSS-styled  "div" named  "section"
              that includes a section-name line.

              For DokuWiki,  maps to a  "=== foo ===" block  with  the
              appropriate  number of "equals" signs determined automa-
              tically.

text        - Defines a block of text. Used as follows:

              <text>One or more lines of text.</text>

              For HTML, maps to a  CSS-styled "div" named "text".  For
              DokuWiki, simply produces  a block  of text followed  by
              two newlines.

xterm       - Multi-purpose element. Used as follows:

              <xterm>one or more lines of text</xterm>

              For HTML,  maps  to a  CSS-styled  "div" named  "xterm".
              For DokuWiki, maps to a DokuWiki "<xterm>" block.  Note:
              This feature requires the "xterm" plugin for "DokuWiki".

----------------------------------------------------------------------

A.2. Additional XML input elements.

The following XML input elements are also supported:

cproto      - (Deprecated by "proto".) Defines a 'C' prototype defini-
              tion block. Used as follows:

              <cproto>lines of code</cproto>

              For HTML,  maps  to a  CSS-styled  "div" named "cproto".
              For DokuWiki, maps to:

              <xterm>%%lines of code%%</xterm>
              two newlines

              Note: This feature requires the "xterm" plugin for "Dok-
              uWiki".

desc        - Presently, equivalent to "text".

namedvar    - Presently, equivalent to "label".

proto       - Defines  a  programming  language  prototype  definition
              block. Used as follows:

              <proto lang="c">lines of code</proto>

              For HTML,  maps  to a  CSS-styled  "div" named  "proto".
              For DokuWiki, maps to:

              <xterm>%%lines of code%%</xterm>
              two newlines

              Note: This feature requires the "xterm" plugin for "Dok-
              uWiki".