BillTihen Ramin Miraftabi SEUL/edu This article describes the software needed to write DocBook documents (the list will grow so watch this document for updates). It also contains a and a quick introduction to configuring and using these tools with DocBook. 0.5 not done yet TO-DO: o Integrate jade and doc book into the SGML tools section. (ramin) o Write the section on customizing the output. (ramin) o Integrate comments from the LyX mailling list, that should be a good place to get some very honest feedback ;-). (bill) o Create tags refering to our other SEUL/edu documents. (bill) 0.4 20 December 1999 DONE: o Split this doc into 3 separate docs: SGML tools, SEUL/edu sgml standards, and including graphics. o Added Document Information section. o Removed and re-orded the sections that Ramin suggested. o I put the text-based editors first since they are the suggested method and the gui-based second since they are not really ready yet. o I also include a short section on the new GUI DocBook editor -- Conglomerate. o Organized the software into 2 sections -- SGML Document Prep (GUI and Text - based) and Document Processing/Publishing. o added web link to nedit o made nedit a section o config nedit. o Ramin and Bill are now co-authors o added nedit backspace (bill) o added nedit tabs spacing (bill) o add note about the CVS version being incomplete and needing to get file (the error messages I get and where to get the missing file and where to install it). (bill) 0.3a 10 December 1999 DONE o Ramin wrote the emacs and SGMLtools sections! o Ramin suggested splitting the document into 2 docs. I agree. 0.3 22 November 1999 DONE Lots of new content added. o Updated chapter section to section section. o Added stuff on RTF & PDF (no content yet). o Removed one of the EMACS sections & Syntax checking & Publishing Documents (they are covered in other areas). 0.2 29 October 1999 Second draft for review - sections started. 0.1 20 October 1999 First draft for review - mostly a skeleton.

This document is designed to help people find, install and use DocBook Software (hopefully so that they can help us with the SEUL/edu documentation project -- but we do forgive you if your interest lie else where and just found this information useful). This document is broken into 2 main sections — 1) SGML document preparation software (which is then subdivided into Text and GUI-based software) and 2) document processing software.

This document is intended to be read by people interested in writing documentation for SEUL/EDU.

DocBook and XML are the documentation formats of the future. LinuxDoc doesn't support screen shots -- will be necessary (or at least very helpful) for some of the software tutorials planned.

This document can be found at SEUL/edu (temporary?) Doc Site Please send corrections and suggestions to Bill Tihen at:

bill@tasis.ch

or Ramin Miraftabi at:

ramin@cs.joensuu.fi

.

The software is sorted into two categories: Text-based SGML document preparation and GUI-based SGML document preparation. We present text-based methods first because we recommend them over the current GUI software. Each tool is described to help you decide what tools will be the most helpful.

The authors currently recommend using a text-based method of document preparation. The gui-environments do not (yet anyway) support tags suggested in _SEUL/edu Documentation Standards: A Writer's Guide_. Furthermore they do not allow the author to work directly with sgml, or even import SGML files. However, there are a few disadvantages. One, the author must keep track of the document structure (a clear indentation system helps — however, it can still be difficult). Two, the author needs to be familiar with SGML tags. It is not enough to understand the content and the structure of the document. One of the author prefers to use nedit, which is a simple text editors, similar to ones found on Macintosh and Windows computers. Once the files are created you will need to use &SGMLtools; or jade to verify and generate the documents for others to read. The other author prefers &emacs; — a powerful text editor and development environment. There are other excellent editors for a graphical environment. Two good places to start looking for your favorite text-editor are: GNOME and KDE worlds. When you are finished typing your document simply use &SGMLtools; (see ) or jade (see ) directly to create your target documents.

Bill Tihen Advantages Nedit interface is simple, intuitive and familiar (for Mac & Windows users) — therefore, the learning curve is very short for most people. Nedit can easily be configured and adapted to suite an individual's preferences. Nedit supports color-syntax highlighting for many programming languages, html & sgml. Nedit supports searching using regular expressions. Disadvantages By default the keybindings are similar to Mac & Windows, this can be confusing to those use to using the Meta key. Document processing must be done at the command line. However, with &SGMLtools; (see ) this is very simple.

Nedit source code and binaries can be found at the following website: nedit .

As a text editor it is already configured to do what is needed, however, there are a few configuration options that are useful.

Now you will probably need to install the SGML highlighting module for nedit. If you don't already have it you will first need to download the file from sgml_html.pats. To install this module you will first need to start nedit in the following way: nedit -import /path-to-pats-file/sgml_html.pats Now open an SGML file and see if you like syntax highlighting. If Nedit isn't displaying the SGML file with syntax highlighting check the following things: Does the file name end with .sgml? If not, then you need to check the Language Mode. To do this you need to go to the menu-bar and choose: ALTp , l Preferences Language Mode SGML HTML Is syntax highlighting enabled? Check this by checking the Preferences menu and see if Highlight Syntax is selected (checked) — if it isn't then go ahead and select it. You can check it by going to the menu-bar and choosing: ALTp Preferences If you need to select it do so by going to the menu-bar and choosing: ALTp , h Preferences Highlight Syntax If you like syntax highlighting be sure it is selected as a default preference. Do this by going to the menu-bar and choosing: ALTp , d, h, n Preferences Default Settings Syntax Highlighting On . Now you will need to save this setting by going to the menu-bar and choosing: ALTp , v Preferences Save Defaults . Answer OK when it informs you that these settings will be saved in your .nedit file.

If you keyboard has a backspace key, you will probably want to enable it. Do so by adding the following line to your .nedit file. nedit.remapDeleteKey: True The help files contain a complete explanation of how to do this. Go to the menu-bar and choose: ALTh , c, x Help Customizing X Resources . This is set to false by default to avoid problems for those who use keyboards with only one backspace/delete key.

I like having the tabs I enter be converted to spaces. In this way the format of my SGML code will look the same in all text editors. Go to the menu-bar and be sure Emulate Tabs is selected: ALTp , t Preferences Tabs... Emulate Tabs . I like to set the Emulated Tab Spacing to 2 spaces. Do this by entering the number 2 into the Emulated tab spacing field (you can of course set this to whatever you like). If you have already closed the Tabs... dialog box you can open it again by going to the menu-bar and choosing: ALTp , t, e, s Preferences Tabs... Emulate Tabs Emulated tab spacing . For this to work properly be sure that the Use tab characters in padding and emulated tabs is NOT selected. If you like your tab settings be sure to set them in the Default settings so that you won't have to do this each time you start Nedit. Do this by going to the menu bar and choosing: ALTp , d, t Preferences Default Settings Tabs... . Just to be safe I save the default settings. ALTp , v Preferences Save Defaults . Answer OK when it informs you that these settings will be saved in your .nedit file. There are many more items that may be configured. Hopefully, at this point you are familiar with the process and can configure Nedit as you wish.

To start nedit you must first be running XWindows, then at the command line type: nedit file.sgml The rest should be clear.

Ramin Miraftabi &emacs; is a very powerful program that can do almost everything. It is an editor, SGML verifier, a mail reader (if you must), a news reader and an IDE environment. The power of Emacs comes from the way it can be extended to support almost anything, as long as someone bothers to create a mode or functions for it. To use Emacs in a fast and efficient way, one needs to become familiar with many keyboard shortcuts and some Emacs Lisp to configure Emacs the way you want it. My .emacs can be found at http://dawn.joensuu.fi/~ramin/config/emacs.html. Some people love the program and other people find it complex and clumsy. As you can expect, I'm one who loves and will leave a WYSIWYG editor at any time to use Emacs. Advantages All your SGML tools are in one spot. (With the exception of running &SGMLtools; from the command line.) Many people are familiar with it because it is also a powerful programming environment. The program runs under both text and graphical environments with the same key-combinations. It also runs on Windows 95/98/NT if needed, again with the same keyboard combinations. Disadvantages Many people find the &emacs; clumsy and overwhelming — especially in the text only mode. &emacs; is slow to start. Once started, it should be fast enough. In many cases the time to start it up can be minimized by learning to use multiple frames and buffers, but again, the learning curve is a bit steep.

&emacs; is best to install from your Linux distribution's packages. I wouldn't try installing it by hand. On RedHat systems the most interesting place to look to for adding packages to Emacs is /usr/share/emacs . I have installed &psgml; in /usr/share/emacs/site-lisp but another usual place to install it would be /usr/share/emacs/20.3/site-lisp. However, as the directory names imply, it is better to use the former since it is not dependent on &emacs;'s version. This means that it can be used by both &emacs; and XEmacs. &Psgml; is found at: http://www.lysator.liu.se/projects/about_psgml.html. After downloading the latest version (1.2.1 at the time of this writing) change in to the directory /usr/local/src (or any other place you see fit) and run the following commands. The commands must be issued as root and output from them has been supressed in some cases (represented by …). [root@reepycheep src]# tar xvfz ~ramin/tmp/psgml-1.2.1.tar.gz … [root@reepycheep src]# cd psgml-1.2.1/ [root@reepycheep psgml-1.2.1]# ./configure --prefix=/usr loading cache ./config.cache checking whether make sets ${MAKE}... (cached) yes checking for a BSD compatible install... (cached) /usr/bin/install -c checking for emacs... (cached) /usr/bin/emacs checking where .elc files should go... $(prefix)/share/emacs/site-lisp checking for makeinfo... (cached) /usr/bin/makeinfo creating ./config.status creating Makefile [root@reepycheep psgml-1.2.1]# make … [root@reepycheep psgml-1.2.1]# make install … This will compile and install &psgml; in /usr/share/emacs/site-lisp/. Read the README.psgml (in the psgml distribution) for more information, if you like.

The bare minimum that is needed to get &emacs; to use &psgml; is to add the following lines to your ~/.emacs. (setq load-path (cons "/usr/share/emacs/site-lisp/" load-path)) (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t ) (setq auto-mode-alist (append '( ("\\.sgml$" . sgml-mode) ) auto-mode-alist ) ) In this you should substitute the path to the one in which you have &psgml; installed. Otherwise what you are doing is telling &emacs; to automatically start &psgml; and telling it to use &psgml; when opening a file that ends with .sgml (it will also work with .sgml~). Without any information on the SGML catalog files &psgml; will not find the DTD. You need to set this information somehow (see for a discussion on how to do this). My own .emacs has many more settings that can be used to make &psgml; (among others) work better. You can find it at http://dawn.joensuu.fi/~ramin/config/emacs.html.

To begin using &emacs; and &psgml; all you need to do is open a file with the suffix .sgml. &Psgml; is also loaded when you save a file with the suffix .sgml. To show that the SGML-mode has been loaded, &emacs; changes its statusbar to show that you are editing a SGML-document and what the top-level element of the document is. &Psgml; itself, just like &emacs;, has multiple settings and keyboard commands that you can use. Customizing &psgml; as well as using many of its freatures are outside the scope of this document. It is therefore strongly recommended that you look at others &emacs; configurations (such as my own) and read the &psgml; manual (found in the distribution directory as psgml.info or psgml.ps). In the following paragraph I will describe how I use it. You might need to take a look at my configuration files to get everything to work in the same way though. I originally only used &psgml; to nicely colorize my editing buffer (with customized colorizations thanks to others). Later I learned to use it to indent everything in a nice way with elements considered as programming code blocks. This helped a lot in visualizing the structure of the whole document in even greater detail. Now, after spending some time reading the &psgml; manual, I've learned to use some of it's keyboard combinations to speed up the insertion of elements and attributes. Pressing Ctrl c Ctrl e will give you a mini-buffer in which you can type in the element you would like to insert at the given point. The mini-buffer supports tab completion, so you can press the tab-key to complete the element's name. It will also place the end-tag either on the same line (if the element does not require other elements) or on a new line. With my settings it will also insert all of the element's required attributes. Pressing Ctrl c + will let you add attributes and their values to the next element or current element if the pointer is in a start-tag at the time. The minibuffers offered for this naturally support tab completion as well. Note that when you use entities as shortcuts psgml might encouter some problems. After inserting some new elements these problems usually disappear.

Bill Tihen We present some options here and describe the installation and use, however, we do not currently recommend using them. They do not allow many of the tags we want to use as defined in _SEUL-edu Documentation Standards: A Writer's Guide_, and because they currently do not import SGML documents.

LyX 1.04 and beyond are SGML capable if the proper &SGMLtools; is installed. LyX will work with several other types of documents as well. LyX allows the user to view the document structure as one writes the document in a WYSIWYG format. This simplifies the creation of structured documents. It also creates tables, lists, grahpics and equations. However, I don't know how well it exports theses advanced features to SGML documents. Some drawbacks of using LyX. LyX does support all SGML tags. It is unaware of the tags (or at least I don't know how to include the following tags in a LyX document) such as application, file, etc. Which will ultimately help us create searchable content in our documents. So if you use this tool, please add the additional tags we expect using a text editor. (Unfortunately, once you do this you will not be able to use LyX to edit it again -- as it doesn't import SGML files yet anyway). LyX does not (yet anyway) import DocBook (SGML) files. Which means if you add some tags by hand — as suggested above — you will no longer be able to edit the document with LyX. LyX still uses sect1, sect2, sect3, etc tags. This means if you edit the file by hand you must be careful to renumber the section tags properly. I find it easier to just use the section tag. In all fairness I don't use LyX regullarly and it is quite possible there are solutions for these difficulties. If you know the solutions please share the solution with use so that we can update this document. Therefore, LyX is only useful in creating simple DocBook articles. Once they are exported and have the additional tags for files, keyboard strokes, etc, LyX will not be able to maintain the document.

You can download LyX from RPMS are avaliable at: To use DocBook you will also need the following version of sgmltools — I am sure at some point other versions will be okay, but for now please use this version: This version of &SGMLtools; seems to have a missing version file in the dssl. This is not a serious problem, but it generates an unnessary error. I suggest going to Norman Walsh's website and getting the most recent dssl -- which will also fix this little error. On my system this stylesheet is installed at /usr/share/sgml/stylesheets. Copy the file you downloaded to the proper location and unzip it. If you want to keep a copy of your old set just rename the original docbook folder before unzipping the file. Now your error will go away and you will have the most recent dssl. LyX requires xforms which can be found at xforms. I don't know of an rpm version of the xforms library, so I have only been able to install LyX, by first installing both the xforms and LyX sources and then compiling them. After the initial installation LyX installation from sources you should be able to use LyX rpms.

Install both LyX and the appropriate version of &SGMLtools;. Now you must reconfigure LyX by going to the menu bar and selecting ALTo SPACE r Options Reconfigure . You should then get the following dialog box telling you to restart LyX. It is important to do this right away!

Using LyX is quite easy, however there are a few steps you must follow when creating a new DocBook article. Open a new document and do the following: ALT-n File New Now check to see if the SGMLtools layout was found. ALT-f d Layout Document... Now the Document Layout dialog box should open up. Class Towards the bottom of the list you should see: SGML (DocBook article). Select this item. Then click on either Apply or OK. Now a confirmation dialog box should appear. Click on Yes. As you type the document select the structures you want using the menu-bar and the menu-items. It should be clear to most people how to do this once the program is running. Now the SGML document needs to be exported by going to the menu bar and choosing: File Export DocBook

This is an open-source document processor project that will work with any DTD (this obviously includes Docbook). The project is just starting, but shows a lot of promise. Visit the project's web site and download a copy of Conglomerate.

&SGMLtools; is currently the easiest way to process and publish SGML documents based on the DocBook DTD. Therefore, this collection of tools will be described in detail. The component that make up &SGMLtools;: jade and the DocBook DTD will not be covered in any detail.

Ramin Miraftabi &SGMLtools; is a collection of tools and utilities to help users process documents based on the DocBook DTD. It was formerly known as Linuxdoc-SGML, but the name was changed quite some time ago to clarify the fact that the tools were not related only to Linux. Versions 1.0.x of &SGMLtools; used the Linuxdoc DTD as their document type. Linuxdoc has some serious limitations (such as not supporting images) that the Linux Documentation Project and &SGMLtools; developers decided to move on to DocBook. The development versions of &SGMLtools; (numbered in the kernel style 1.1.x) already used DocBook. The first stable release with DocBook was 2.0 in late 1998. During the Spring of 1999 the project was suspended, with the last release being 2.0.2. The CVS version of &SGMLtools; has however been slightly updated. Presently &SGMLtools; is a wrapper that combines Jade, Jadetex, Hyperref, the DocBook DTD, and the Stylesheets. It simply presents a unified front-end to the whole process of processing the SGML-file into different formats.

&SGMLtools; is available from . Installing &SGMLtools; requires Python and converting SGML files to tex, dvi, and PostScript requires tetex. Using version 0.9x of tetex is recommended since you can more easily update some essential configurations. The last release of &SGMLtools; does not include DocBook 3.1 and has some other problems as well, therefore I suggest you get the latest version from CVS (instruction on how to do this below). There are also some RPM packages that have been made of &SGMLtools; , you'll have to look around for them. To get the latest &SGMLtools; version out of the CVS repository where it's held, you naturally need to have CVS installed. The password to the CVS repository is cvs. Again, the output from the commands has been supressed. After running these commands you will have a directory called sgmltools in the present working directory and all the files needed to compile and run &SGMLtools; in this directory. export CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs cvs login cvs -z6 get sgmltools

&SGMLtools; should configure itself if everything in the compile stage goes as it should. However, at least I have noticed some problems with the configuration of &SGMLtools; 2.0.2. The main problems with this version are the fact that it does not support DocBook 3.1 out of the box and it has problems in creating the settings for the SGML_CATALOG_FILES environment variable. &SGMLtools; works just fine without these anyway, you just might get some strange error messages. The following paragraphs describe the compilation and basic configuration of &SGMLtools; source versions. I will try to point out the differences between 2.0.2 and the CVS version where possible. If you are using anything before RedHat 6.0 you need to install the tetex version 0.9x packages from RedHat 6.0. The packages with 6.1 might also work. If you are using RedHat 6.0 you need to update the rpm package and then reinstall the tetex packages. Otherwise some important files will be missing (bugs in the first rpm). In the following by the base directory I will mean the directory root directory of the &SGMLtools distribution. All relative paths are relative to this directory. I also recommend that you you do all of the following steps as root even though I point out the steps in which you must be root. First run ./configure to create the initial configuration. If you have the CVS version of &SGMLtools;, change to the directory packages/cvs/sgmltools and add open configure.in in your favourite editor. On line 49 add test "$prefix" = "NONE" && prefix=/usr/local After this run autoconf configure.in > configure. For both versions the next is required for a succesful compilation. At some point of time the default French package was removed from the tetex distribution because of copyright problems. The lack of this package causes problem in compiling Jadetex. To fix this you have to open packages/cvs/jadetex/jadetex.dtx and go to line 117. On this line you will see the text \RequirePackage[german,french,english]{babel}[1997/01/23] Now you have to change the french to frenchb if you want support for French. Depending on your tetex distribution you can add other languages as well (I've removed support for French completely and added Finnish (finnish) instead). To be precise, the support for other languages depends on Babel. My thanks go to Sebastian Rahtz (the author of Jadetex) for this fix. After all of these steps you can finally run make && make install to compile and install &SGMLtools;. Remember, that you have to be root to run make install. This will install the binaries in /usr/local/bin and the other data files in /usr/local/share/sgml. Some environment information will be installed into /etc/sgml. You can control these locations by the configure parameters --prefix and --with-etcsgml. To fix some problems that occur when processing into PostScript, dvi, or jadetex you will need to fix the kpathsea configuration. To do this you again have to be root. Change into the directory /usr/share/texmf/web2c. Save the following text into a file (say texmf.cnf.patch). --- texmf.cnf.orig Sun Dec 5 19:43:17 1999 +++ texmf.cnf Sun Dec 5 19:44:49 1999 @@ -396,6 +396,7 @@ % Extra space for the hash table of control sequences (which allows 10K % names as distributed). +hash_extra.jadetex = 15000 hash_extra.context = 15000 hash_extra.cont-en = 15000 hash_extra.cont-nl = 15000 @@ -404,6 +405,7 @@ % Max number of characters in all strings, including all error messages, % help texts, font names, control sequences. These values apply to TeX and MP. +pool_size.jadetex = 200000 pool_size.context = 500000 pool_size.cont-en = 500000 pool_size.cont-nl = 500000 @@ -417,6 +419,7 @@ string_vacancies.cont-de = 45000 string_vacancies = 25000 % Maximum number of strings. +max_strings.jadetex = 50000 max_strings.context = 55000 max_strings.cont-en = 55000 max_strings.cont-nl = 55000 @@ -461,6 +464,7 @@ param_size.cont-nl = 1500 param_size.cont-de = 1500 param_size = 500 % simultaneous macro parameters +save_size.jadetex = 15000 save_size.context = 5000 save_size.cont-en = 5000 save_size.cont-nl = 5000 Now we only have one more final step to do in order to get &SGMLtools; properly working for all users. As root, open /etc/profile (for sh-users) and add the following lines to the end of the file: # Source /etc/sgml/sgml.env if [ -f /etc/sgml/sgml.env ]; then . /etc/sgml/sgml.env fi With these lines you tell the enviroment to get the settings out of the file /etc/sgml/sgml.env if it exists and add them to the environment. The settings in csh can be found in /etc/sgml/sgml.cenv. As an additional step, I recommend that you get the latest version of the DocBook Stylesheets from Norman Walsh's site (). The latest version at the time of this writing is 1.48 and they are regularly updated. After you have downloaded the stylesheet package, as root change to the directory /usr/local/share/sgml/stylesheets and unzip the stylesheet distribution (unzip path/to/dbxxx.zip). Overwrite all of the files. The benefits in keeping up to date with the stylesheets include support for additional features and languages, and fixes for bugs in the stylesheets themselves (and therefore in the presentation of the document). For example, the latest version included support for PNG graphics in HTML and fixed some annoying problems with extra space between paragraphs and lists.

&SGMLtools; is used to verify the validity of the SGML documents and publish SGML documents in various formats. Using &SGMLtools; you can easily create various output file. To create a postscript file (PS) simply type the command: sgmltools -b ps filename.sgml To create a web browsable document (HTML) from the file, you would use: sgmltools -b html filename.sgml To create a rich-text-formatted document (RTF) file use: sgmltools -b rtf filename.sgml To create a text (TXT) file use: sgmltools -b rtf filename.sgml To get additional help type: sgmltools --help Unfortunately, &SGMLtools; is not (yet anyway) able to create portable-document-format (PDF) files.

document the usage of own stylesheets with SGMLtools and Jade. Show an example of such stylesheets and tell where to get more info on them. (ramin).

This is a SGML verifier and also generates various document formats from SGML files. This package is used by other software. You will need it. However, it is clumsy to use you are also wise to also install &SGMLtools; (see ) to simplify you life.

Jade can be found at:

Nothing to configure?

To create an RTF file type the following command: jade -t rtf -d /path-to-stylesheets/docbook/print/docbook.dssl file.sgml To create an HTML file type the following command: jade -t sgml -d /path-to-stylesheets/docbook/html/docbook.dssl file.sgml

These are files that define something. (I don't really know what they do, but the docbook.dtd files are needed. Maybe they come with other packages too. I think so. Is this really a package we need to describe? Ramin?)

It can be found here.

Is there anything to configure?

Programs use it you don't directly.

DebraCameron BillRosenblatt EricRaymond 199619921991 O'Reilly 1-56592-152-6 O'Reilly Second Edition NormanWalsh LeonardMuellner 1999 O'Reilly FrankWillison 1-56592-580-7 O'Reilly The Definitive Guide