doc/intro.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE chapter SYSTEM "../doc.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../html.xsl"?>
   4
   5 <!--
   6       XML documentation system
   7       Original author :  Arjen Baart - arjen@andromeda.nl
   8       Version         : $Revision: 1.3 $
   9 -->
  10
  11 <chapter>
  12 <heading>Introduction</heading>
  13
  14 <para>
  15 <LaTeX command='\setlength{\parindent}{0cm}'/>
  16 <LaTeX command='\setlength{\parskip}{0.4cm}'/>
  17 XMLDoc is a collection of stylesheets and utilities, resembling a
  18 documentation system like sgmltools and Linuxdoc.
  19 The objective is to prepare documentation in XML format.
  20 Other formats, like LaTeX, PostScript or HTML are then generated by
  21 transforming the XML source document into other formats.
  22 The transformation is performed by an XSLT processor and using
  23 XSL stylesheets for a specific output format.
  24 </para>
  25
  26 <section>
  27 <heading>XMLDoc concepts</heading>
  28
  29 <para>
  30 Writing documents in XML is rather like writing them in HTML.
  31 The content is just plain text and the markup, or layout, is defined
  32 with tags, which are marked in angle brackets (&lt; and &gt;).
  33 A tag marks the beginning or end of an element, where an element is something
  34 like a chapter, a section or a phrase of emphasized text.
  35 The tags are processed by the XML parser and translated to the output
  36 format commands, as defined by the XSL stylesheet.
  37 </para>
  38
  39 <para>
  40 You can not use every tag just anywhere in your document.
  41 There is a certain amount of structure you must adhere to.
  42 This structure is defined in the <emph>Document Type Definition (DTD)</emph>.
  43 </para>
  44 </section>
  45
  46 <section>
  47 <heading>XMLDoc in practice</heading>
  48 <para>
  49 Using XMLDoc is fairly simple.
  50 To use XMLDoc, all you need is a plain text editor, such as vim or emacs
  51 and a working installation of the XMLDoc utilities and stylesheets.
  52 The utilities constitute a special form of XSLT processor and a few
  53 shell scripts that invoke this XSLT processor with the proper style sheets.
  54 </para>
  55
  56 <para>
  57 Since there are three XSLT sheets, there are also three shell scripts:
  58 <code>xml2html</code>, <code>xml2latex</code> and <code>xml2text</code>.
  59 These scripts transform the XMLDoc document into HTML, LaTeX and plain
  60 text output, respcetively.
  61 All you need to do is create your XML source document and use one of these
  62 scripts to transform the document an another format.
  63 For example, to transform this guide into a LaTeX document, you could
  64 use:
  65 </para>
  66
  67 <verbatim>
  68    xml2latex guide.xml >guide.tex
  69 </verbatim>
  70
  71 <para>
  72 Note that the transformed document is written to standard output.
  73 </para>
  74 </section>
  75 </chapter>