Linuxdoc Reference <subtitle>A introduction to the linuxdoc dtd</subtitle> Uwe B&oe;hme, <uwe@hof.baynet.de> v1.1, 30 January 2000 This article is intended to be a reference for the SGML document type definition linuxdoc, which is coming along with the SGML text formatting system version 1.0. It should also be applicable to future versions which may be found at . Making of

Legal stuff

. Please contact the authors if you are unable to get the license. This is free documentation. It is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. This document is not part of Genesis

This document was born trying to learn more about writing texts on my linux system. The one system looking like suitable to my needs was an the ) the overall structure is described nice and easy. Also [) was helpful, ). It's as detailed as hoped, but it's not made for the linuxdoc dtd dtd = document type definition file itself, and try to understand it. As time went by I noticed that I also forgot about some stuff, or - at least - didn't point it out strong enough. This will change within the next revision. Any feedback you might have is welcome (especially help with English spelling or grammar) by e-mail at . Introduction

You might want to call it wysiwym, i.e. "What you see is what you mean". You do not tell the program that this line should be in a bigger font, You do not need to mess around with fontsetting, line gaps or anything directly connected to the layout. In addition in all sgml-style documents you will find . A minimalistic document

In this section you'll find what you'll need for a minimalistic linuxdoc dtd conform document. It's intended to give a first touch. Skip this section, if you already now the principles. Step By Step

The steps you have to do to create a nice linuxdoc document and map it to the form you need are: Take a plain text editor of your choice. Create a file and name it (or later save it as) e.g. Type the document Save the file and close your editor. Run the checker by typing sgmlcheck start.sgml. If you get errors reported, reopen your document in your editor again and try to correct itThe error messages of will give you a hint about the type of error and also line and column where it occurred.. Run the checker again until no more errors occur. Now you have to decide what's your document for. . type|to produce@@
SGML-Tools mappers for sgml documents
 A Startup Document

We start with a simple document (the numbers and colon in the beginning of the line are for explanation, don't type it!): 1: <!doctype linuxdoc system> 2: <notes> 3: <title>A Small Linuxdoc Example&etago;title> 4: <p>Hello <em>world&etago;em>.&etago;p> 5: <p><bf>Here&etago;bf> we are.&etago;p> 6: &etago;notes> Now we take a look at the single lines: A linuxdoc document has to start, like all SGML conform documents, with the preamble. If you like you can take it as a piece of necessary magic, or you can try to find more information about SGML. The preamble is indicating to the SGML-parser, which dtd (document type definition) it should use for checking the syntax of the document. Open the for detailed description about that Even if optional it's a good idea to give a A paragraph marked by the Another completely tagged paragraph, with another word Here we close the open The same example may be written a little bit shorter, by leaving out tags which are placed automatically by the parser, and by using shortened tags: 1: <!doctype linuxdoc system> 2: <notes> 3: <title>A Small Linuxdoc Example 4: <p>Hello <em/world/. 5: 6: <bf/Here/ we are. 7: &etago;notes> Now we look at the single lines again: The The document class (also unchanged). The The paragraph is implicitly closing the /. The The empty line here is the reason, why you don't need to close the previous Another paragraph (not opened directly), with another short Closing the open Maybe now it's a little bit more clear, who you have to work with tags. Document Classes

<!element linuxdoc o o (sect | chapt | article | report | book | letter | telefax | slides | notes | manpage ) > This is describing the overall class of the document, so naturally it has (leave alone the doctype definition) to be the first tag enclosing your whole document. Some of the tags namely the ) doesn't make any sense taken them standalone despite being included as part of more complete classed document, so we'll describe them later as a part of the other document classes. Decide first which of the top mentioned document classes fits the type of the document you want to write best. To find a detailed description of the document classes see table . Chapter|Class tag@@ ||||||||
Document classes
To me the Article Tag

<!element article - - (titlepag, header?, toc?, lof?, lot?, p*, sect*, (appendix, sect+)?, biblio?) +(footnote)> You can see that the Titlepage Tag

<!element titlepag o o (title, author, date?, abstract?)> The Title Tag

<!element title - o (%inline, subtitle?) +(newline)> Each <title>Linuxdoc Reference <subtitle>A introduction to the linuxdoc dtd Author Tag

<!element author - o (name, thanks?, inst?, (and, name, thanks?, inst?)*)> Usually you place the (your) name here. People should know who wrote the document, so you place a Date Tag

Abstract Tag

). Header Tag

<!element header - - (lhead, rhead) > <!element lhead - o (%inline)> <!element rhead - o (%inline)> A Table Of Contents Tag

List Of Figures Tag

List Of Tables Tag

Body

. There is no Appendix Tag

Bibliography Tag

Footnote Tag

Report Tag

<!element report - - (titlepag, header?, toc?, lof?, lot?, p*, chapt*, (appendix, chapt+)?, biblio?) +(footnote)> The ). The rest of the structure is identical to the . Book Tag

<!element book - - (titlepag, header?, toc?, lof?, lot?, p*, chapt*, (appendix, chapt+)?, biblio?) +(footnote) > You will notice that the . So anything valid there is also valid if you classify your document with a Letter Tag

<!entity % addr "(address?, email?, phone?, fax?)" > <!element letter - - (from, %addr, to, %addr, cc?, subject?, sref?, rref?, rdate?, opening, p+, closing, encl?, ps?)> Also the purpose of the tag|mandatory|what's it@@ from|yes|from sender@ address|no|sender's address@ email|no|sender's email@ phone|no|sender's phone@ fax|no|sender's fax@ to|yes|receiver@ address|no|receiver's address@ email|no|receiver's email@ phone|no|receiver's phone@ fax|no|receiver's fax@ cc|no|carbon copy@ subject|no|letters subject@ sref|no|sender's reference@ rref|no|receiver's reference@ rdate|no|received date??@ opening|yes|opening@ paragraphs|yes|see @ closing|yes|closing@ encl|no|enclosure@ ps|no|post scriptum@
Tags in a letter
Telefax Tag

<!element telefax - - (from, %addr, to, address, email?, phone?, fax, cc?, subject?, opening, p+, closing, ps?)> Overall the structure is same to the Slides Tag

<!element slides - - (slide*) > The Slide Tag

<!element slide - o (title?, p+) > A ) and one or more ). That's all. Note Tag

<!element notes - - (title?, p+) > Intended as a class for personal notes the structure is even more simplified than the ). After classifying a document with the ) and one or more ) are allowed. Manual Page Tag

<!element manpage - - (sect1*) -(sect2 | f | %mathpar | figure | tabular | table | %xref | %thrm )> This document class is intended for writing ), for easy pasting manual pages into an Inlines

<!entity % inline " (#pcdata | f| x| %emph; |sq| %xref | %index | file )* " > . for detailed information. . . . Sectioning

<!element chapt - o (%sect, sect*) +(footnote)> <!element sect - o (%sect, sect1*) +(footnote)> <!element sect1 - o (%sect, sect2*)> <!element sect2 - o (%sect, sect3*)> <!element sect3 - o (%sect, sect4*)> <!element sect4 - o (%sect)> The is done by the according elements, forming the section tree. They are bringing the various paragraphs within our document to follow a nice tree. The top level tag and the allowed depth is varying with the ). The normal hierarchy is chapt sect sect1 sect2 sect3 sect4 Just take a book, look the table of conetents and you will see. Each of the tags out of the ). Within the you may place subordinate sections and ). Some of the sectioning tags may only appear in special document classes (). . Later when your document grows you might want to. Paragraphs

<!entity % sectpar " %par; | figure | tabular | table | %mathpar; | %thrm; | %litprog; "> <!entity % par " %list; | comment | lq | quote | tscreen " > <!entity % litprog " code | verb " > Each of the here described tags form a paragraph. For obvious reason a paragraph is normally. Normal Paragraph

Normal paragraphs can be formed in two ways: Paragraph tag

The Empty Newline

A empty line between two paragraph is implicitly starting a new List-like Paragraphs

<!entity % list " list | itemize | enum | descrip " > This four tags indicate the starting of a list-like paragraph. Within each of the lists the single items are separated by an <!element item o o ((%inline; | %sectpar;)*, p*) > As you can see, a item may again contain paragraphs (and therefore also may contain other lists - even of a different type). List Tag

<!element list - - (item+)> The <list> <item>A point <item>Another one <item>Last </list> Will look (depending on the mapping) like: A point Another one Last Itemize Tag

<!element itemize - - (item+)> The <itemize> <item>A point <item>Another one <item>Last </itemize> Will look (depending on the mapping) like: A point Another one Last Enum Tag

<!element enum - - (item+)> The <enum> <item>A point <item>Another one <item>Last </enum> Will look (depending on the mapping) like: A point Another one Last Descrip Tag

<!element descrip - - (tag?, p+)+ > The <descrip> <tag/sgml/structured general markup language. <tag/html - hypertext markup language/ A sgml implementation. It contains some concepts about linking information together in a very convenient way. This made it to be so successful and to become the standard for documents published by the internet. <tag/internet/A worldwide connected internet (internet here as a technical term) </descrip> Will look (depending on the mapping) like: Figures and Tables

The . h|here|At the same location as in the SGML file@ t|top|At the top of a page@ b|bottom|At the bottom of a page@ p|page|On a separate page only with figures and tables
Table Locations
The default value of the loc attribute is Table Tag

<!element table - - (tabular, caption?) > As you can see a ). The ). A short example will show how it's working together. <table loc="ht"> <tabular ca="lcr"> Look|this|table@ Isn't|it|nice@ 1.234|mixed|columns &etago;tabular> <caption>A sample table &etago;table> Look|this|table@ Isn't|it|nice@ 1.234|mixed|columns
A sample table
The Figure Tag

<!element figure - - ((eps | ph ), img*, caption?)> The usage of the Encapsulated Postscript™ Tag

<!attlist eps file cdata #required height cdata "5cm" angle cdata "0"> The A example: <figure loc="here"> <eps file="logo" height="4cm" angle="15"> <img src="logo.gif"> <caption>A included encapsulated postscript&ero;trade; &etago;figure> The A included encapsulated postscript™ file. The . Placeholder Tag

<!attlist ph vspace cdata #required> This tag doesn't place anything but keeps a clean space for good old manual picture pasting. The space kept free is destined by the . <figure loc="ht"> <ph vspace="5cm"> <caption>A blank space. &etago;figure> Results to:

A blank space for gluing a photo
At this point you might want to look for your scissors and the glue. Tabular Tag