From 1eeaab9094e6666a8a5860dd36545e03c4c4fa7b Mon Sep 17 00:00:00 2001 From: arjen Date: Tue, 19 Aug 2003 06:48:54 +0000 Subject: [PATCH] Added a glossary with an alphabethical list of elements along with a few other things. --- doc/glossary.xml | 245 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/guide.xml | 52 ++++++++++-- doc/inline.xml | 40 ++++++++- doc/intro.xml | 34 +++++++- doc/main.css | 8 +- doc/makefile | 2 +- doc/multifiles.xml | 4 +- doc/overall.xml | 17 +++- 8 files changed, 382 insertions(+), 20 deletions(-) create mode 100644 doc/glossary.xml diff --git a/doc/glossary.xml b/doc/glossary.xml new file mode 100644 index 0000000..7598ed8 --- /dev/null +++ b/doc/glossary.xml @@ -0,0 +1,245 @@ + + + + + + + +Glossary + + + Alphabetical list of elements: + + + + Optional part of the title page. States in a few + sentences what the document is about. + + + + One of the document styles. + Defines what kind of document this is. + + + + Part of the title page. States by whom the + document was written. There must be at least one author on a title page. + + + + One of the document styles. + Defines what kind of document this is. + + + + The first level of sectioning elements. + + + + A form of inline content for making code + examples. Usually renders to a monospace font. + + + + A single cell of content in a table. + + + + Part of the title page. States when the + document was written. + + + + Creates a list of descriptive items. + + + + The single root element of all XMLDoc documents. + + + + Optional block of information about the document. + Contains a list of one or more infoitem elements. + + + + A form of inline content for making emphasized + text. Usually renders to some form of italic. + + + + Creates a list of numbered items. + + + + Creates a numbered footnote at the bottom of the page. + + + + Holds the heading of any one of the sectioning elements. + This heading is printed in larger font at the top of the sectioning + element and is used to create the table of contents (toc). + + + + Includes part of the document from another file. + + + + An informational item on the title page. Holds + additional information about the document, such as version number or + organization. + + + + One item in a list of items. + + + + Creates a list of bulleted items. + + + + Used for internal references. + Marks a point in the document that can be referred to by a ref + element. + The name attribute sets the name that can be referred. + + + + LaTeX escape element. Copies the content of the + command attribute literally to the LaTeX output. + + + + Forces a line break in the output document. + + + + Forces a page break in the output document. + Used only for LaTeX output. + + + + Used for internal references. + Creates a page number to a label element. + The name of the label is put in the to attribute. + Used only for LaTeX output. + + + + The primary block-level element to hold the textual + content of the document. + + + + The fifth level of sectioning elements. + + + + Imports pictures into the document. + + + + A quotation is a slightly indented block of text. + + + + Used for internal references. + Creates a reference to a label element. + The name of the label is put in the to attribute. + + + + Used for external references. + Creates a reference to an external document pointed to by the + href attribute. + + + + + A form of inline content for making a remark + that stands out from the rest of the text. The final rendering is not really + defined and mey depend on other stylesheets. + E.g. for HTML output, this creates a span tag with remark + class attribute. The way this looks is determined by a CSS stylesheet. + + + + One of the document styles. + Defines what kind of document this is. + + + + A row of columns in a table. + + + + The second level of sectioning elements. + + + + A form of inline content for making + strong text. Usually renderd in bold. + + + + A form of inline content for making + subscript text. + + + + The sixth level of sectioning elements. + + + + The third level of sectioning elements. + + + + The fourth level of sectioning elements. + + + + Optionally, a document can have any number of subtitles added to + the title. + + + + A form of inline content for making + superscript text. + + + + Creates tabular content. + + + + Optional first header row of a table. + + + + Mandatory first element of the title page. + + + + Optional title page to hold the document's + title and author, along with some other information. + + + + Automatically generated table of contents. + + + + A block-level element to hold text with a + pre-determined layout. Mainly used for coding examples. + + + + + diff --git a/doc/guide.xml b/doc/guide.xml index 8a5659b..f314395 100644 --- a/doc/guide.xml +++ b/doc/guide.xml @@ -6,7 +6,7 @@ -Type styles and special characters + There are six type styles: @@ -23,6 +23,42 @@ There are six type styles:
+ + + +You can force the start of a new line of output with the empty +newline element. +This element has no attributes and no content. +Starting a new page with the newpage element is only +usefull when you create LaTeX output. + + +
+ +
+ + + +You can insert eny piece of text into a specific output target by using +an escape element. An escape element is an element with the name of the +output format and a single command attribute. +For example, the LaTeX is used to put arbitrary text into +the output of xml2latex. +The content of its command attribute is copied literally +into the output. +One of the applications of the LaTeX escape element is to +control the first line indent of a paragraph in LaTeX: + + +<LaTeX command='\setlength{\parindent}{0cm}'/> + + +Note that it is not possible to create HTML tags in this manner. + + +
+ +
Special characters diff --git a/doc/intro.xml b/doc/intro.xml index 6e80a81..5dc1c92 100644 --- a/doc/intro.xml +++ b/doc/intro.xml @@ -5,7 +5,7 @@ @@ -14,7 +14,7 @@ -XML-doc is a collection of stylesheets and utilities, resembling a +XMLDoc is a collection of stylesheets and utilities, resembling a documentation system like sgmltools and Linuxdoc. The objective is to prepare documentation in XML format. Other formats, like LaTeX, PostScript or HTML are then generated by @@ -24,7 +24,7 @@ XSL stylesheets for a specific output format.
-XML-doc concepts +XMLDoc concepts Writing documents in XML is rather like writing them in HTML. @@ -42,4 +42,32 @@ There is a certain amount of structure you must adhere to. This structure is defined in the Document Type Definition (DTD).
+ +
+XMLDoc in practice + +Using XMLDoc is fairly simple. +To use XMLDoc, all you need is a plain text editor, such as vim or emacs +and a working installation of the XMLDoc utilities and stylesheets. +The utilities constitute a special form of XSLT processor and a few +shell scripts that invoke this XSLT processor with the proper style sheets. + + + +Since there are three XSLT sheets, there are also three shell scripts: +xml2html, xml2latex and xml2text. +These scripts transform the XMLDoc document into HTML, LaTeX and plain +text output, respcetively. +All you need to do is create your XML source document and use one of these +scripts to transform the document an another format. +For example, to transform this guide into a LaTeX document, you could +use: + + + xml2latex guide.xml >guide.tex + + +Note that the transformed document is written to standard output. + +
 diff --git a/doc/main.css b/doc/main.css index 4ada333..dbb3494 100644 --- a/doc/main.css +++ b/doc/main.css @@ -46,7 +46,7 @@ div.titlepage p { - font-size : 90%; + font-size : 100%; } span.remark @@ -64,3 +64,9 @@ table border-collapse : collapse; padding : 1px ; } + +dt +{ + font-weight : bold ; + top-margin : 1ex; +} diff --git a/doc/makefile b/doc/makefile index 9c1daa2..bdebd00 100644 --- a/doc/makefile +++ b/doc/makefile @@ -7,7 +7,7 @@ .obj.eps: tgif -print -eps -color $< -XMLS = guide.xml intro.xml overall.xml block.xml inline.xml multifiles.xml +XMLS = guide.xml intro.xml overall.xml block.xml inline.xml multifiles.xml glossary.xml IMAGES= PICTURES= diff --git a/doc/multifiles.xml b/doc/multifiles.xml index 6a44031..ea9c715 100644 --- a/doc/multifiles.xml +++ b/doc/multifiles.xml @@ -5,7 +5,7 @@ @@ -16,7 +16,7 @@ and output. Well, not really. Multiple output files is not implemented yet :-)
-Multiple input files + You do not need to create one single big XML file that contains all of your story. diff --git a/doc/overall.xml b/doc/overall.xml index d662a76..22ac06c 100644 --- a/doc/overall.xml +++ b/doc/overall.xml @@ -5,12 +5,12 @@ -Overall document structure + All XML-doc documents are set up in a similar way. @@ -60,7 +60,7 @@ The example shows a minimal XML-doc document:
-Preamble + The document preamble is everything that comes before the real page of text. Typical elements of the preamble are the title page and the table of contents. @@ -104,12 +104,15 @@ All it takes is an empty toc element: The table of contents is optional, but if you use it, it must come between the title page and the first chapter. +Note for LaTeX: to actually make the table of contents, you +need to run latex twice. LaTeX does not do this in +a single pass.
-Sectioning and Paragraphs + After the opening tag of the first chapter, the document really begins. @@ -131,6 +134,12 @@ Note that the names are equivalent to their counterparts in LaTeX. +Just as in LaTeX, the article document type does not have +a chapter element. +The top-level sectioning element for an article is a +section. + + After the open tag of a sectioning element (chapter, section, subsection or subsubsection, etc.) comes the heading element, followed by the block level content -- 2.11.0