This section has been added because SGML (or to be more precise: the LinuxDoc DTD) still seems to be difficult for beginners that want to write documentation. When looking at some KDE applications, I have seen some that contain an sgml file which is the template - but the author went over to edit the html output instead of the sgml file. This results in problems that translators have - if they want to provide documentation for your application in their native language, they will have to edit each file as well in HTML and this makes it impossible to reuse the documetation for other formats not only in the english version but all internationalized versions as well. You see that this is very short-thinking and a bad situation; personally I think that this results from the author's knowledge of HTML but not of SGML. As most will try to avoid learning a new formatting language, they will use the HTML output as the template that they edit. If you once find out how easy (and useful) SGML with LinuxDoc is, you will know that it's worth to learn a few more tags that built the SGML formatting.
The following sections will therefore introduce you to the most important parts of an LinuxDoc sgml file and how to extend your documentation.
An SGML file, whatever DTD it may use, always has to start with the DTD declaration. This tells the SGML parser about which DTD to use. Therefore, the first tag (a bracketed expression like <yourtag> your contents </yourtag>) is always the DOCTYPE:
<!doctype linuxdoc system>
That tells your sgml formatter that it shall use the LinuxDoc DTD.
Now, when using the LinuxDoc, the next tag is the start tag for the document style type. The LinuxDoc DTD offers a whole set of types that you can select from, dependent on the purpose of your document or it's legth. Available formats are:
<notes> for short explanations
<article> for writing articles with abt. 10-20 pages (suggested). This is used by the templates of KDevelop and most KDE applications.
<report> for articles that are longer than an <article> type
<book> for writing large books - the KDevelop handbooks have been written using this document type
<slides> for slideshows. This is useful for presentations. You will use latex as output format in most cases, of course.
<letter> for normal letters
<telefax> for a telefax
<manpage> for a manpage
Mind that these are only describing how the document structure will look like in general - not the actual output. As mentionend, the KDevelop default generated template is using the <article> structure. This is used by most applications except KDevelop itself which uses the <book> format. In the HTML output this doesn't really matter much - but for latex e.g. this makes much difference. The handbooks are really "books" with separate pages for each chapter as the main difference.
What follows is that the end of the sgml file must have an end-tag for the document structure type - for <article> this would be </article>.
Now, after the document structure follows a section that describes all entries usually found on a titlepage. The predefined template doesn't use this explicitely but only sets the information for <title>, <author> and <date> as this lasts for most purposes. Especially when using a <book> structure, you probably want to define a complete titlepage. The following lists the according tags for this, taken from the sgml source of this handbook:
1 <!doctype linuxdoc system> 2 <book> 3 <titlepag> 4 <title>The KDevelop Programming Handbook 5 <subtitle>The User Guide to C++ Application Design for the K Desktop Environment (KDE) with the KDevelop IDE, Version 1.0 6 <author> 7 <name>Ralf Nolden <htmlurl url="mailto:Ralf.Nolden@post.rwth-aachen.de" 8 name = "<Ralf.Nolden@post.rwth-aachen.de>"> 9 <inst>The KDevelop Team 10 <date>Version 2.1 , July 7, 1999 11 <abstract> 12 This handbook itself is part of the KDevelop Integrated Development Environment 13 and is therefore also licensed under the GNU General Public License; 14 see <ref id="Copyright" name="Copyright"> for more information. 15 </abstract> |
This covers all a normal titlepage usually contains. The <author> tag can also include a <thanks> tag to insert some thanks to co-authors, lecturers etc. <inst> represents the institute or company for which the author wrote the documentation; you could also use your team-name here like I did. <abstract> now covers an short description that is placed on the titlepage as well. This is somewhat annoying on a printed version where this section would be printed on the back of the title page where the copyright notice etc. are collected; this can be changed for latex output when editing the tex file.
The LinuxDoc DTD defines a set of tags for various indices as they occur in usual documents. Those are:
<toc> for the table of contents
<lof> for the list of figures
<lot> for the list of tables
The according start-tags don't necessarily require an end-tag; they're inserted just after the titlepage before the actual beginning of the document with the according sections or chapters.
Now, when it comes to indexing keywords for an index that is placed at the end of the document, you are provided four different tags; two which leave the indexed phrase within the page and two for index entries that are not displayed:
<idx> for a normal index entry
<cdx> for a true-type index entry
<nidx> for an index entry not appearing in the text document
<ncdx> as before for a tt-index entry
These tags are ignored by all backends (the tool that does the mapping of the sgml-tags to their document format) except sgml2latex, which generates an index file index.idx that can be turned to a tex-index with makeindex index.idx. The index itself can be inserted into the tex output file afterwards with \printindex. I patched my mapping for the latex output to do this automatically (but still don't know how to include the index into the table of contents...).
Now, after explaining most details of the general structure, we're coming to the actual document contents. Dependent on the document structure type, has to start with a <sect> tag, when using <book> you have to start with <chapt> for the chapters.
After the start tag, you can structurize each chapter with <sect1>, <sect2> etc. up to the allowed level of sub-sections (4).
The chapter start tag is followed by the chapter's title. There, you have the additional choice to use <title> and </title> for the chapter's title (optional). Now, afte the title of the chapter, you have to add a <p> tag to actually start with the subsection's contents. Within that, you have almost all means to format your document with list, enumerations, itemizations and description lists. Further, quotations, code snippets and the like can be inserted by tags; see you sgmltools documentation guide for a complete list. What you should look for is the "special characters" section. This contains all valid replacements for characters that are different from the usual alphabet like brackets, slashes and symbols like trademark etc. With the given tags you can structurize your text contents as you application documentation requires.