3.5. Editing tools
The following tools may be used to create, edit, or validate your HOWTO.
3.5.1. Emacs (PSGML)
Optional - http://www.lysator.liu.se/~lenst/about_psgml/
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.
3.5.1.1. Writing SGML using PSGML
3.5.1.1.1. 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 (C-himpsgml).
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.
3.5.1.1.2. 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
3.5.1.1.3. 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)> ]> <test></test> |
3.5.1.1.4. 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 C-cC-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-cC-eRETURN to insert an <article> element and proceed to write your HOWTO.
3.5.1.1.5. Quick Reference for Emacs with PSGML
See Nik Clayton's primer for FreeBSD documentation: http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html
3.5.2. VIM
No mention of Emacs is complete without talking about vi. The 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.
3.5.2.1. 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.
3.5.2.2. 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.
3.5.3. WordPerfect 9 (Corel Office 2000)
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.
3.5.4. epcEdit
The 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 -> command.
3.5.5. nedit
To be fair, 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.
3.5.5.1. 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 ->-> command.
3.5.5.2. 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 ->->->. This will bring up the Shell Command dialog box, with all the shell commands nedit has listed under the menu. Under Menu Entry, enter "SGML Validate". This will be the entry you'll see on the screen. Under Accelerator, press Alt-S. Once this menu item is set up, you can press Alt-S 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.
Click and you'll now be back at the main nedit screen. Load up an SGML file, and select -> or press Alt-S. 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 ->) then finding the errors is much simpler, as nsgmls will list errors by their line number.
3.5.6. 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.