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
http://www.vim.org
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)
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.
3.5.4. epcEdit
http://www.tksgml.de/
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
http://nedit.org
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 OK 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.
