From 811ff2d196c13670c20c3a639367e745dc5b0c0e Mon Sep 17 00:00:00 2001 From: emmajane <> Date: Wed, 13 Aug 2003 06:46:59 +0000 Subject: [PATCH] Moved the Tools section into the appendix the writing sections. Documents are NOT finished. --- .../LDP-Author-Guide/LDP-Author-Guide.xml | 744 +----------------- .../LDP-Author-Guide/authoring-writing.xml | 20 +- LDP/guide/docbook/LDP-Author-Guide/tools.xml | 737 +++++++++++++++++ 3 files changed, 760 insertions(+), 741 deletions(-) create mode 100644 LDP/guide/docbook/LDP-Author-Guide/tools.xml diff --git a/LDP/guide/docbook/LDP-Author-Guide/LDP-Author-Guide.xml b/LDP/guide/docbook/LDP-Author-Guide/LDP-Author-Guide.xml index 0ba8f386..4f86b358 100644 --- a/LDP/guide/docbook/LDP-Author-Guide/LDP-Author-Guide.xml +++ b/LDP/guide/docbook/LDP-Author-Guide/LDP-Author-Guide.xml @@ -23,6 +23,8 @@ + + @@ -271,746 +273,10 @@ This chapter includes: --> &authoring-writing; + + + &tools; - - The tools - In this section, we will cover some of the tools that you will - need or want to use to create your own LDP documentation. I'll - describe them here, and better define them later on, along with - how to install them. If you use some other tool to assist in - writing LDP, please let me know and I'll add a blurb here for - it. - -
- DSSSL - The Normal Walsh version is required, the LDP is - optional but recommended. - -
- Norman Walsh DSSSL - http://nwalsh.com/docbook/dsssl/ - The DSSSL - Document Style Semantics and Specification Language - tells jade (see ) how to render a DocBook document - into print or online - form. The DSSSL is what converts a title tag into an - <H1> tag in HTML, or to 14 point bold Times Roman for RTF, - for example. Documentation for DSSSL is located at the same - site. Note that modifying the DSSSL doesn't modify DocBook - itself. It merely changes the way the rendered text looks. The - LDP uses a modified DSSSL (see below). -
- - -
- LDP DSSSL - http://www.tldp.org/authors/tools/ldp.dsl - The LDP DSSSL requires the Norman Walsh version (see - above) but is a slightly modified DSSSL to provide things like - a table of contents. -
-
- -
- DocBook DTD (version 4.1 or 3.1) - Required - http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip or http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip - The XML DTD is available from http://www.oasis-open.org/xml/4.1.2/. - - - The DocBook DTD - DocBook DTD defines the tags and structure of a - DocBook document. Modifying the DTD, such as adding a new - tag, means that this DTD is no longer DocBook. - -
- -
- Jade - - jade - Jade and OpenJade are two of the programs that do most of - the rendering and validation of code based on the DTD and - DSSSL. One of the following is required and should be installed - after the DTD and DSSSL have been installed. - - -
- Jade - ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz - Jade is the front-end processor for SGML and XML. It uses the - DSSSL and DocBook DTD to perform the verification and - rendering from SGML and XML into the target format. -
- Using Jade - This is the quick and dirty way that should work for all - distributions, no matter what one you are using. - - - - Create a base directory to store everything such as - /usr/local/sgml/. We'll call - this $_toolroot from here on. - - - Install Jade, DocBook DTD, and DSSSL such that the - base of each is under $_toolroot, creating: - - - - $_toolroot/jade-1.2.1 - - - - $_toolroot/dtd - - - - $_toolroot/dsssl - - - - - - You'll need to set the - SGML_CATALOG_FILES environment variable to - the catalogs that you have under$_toolroot. You can do this - with the command: - -bash$ export SGML_CATALOG_FILES=$_toolroot/dtd/docbook.cat:\ -$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog - - - - - Now you can start using Jade. To create individual - HTML files: - -$_toolroot/jade-1.2.1/jade/jade -t sgml -i html \ --d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml - - - - To create one large HTML file, add -V - nochunks to the jade command. - - -
-
- Jade in XML mode - - Once configured for XML, jade and openjade will work - the same way as for SGML DocBook. - - - After extracting the XML DTD, you will want to make - a symlink from the docbook.cat file to "catalog", the - default filename for jade/openjade catalogs. Replace - $_xml_root with the location of your XML DTD. - - - -bash$ cd $_xml_root -bash$ ln -s docbook.cat catalog -bash$ export SGML_CATALOG_FILES=$_xml_root/catalog:$_toolroot/dsssl/catalog:\ -$_toolroot/dtd/docbook/catalog -bash$ jade -t sgml -i html -d style $_jade_path/pubtext/xml.dcl foo.xml - - - - - You'll need the catalogs for XML, the DSSSL, and DocBook, - respectively. $_toolroot was defined above. - - - - - Replace style with the DSSSL - (ldp.dsl) you wish to use. The pointer to xml.dcl is - required for jade to work, and it has to be listed - immediately before the pointer to your XML document. - This file may be in a different directory. - Check your distribution. - - - You may get the following warnings when processing XML - documents. They don't impact the output, and the cause - is being looked into. - - -<xml_dtd_pth>/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name -<xml_dtd_pth>/ent/iso-lat2.ent:120:17:E: "X0178" is not a function name - - - - - - If you want to convert your existing SGML DocBook into - XML docbook, use this as your declaration (the lines at the - very start of your document). - - -<?xml version='1.0' encoding='ISO-8859-1'?> -<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'> - - - If you have followed LDP guidelines, there should be no - other changes required to your document. Note that there - are changes between DocBook 3.x and 4.x that you may - also have to take into account. You can get more information - at this in . - -
-
- -
- OpenJade - http://openjade.sourceforge.net/ - An extension of Jade written by the DSSSL - community. Some applications require jade, but are being - updated to support either software package. -
-
- -
- Jade wrappers - These tools are optional and may be installed after Jade, - the DSSSL, and DTD have been installed. - -
- sgmltools-lite - http://sgmltools-lite.sourceforge.net/ - This is the successor to the sgmltools project, which - has been officially disbanded for over a year. Since then, - Cees de Groot has created a slightly different project, which - acts as a wrapper to the jade SGML processor. It hides much of - the ugliness of the syntax. This author was able to install the - old sgmltools package followed by the sgmltools-lite and could - format this document quite easily. There's even a man page for - sgmltools showing syntax. -
- -
- Cygnus DocBook Tools - May be Red Hat specific - http://www.redhat.com/ - - Cygnus Tools - Red Hat distributes three packages, starting with the - 6.2 release, that include DocBook support and some tools. The - tools are easily installed, allowing you to focus more on - writing than wrestling with the tools. TeTex, Jade, and - JadeTeX must be installed first. All three of these packages - are available on the installation CD. - -
- Using the Cygnus Tools - These tools are provided with Red Hat 6.2. Make sure - the following packages are installed: - - sgml-common-0.1-8.noarch - docbook-3.1-4.noarch - stylesheets-1.54.13rh-1.noarch - - Red Hat has the latest version on their web site: - http://www.redhat.com/support/errata/RHBA-2000022-01.html. - Download/get/sneaker-net the RPMs to your machine and - install in the usual manner (become root, then rpm -Uvh filename). Once the RPMs - are installed, you can use the following commands to render - DocBook: - -bash$ db2html - - Renders DocBook into HTML. A subdirectory with the - filename (minus the .sgml extension) is created and the HTML - files are placed there. - -bash$ db2pdf - - Renders DocBook into a PDF file. Note that there is currently a - problem with db2pdf, and pd2ps caused by JadeTeX. This has been - - registered as a bug with RedHat. -
-
-
- -
- Editing tools - The following tools may be used to create, edit, or - validate your HOWTO. - -
- Emacs (PSGML) - Optional - http://www.lysator.liu.se/~lenst/about_psgml/ - - Emacs - - - Editors - emacs - - Emacs has an SGML writing mode called psgml that is a - major mode designed for editing SGML and XML documents. It - provides syntax highlighting or pretty - printing features that make SGML tags stand out, a way - to insert tags other than typing them by hand, and the ability - to validate your document while writing. - For users of Emacs, it's a great way to go, and many - believe it to allow more versatility than any other SGML - documentation tool. It works with DocBook, LinuxDoc and other - DTDs equally well. -
- Writing SGML using PSGML - -
Introduction - If you have installed a recent distribution, you may - already have PSGML installed for use with Emacs. To check, - start Emacs and look for the PSGML documentation (Chimpsgml). - From here on, we assume you have PSGML installed for - use with a recent version of GNU Emacs. If that all went by - too fast for you, see the free chapter from Bob Ducharme's - SGML CD book: http://www.snee.com/bob/sgmlfree/psgmqref.html. -
- -
- Updating your .emacs to use PSGML - If you want GNU Emacs to enter PSGML mode when you open - a .sgml file and be ready for SGML - editing, make sure PSGML can find the DocBook DTD. If your - distribution already had PSGML set up for use with GNU Emacs, - you probably do not have to do anything to get this to - work. Otherwise, you may need to set an environment variable - that tells PSGML where to look for the SGML catalog (the list - of DTDs). - For example: - -bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog - - Then add something like the following to your .emacs - file: - -;; ******************************************************************* -;; set up psgml mode... -;; use psgml-mode instead of emacs native sgml-mode -;; - -(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t ) -(setq auto-mode-alist - (append - (list - '("\\.sgm$" . sgml-mode) - '("\\.sgml$" . sgml-mode) - ) - auto-mode-alist)) - -;; set some psgml variables - -(setq sgml-auto-activate-dtd t) -(setq sgml-omittag-transparent t) -(setq sgml-balanced-tag-edit t) -(setq sgml-auto-insert-required-elements t) -(setq sgml-live-element-indicator t) -(setq sgml-indent-step nil) - -;; create faces to assign to markup categories - -(make-face 'sgml-comment-face) -(make-face 'sgml-start-tag-face) -(make-face 'sgml-end-tag-face) -(make-face 'sgml-entity-face) -(make-face 'sgml-doctype-face) ; DOCTYPE data -(make-face 'sgml-ignored-face) ; data ignored by PSGML -(make-face 'sgml-ms-start-face) ; marked sections start -(make-face 'sgml-ms-end-face) ; end of marked section -(make-face 'sgml-pi-face) ; processing instructions -(make-face 'sgml-sgml-face) ; the SGML declaration -(make-face 'sgml-shortref-face) ; short references - -;; view a list of available colors with the emacs-lisp command: -;; -;; list-colors-display -;; -;; please assign your own groovy colors, because these are pretty bad -(set-face-foreground 'sgml-comment-face "coral") -;(set-face-background 'sgml-comment-face "cornflowerblue") -(set-face-foreground 'sgml-start-tag-face "slateblue") -;(set-face-background 'sgml-start-tag-face "cornflowerblue") -(set-face-foreground 'sgml-end-tag-face "slateblue") -;(set-face-background 'sgml-end-tag-face "cornflowerblue") -(set-face-foreground 'sgml-entity-face "lavender") -;(set-face-background 'sgml-entity-face "cornflowerblue") -(set-face-foreground 'sgml-doctype-face "lavender") -;(set-face-background 'sgml-doctype-face "cornflowerblue") -(set-face-foreground 'sgml-ignored-face "cornflowerblue") -;(set-face-background 'sgml-ignored-face "cornflowerblue") -(set-face-foreground 'sgml-ms-start-face "coral") -;(set-face-background 'sgml-ms-start-face "cornflowerblue") -(set-face-foreground 'sgml-ms-end-face "coral") -;(set-face-background 'sgml-ms-end-face "cornflowerblue") -(set-face-foreground 'sgml-pi-face "coral") -;(set-face-background 'sgml-pi-face "cornflowerblue") -(set-face-foreground 'sgml-sgml-face "coral") -;(set-face-background 'sgml-sgml-face "cornflowerblue") -(set-face-foreground 'sgml-shortref-face "coral") -;(set-face-background 'sgml-shortref-face "cornflowerblue") - -;; assign faces to markup categories - -(setq sgml-markup-faces ' - ( - (comment . sgml-comment-face) - (start-tag . sgml-start-tag-face) - (end-tag . sgml-end-tag-face) - (entity . sgml-entity-face) - (doctype . sgml-doctype-face) - (ignored . sgml-ignored-face) - (ms-start . sgml-ms-start-face) - (ms-end . sgml-ms-end-face) - (pi . sgml-pi-face) - (sgml . sgml-sgml-face) - (shortref . sgml-shortref-face) - )) - -;; tell PSGML to pay attention to face settings -(setq sgml-set-face t) -;; ...done setting up psgml-mode. -;; ******************************************************************* - - Then restart Emacs -
- -
- SGML Smoke Test - Try the following smoke test. Start a new file, - /tmp/test.sgml for - example, and enter the following: - - -!DOCTYPE test [ -<!ELEMENT test - - (#PCDATA)> -] - - Enter C cC - p. If Emacs - manages to parse your DTD, you will see Parsing - prolog...done in the minibuffer. Try - C-c C-e RETURN to insert a - test element. If - things are working correctly, you should see the following - in Emacs: - -!DOCTYPE test [ -<!ELEMENT test - - (#PCDATA)> -] -testtest - -
- -
- Writing a New HOWTO in DocBook - Start a new file for your HOWTO and enter the - following: - -!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN" - - Enter CcC - p and hold - your breath. If everything goes as planned, you will see - Emacs chewing for a few seconds and then Parsing - prolog...done in the minibuffer. - At this point, enter C cCeRETURN to insert an - article element and - proceed to write your HOWTO. -
- -
- Quick Reference for Emacs with PSGML - See Nik Clayton's primer for FreeBSD documentation: - http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html - -
-
-
- -
- VIM - http://www.vim.org - No mention of Emacs is complete without talking about - vi. The vim - - Editors - vim - - VIM (Vi IMproved) editor has the functionality of - regular vi, but also has an SGML mode that will - color-coordinate your screen to show where tags are. -
- Getting Started - The vim program comes in many parts. There is - the plain vim program, which is compatibile with the - vi program and its commands. Red Hat users will want the vim-common - and vim-minimal packages. Next is the enhanced - vim, which includes the highlighting and other - features of vim over regular vi. Red Hat - users will want vim-enhanced. Last, but certainly not least, is the - X interface, which gives a graphical interface, menus, and mouse - control. To separate this from vim or vi, the command for graphical - access is called gvim. -
-
- Loading or starting new documents - In both vim and gvim modes, - .sgml files will be automatically recognized and - enter into sgml mode. A series of known DocBook tags - have been entered into vim and will he highlighted - in brown if a tag is known. If it isn't, it will appear in light blue. - attributes to known tags are in light blue, and values for the - attributes are in pink. From here on, you can use regular vi - commands to navigate and edit. - - While VIM has an XML mode, this mode will not highlight known - and unknown DocBook tags. You can still force VIM into - SGML mode if you like using the :set ft=sgml - command. Note that this will not have any affect on the file - or its contents, only the highlighting within VIM. - -
-
- -
- WordPerfect 9 (Corel Office 2000) - http://www.corel.com/ - WordPerfect 9 for the MS Windows platform has support - for SGML and DocBook 3.0. WordPerfect 9 for Linux has no SGML - capabilities. - This is the least expensive of the commercial - applications that support SGML. -
- -
- epcEdit - http://www.tksgml.de/ - The epcEdit - - Editors - epcEdit - - epcEdit program allows you to visually edit SGML - files. It has the advantages of not needing to know Emacs or - vi before starting, and is cross-platform, working in both - Windows and Linux. This is a commercial application, and - pricing can be found at - http://www.tksgml.de/pricing.html - - Along with visual editing, epcEdit will also validate - documents on loading, and on demand by using the DocumentValidate - command. - -
- epcEdit screen shot - - - - - - - - - The screen shot of the epcEdit program shows a - tree on the left side that has the SGML document in a - hierarchy, while the right side shows the document. - Tags are shown with a grey background. - - -
-
- -
- nedit - http://nedit.org - To be fair, - nedit - - Editors - nedit - - nedit is more - for programmers, so it might seem a bit of overkill for new - users and especially non-programmers. All that aside, it's - extremely powerful, allowing for color coding of tags. Unlike - epcEdit, nedit doesn't allow you to automatically insert tags - or automatically validate your code. However, it does allow - for shell commands to be run against the contents of the - window (as opposed to saving the file, then checking). In a - few minutes, I was able to set up nsgmls to - validate the SGML and aspell to do my spell - checking. - -
- nedit screen shot - - - - - - - - - The nedit program can provide line numbers - across the left side of the screen, handy for when - nsgmls complains of errors - - -
- -
- Using nedit - For writing new documentation, it is recommended that - you download and use the LDP DocBook template. Once you have - the file, you can start up nedit and begin editing. If the - file is saved with a .sgml extension, nedit will load the file - up with SGML/HTML tags enabled. You can turn this on - explicitly using the - PreferencesLanguage - ModeSGML - HTML command. -
- -
- Tips and tricks with nedit - Since you can feed the contents of your window to - outside programs, you can easily extend nedit to perform - repetitive functions. The example you'll see here is to - validate the SGML code using nsgmls. - Select - PreferencesDefault - SettingsCustomize - MenusShell - Menu.... This will bring up the - Shell Command dialog box, with all the shell commands nedit - has listed under the - Shell menu. Under - Menu Entry, enter "SGML Validate". This will be the entry - you'll see on the screen. Under Accelerator, press - AltS. - Once this menu item is set up, you can press - AltS - to have the SGML Validate automatically run. Under Command - Input, select window, and under Command Output, select - dialog. Under Command to Execute, enter nsgmls -sv. Note - that nsgmls has to be in your - PATH for this to work properly. - -
- Adding shell commands to nedit - - - - - - - - -
- - Click OK and you'll now be back - at the main nedit screen. Load up an SGML file, and select - ShellSGML - Validate or press - AltS. - The nedit program will fire up and check - the contents of the window. The reason for using -sv is that - the -v tells nsgmls to output the version - of the program, so you'll always get output and know that - nsgmls has run. If all you get is a - version number, then there are no errors with the document. - If there are errors, then they'll be listed in the separate - window for you to see. If you have line numbers turned on - (using - PreferencesShow - Line Numbers) then finding the - errors is much simpler, as nsgmls will list - errors by their line number. - -
- nsgmls output on success - - - - - - - - - If nsgmls reports success, it merely reports the version of nsgmls - - -
-
-
- -
- Morphon XML editor - http://www.morphon.com/xmleditor/index.shtml - This is a commerical application that has a free 30 day - license available for download. It is written in Java, allowing - it to run on any platform that has a JVM (that is, works in both - Windows and Linux). The cost is $150USD for a single user - license, and $75USD for a student license. - On the plus sides of XMLEditor is the left side of the - screen shows the heirarchy of the document (starting with Book - and so on). Selecting an item in the list brings you to that - part of the document so you can edit it. The right part of the - screen shows the text without any markup or tags being shown. - If you have external files as ELEMENTS (as the LDP Author Guide - does), XMLEditor will follow the links and load the files, so - you always work on the entire work. On the minus side of this, - you will get errors if a file (like index.xml) is - missing. -
-
- -&cvs; -
Other/Reference The items in this section are reference books or other diff --git a/LDP/guide/docbook/LDP-Author-Guide/authoring-writing.xml b/LDP/guide/docbook/LDP-Author-Guide/authoring-writing.xml index 910ea7cf..16df3807 100644 --- a/LDP/guide/docbook/LDP-Author-Guide/authoring-writing.xml +++ b/LDP/guide/docbook/LDP-Author-Guide/authoring-writing.xml @@ -233,8 +233,24 @@ &cvs;
- - + Spell Check +
+ Aspell + Optional - http://aspell.sourceforge.net/ + This spell checking application can work around XML tags. By + distinguishing between content and markup aspell is able to check + your content and ignore the bits it shouldn't be looking at. If you + are getting spelling errors in your markup tags you may be using an + old version and should upgrade. + +
+
+ ispell + Optional - http://www.cs.hmc.edu/~geoff/ispell.html + The ispell program is distributed with RedHat (and possibly other + distros) and also ignores markup tags. +
diff --git a/LDP/guide/docbook/LDP-Author-Guide/tools.xml b/LDP/guide/docbook/LDP-Author-Guide/tools.xml new file mode 100644 index 00000000..563b2e66 --- /dev/null +++ b/LDP/guide/docbook/LDP-Author-Guide/tools.xml @@ -0,0 +1,737 @@ + + The tools + In this section, we will cover some of the tools that you will + need or want to use to create your own LDP documentation. I'll + describe them here, and better define them later on, along with + how to install them. If you use some other tool to assist in + writing LDP, please let me know and I'll add a blurb here for + it. + +
+ DSSSL + The Normal Walsh version is required, the LDP is + optional but recommended. + +
+ Norman Walsh DSSSL + http://nwalsh.com/docbook/dsssl/ + The DSSSL + Document Style Semantics and Specification Language + tells jade (see ) how to render a DocBook document + into print or online + form. The DSSSL is what converts a title tag into an + <H1> tag in HTML, or to 14 point bold Times Roman for RTF, + for example. Documentation for DSSSL is located at the same + site. Note that modifying the DSSSL doesn't modify DocBook + itself. It merely changes the way the rendered text looks. The + LDP uses a modified DSSSL (see below). +
+ + +
+ LDP DSSSL + http://www.tldp.org/authors/tools/ldp.dsl + The LDP DSSSL requires the Norman Walsh version (see + above) but is a slightly modified DSSSL to provide things like + a table of contents. +
+
+ +
+ DocBook DTD (version 4.1 or 3.1) + Required - http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip or http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip + The XML DTD is available from http://www.oasis-open.org/xml/4.1.2/. + + + The DocBook DTD + DocBook DTD defines the tags and structure of a + DocBook document. Modifying the DTD, such as adding a new + tag, means that this DTD is no longer DocBook. + +
+ +
+ Jade + + jade + Jade and OpenJade are two of the programs that do most of + the rendering and validation of code based on the DTD and + DSSSL. One of the following is required and should be installed + after the DTD and DSSSL have been installed. + + +
+ Jade + ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz + Jade is the front-end processor for SGML and XML. It uses the + DSSSL and DocBook DTD to perform the verification and + rendering from SGML and XML into the target format. +
+ Using Jade + This is the quick and dirty way that should work for all + distributions, no matter what one you are using. + + + + Create a base directory to store everything such as + /usr/local/sgml/. We'll call + this $_toolroot from here on. + + + Install Jade, DocBook DTD, and DSSSL such that the + base of each is under $_toolroot, creating: + + + + $_toolroot/jade-1.2.1 + + + + $_toolroot/dtd + + + + $_toolroot/dsssl + + + + + + You'll need to set the + SGML_CATALOG_FILES environment variable to + the catalogs that you have under$_toolroot. You can do this + with the command: + +bash$ export SGML_CATALOG_FILES=$_toolroot/dtd/docbook.cat:\ +$_toolroot/dsssl/docbook/catalog:$_toolroot/jade-1.2.1/dsssl/catalog + + + + + Now you can start using Jade. To create individual + HTML files: + +$_toolroot/jade-1.2.1/jade/jade -t sgml -i html \ +-d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml + + + + To create one large HTML file, add -V + nochunks to the jade command. + + +
+
+ Jade in XML mode + + Once configured for XML, jade and openjade will work + the same way as for SGML DocBook. + + + After extracting the XML DTD, you will want to make + a symlink from the docbook.cat file to "catalog", the + default filename for jade/openjade catalogs. Replace + $_xml_root with the location of your XML DTD. + + + +bash$ cd $_xml_root +bash$ ln -s docbook.cat catalog +bash$ export SGML_CATALOG_FILES=$_xml_root/catalog:$_toolroot/dsssl/catalog:\ +$_toolroot/dtd/docbook/catalog +bash$ jade -t sgml -i html -d style $_jade_path/pubtext/xml.dcl foo.xml + + + + + You'll need the catalogs for XML, the DSSSL, and DocBook, + respectively. $_toolroot was defined above. + + + + + Replace style with the DSSSL + (ldp.dsl) you wish to use. The pointer to xml.dcl is + required for jade to work, and it has to be listed + immediately before the pointer to your XML document. + This file may be in a different directory. + Check your distribution. + + + You may get the following warnings when processing XML + documents. They don't impact the output, and the cause + is being looked into. + + +<xml_dtd_pth>/ent/iso-lat2.ent:119:18:E: "X0176" is not a function name +<xml_dtd_pth>/ent/iso-lat2.ent:120:17:E: "X0178" is not a function name + + + + + + If you want to convert your existing SGML DocBook into + XML docbook, use this as your declaration (the lines at the + very start of your document). + + +<?xml version='1.0' encoding='ISO-8859-1'?> +<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.1.2//EN'> + + + If you have followed LDP guidelines, there should be no + other changes required to your document. Note that there + are changes between DocBook 3.x and 4.x that you may + also have to take into account. You can get more information + at this in . + +
+
+ +
+ OpenJade + http://openjade.sourceforge.net/ + An extension of Jade written by the DSSSL + community. Some applications require jade, but are being + updated to support either software package. +
+
+ +
+ Jade wrappers + These tools are optional and may be installed after Jade, + the DSSSL, and DTD have been installed. + +
+ sgmltools-lite + http://sgmltools-lite.sourceforge.net/ + This is the successor to the sgmltools project, which + has been officially disbanded for over a year. Since then, + Cees de Groot has created a slightly different project, which + acts as a wrapper to the jade SGML processor. It hides much of + the ugliness of the syntax. This author was able to install the + old sgmltools package followed by the sgmltools-lite and could + format this document quite easily. There's even a man page for + sgmltools showing syntax. +
+ +
+ Cygnus DocBook Tools + May be Red Hat specific - http://www.redhat.com/ + + Cygnus Tools + Red Hat distributes three packages, starting with the + 6.2 release, that include DocBook support and some tools. The + tools are easily installed, allowing you to focus more on + writing than wrestling with the tools. TeTex, Jade, and + JadeTeX must be installed first. All three of these packages + are available on the installation CD. + +
+ Using the Cygnus Tools + These tools are provided with Red Hat 6.2. Make sure + the following packages are installed: + + sgml-common-0.1-8.noarch + docbook-3.1-4.noarch + stylesheets-1.54.13rh-1.noarch + + Red Hat has the latest version on their web site: + http://www.redhat.com/support/errata/RHBA-2000022-01.html. + Download/get/sneaker-net the RPMs to your machine and + install in the usual manner (become root, then rpm -Uvh filename). Once the RPMs + are installed, you can use the following commands to render + DocBook: + +bash$ db2html + + Renders DocBook into HTML. A subdirectory with the + filename (minus the .sgml extension) is created and the HTML + files are placed there. + +bash$ db2pdf + + Renders DocBook into a PDF file. Note that there is currently a + problem with db2pdf, and pd2ps caused by JadeTeX. This has been + + registered as a bug with RedHat. +
+
+
+ +
+ Editing tools + The following tools may be used to create, edit, or + validate your HOWTO. + +
+ Emacs (PSGML) + Optional - http://www.lysator.liu.se/~lenst/about_psgml/ + + Emacs + + + Editors + emacs + + Emacs has an SGML writing mode called psgml that is a + major mode designed for editing SGML and XML documents. It + provides syntax highlighting or pretty + printing features that make SGML tags stand out, a way + to insert tags other than typing them by hand, and the ability + to validate your document while writing. + For users of Emacs, it's a great way to go, and many + believe it to allow more versatility than any other SGML + documentation tool. It works with DocBook, LinuxDoc and other + DTDs equally well. +
+ Writing SGML using PSGML + +
Introduction + If you have installed a recent distribution, you may + already have PSGML installed for use with Emacs. To check, + start Emacs and look for the PSGML documentation (Chimpsgml). + From here on, we assume you have PSGML installed for + use with a recent version of GNU Emacs. If that all went by + too fast for you, see the free chapter from Bob Ducharme's + SGML CD book: http://www.snee.com/bob/sgmlfree/psgmqref.html. +
+ +
+ Updating your .emacs to use PSGML + If you want GNU Emacs to enter PSGML mode when you open + a .sgml file and be ready for SGML + editing, make sure PSGML can find the DocBook DTD. If your + distribution already had PSGML set up for use with GNU Emacs, + you probably do not have to do anything to get this to + work. Otherwise, you may need to set an environment variable + that tells PSGML where to look for the SGML catalog (the list + of DTDs). + For example: + +bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog + + Then add something like the following to your .emacs + file: + +;; ******************************************************************* +;; set up psgml mode... +;; use psgml-mode instead of emacs native sgml-mode +;; + +(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t ) +(setq auto-mode-alist + (append + (list + '("\\.sgm$" . sgml-mode) + '("\\.sgml$" . sgml-mode) + ) + auto-mode-alist)) + +;; set some psgml variables + +(setq sgml-auto-activate-dtd t) +(setq sgml-omittag-transparent t) +(setq sgml-balanced-tag-edit t) +(setq sgml-auto-insert-required-elements t) +(setq sgml-live-element-indicator t) +(setq sgml-indent-step nil) + +;; create faces to assign to markup categories + +(make-face 'sgml-comment-face) +(make-face 'sgml-start-tag-face) +(make-face 'sgml-end-tag-face) +(make-face 'sgml-entity-face) +(make-face 'sgml-doctype-face) ; DOCTYPE data +(make-face 'sgml-ignored-face) ; data ignored by PSGML +(make-face 'sgml-ms-start-face) ; marked sections start +(make-face 'sgml-ms-end-face) ; end of marked section +(make-face 'sgml-pi-face) ; processing instructions +(make-face 'sgml-sgml-face) ; the SGML declaration +(make-face 'sgml-shortref-face) ; short references + +;; view a list of available colors with the emacs-lisp command: +;; +;; list-colors-display +;; +;; please assign your own groovy colors, because these are pretty bad +(set-face-foreground 'sgml-comment-face "coral") +;(set-face-background 'sgml-comment-face "cornflowerblue") +(set-face-foreground 'sgml-start-tag-face "slateblue") +;(set-face-background 'sgml-start-tag-face "cornflowerblue") +(set-face-foreground 'sgml-end-tag-face "slateblue") +;(set-face-background 'sgml-end-tag-face "cornflowerblue") +(set-face-foreground 'sgml-entity-face "lavender") +;(set-face-background 'sgml-entity-face "cornflowerblue") +(set-face-foreground 'sgml-doctype-face "lavender") +;(set-face-background 'sgml-doctype-face "cornflowerblue") +(set-face-foreground 'sgml-ignored-face "cornflowerblue") +;(set-face-background 'sgml-ignored-face "cornflowerblue") +(set-face-foreground 'sgml-ms-start-face "coral") +;(set-face-background 'sgml-ms-start-face "cornflowerblue") +(set-face-foreground 'sgml-ms-end-face "coral") +;(set-face-background 'sgml-ms-end-face "cornflowerblue") +(set-face-foreground 'sgml-pi-face "coral") +;(set-face-background 'sgml-pi-face "cornflowerblue") +(set-face-foreground 'sgml-sgml-face "coral") +;(set-face-background 'sgml-sgml-face "cornflowerblue") +(set-face-foreground 'sgml-shortref-face "coral") +;(set-face-background 'sgml-shortref-face "cornflowerblue") + +;; assign faces to markup categories + +(setq sgml-markup-faces ' + ( + (comment . sgml-comment-face) + (start-tag . sgml-start-tag-face) + (end-tag . sgml-end-tag-face) + (entity . sgml-entity-face) + (doctype . sgml-doctype-face) + (ignored . sgml-ignored-face) + (ms-start . sgml-ms-start-face) + (ms-end . sgml-ms-end-face) + (pi . sgml-pi-face) + (sgml . sgml-sgml-face) + (shortref . sgml-shortref-face) + )) + +;; tell PSGML to pay attention to face settings +(setq sgml-set-face t) +;; ...done setting up psgml-mode. +;; ******************************************************************* + + Then restart Emacs +
+ +
+ SGML Smoke Test + Try the following smoke test. Start a new file, + /tmp/test.sgml for + example, and enter the following: + + +!DOCTYPE test [ +<!ELEMENT test - - (#PCDATA)> +] + + Enter C cC + p. If Emacs + manages to parse your DTD, you will see Parsing + prolog...done in the minibuffer. Try + C-c C-e RETURN to insert a + test element. If + things are working correctly, you should see the following + in Emacs: + +!DOCTYPE test [ +<!ELEMENT test - - (#PCDATA)> +] +testtest + +
+ +
+ Writing a New HOWTO in DocBook + Start a new file for your HOWTO and enter the + following: + +!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN" + + Enter CcC + p and hold + your breath. If everything goes as planned, you will see + Emacs chewing for a few seconds and then Parsing + prolog...done in the minibuffer. + At this point, enter C cCeRETURN to insert an + article element and + proceed to write your HOWTO. +
+ +
+ Quick Reference for Emacs with PSGML + See Nik Clayton's primer for FreeBSD documentation: + http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html + +
+
+
+ +
+ VIM + http://www.vim.org + No mention of Emacs is complete without talking about + vi. The vim + + Editors + vim + + VIM (Vi IMproved) editor has the functionality of + regular vi, but also has an SGML mode that will + color-coordinate your screen to show where tags are. +
+ Getting Started + The vim program comes in many parts. There is + the plain vim program, which is compatibile with the + vi program and its commands. Red Hat users will want the vim-common + and vim-minimal packages. Next is the enhanced + vim, which includes the highlighting and other + features of vim over regular vi. Red Hat + users will want vim-enhanced. Last, but certainly not least, is the + X interface, which gives a graphical interface, menus, and mouse + control. To separate this from vim or vi, the command for graphical + access is called gvim. +
+
+ Loading or starting new documents + In both vim and gvim modes, + .sgml files will be automatically recognized and + enter into sgml mode. A series of known DocBook tags + have been entered into vim and will he highlighted + in brown if a tag is known. If it isn't, it will appear in light blue. + attributes to known tags are in light blue, and values for the + attributes are in pink. From here on, you can use regular vi + commands to navigate and edit. + + While VIM has an XML mode, this mode will not highlight known + and unknown DocBook tags. You can still force VIM into + SGML mode if you like using the :set ft=sgml + command. Note that this will not have any affect on the file + or its contents, only the highlighting within VIM. + +
+
+ +
+ WordPerfect 9 (Corel Office 2000) + http://www.corel.com/ + WordPerfect 9 for the MS Windows platform has support + for SGML and DocBook 3.0. WordPerfect 9 for Linux has no SGML + capabilities. + This is the least expensive of the commercial + applications that support SGML. +
+ +
+ epcEdit + http://www.tksgml.de/ + The epcEdit + + Editors + epcEdit + + epcEdit program allows you to visually edit SGML + files. It has the advantages of not needing to know Emacs or + vi before starting, and is cross-platform, working in both + Windows and Linux. This is a commercial application, and + pricing can be found at + http://www.tksgml.de/pricing.html + + Along with visual editing, epcEdit will also validate + documents on loading, and on demand by using the DocumentValidate + command. + +
+ epcEdit screen shot + + + + + + + + + The screen shot of the epcEdit program shows a + tree on the left side that has the SGML document in a + hierarchy, while the right side shows the document. + Tags are shown with a grey background. + + +
+
+ +
+ nedit + http://nedit.org + To be fair, + nedit + + Editors + nedit + + nedit is more + for programmers, so it might seem a bit of overkill for new + users and especially non-programmers. All that aside, it's + extremely powerful, allowing for color coding of tags. Unlike + epcEdit, nedit doesn't allow you to automatically insert tags + or automatically validate your code. However, it does allow + for shell commands to be run against the contents of the + window (as opposed to saving the file, then checking). In a + few minutes, I was able to set up nsgmls to + validate the SGML and aspell to do my spell + checking. + +
+ nedit screen shot + + + + + + + + + The nedit program can provide line numbers + across the left side of the screen, handy for when + nsgmls complains of errors + + +
+ +
+ Using nedit + For writing new documentation, it is recommended that + you download and use the LDP DocBook template. Once you have + the file, you can start up nedit and begin editing. If the + file is saved with a .sgml extension, nedit will load the file + up with SGML/HTML tags enabled. You can turn this on + explicitly using the + PreferencesLanguage + ModeSGML + HTML command. +
+ +
+ Tips and tricks with nedit + Since you can feed the contents of your window to + outside programs, you can easily extend nedit to perform + repetitive functions. The example you'll see here is to + validate the SGML code using nsgmls. + Select + PreferencesDefault + SettingsCustomize + MenusShell + Menu.... This will bring up the + Shell Command dialog box, with all the shell commands nedit + has listed under the + Shell menu. Under + Menu Entry, enter "SGML Validate". This will be the entry + you'll see on the screen. Under Accelerator, press + AltS. + Once this menu item is set up, you can press + AltS + to have the SGML Validate automatically run. Under Command + Input, select window, and under Command Output, select + dialog. Under Command to Execute, enter nsgmls -sv. Note + that nsgmls has to be in your + PATH for this to work properly. + +
+ Adding shell commands to nedit + + + + + + + + +
+ + Click OK and you'll now be back + at the main nedit screen. Load up an SGML file, and select + ShellSGML + Validate or press + AltS. + The nedit program will fire up and check + the contents of the window. The reason for using -sv is that + the -v tells nsgmls to output the version + of the program, so you'll always get output and know that + nsgmls has run. If all you get is a + version number, then there are no errors with the document. + If there are errors, then they'll be listed in the separate + window for you to see. If you have line numbers turned on + (using + PreferencesShow + Line Numbers) then finding the + errors is much simpler, as nsgmls will list + errors by their line number. + +
+ nsgmls output on success + + + + + + + + + If nsgmls reports success, it merely reports the version of nsgmls + + +
+
+
+ +
+ Morphon XML editor + http://www.morphon.com/xmleditor/index.shtml + This is a commerical application that has a free 30 day + license available for download. It is written in Java, allowing + it to run on any platform that has a JVM (that is, works in both + Windows and Linux). The cost is $150USD for a single user + license, and $75USD for a student license. + On the plus sides of XMLEditor is the left side of the + screen shows the heirarchy of the document (starting with Book + and so on). Selecting an item in the list brings you to that + part of the document so you can edit it. The right part of the + screen shows the text without any markup or tags being shown. + If you have external files as ELEMENTS (as the LDP Author Guide + does), XMLEditor will follow the links and load the files, so + you always work on the entire work. On the minus side of this, + you will get errors if a file (like index.xml) is + missing. +
+
+