Documentation Authoring
- not suffer from an oversupply of open-source authoring tools. The
- most common tool set is the
- editor with appropriate editing mode. On some systems
- these tools are provided in a typical full installation.
+ The documentation sources are most conveniently modified with an editor
+ that has a mode for editing XML, and even more so if it has some awareness
+ of XML schema languages so that it can know about
+
DocBook syntax specifically.
-
-
Emacs/PSGML
-
-
PSGML is the most common and most
- powerful mode for editing
SGML documents.
- When properly configured, it will allow you to use
-
Emacs to insert tags and check markup
- consistency. You could use it for
HTML as
- PSGML web site for downloads, installation instructions, and
- detailed documentation.
-
-
- There is one important thing to note with
-
PSGML: its author assumed that your
- main
SGML DTD directory
- would be /usr/local/lib/sgml. If, as in the
- examples in this chapter, you use
- /usr/local/share/sgml, you have to
- compensate for this, either by setting
- SGML_CATALOG_FILES environment variable, or you
- can customize your
PSGML installation
- (its manual tells you how).
-
-
- Put the following in your ~/.emacs
- environment file (adjusting the path names to be appropriate for
- your system):
-
-; ********** for SGML mode (psgml)
-
-(setq sgml-omittag t)
-(setq sgml-shorttag t)
-(setq sgml-minimize-attributes nil)
-(setq sgml-always-quote-attributes t)
-(setq sgml-indent-step 1)
-(setq sgml-indent-data t)
-(setq sgml-parent-document nil)
-(setq sgml-exposed-tags nil)
-(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
-
-(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
-
-
- and in the same file add an entry for
SGML- into the (existing) definition for
- auto-mode-alist:
-(setq
- auto-mode-alist
- '(("\\.sgml$" . sgml-mode)
- ))
-
-
-
- You might find that when using
PSGML, a
- comfortable way of working with these separate files of book
- parts is to insert a proper DOCTYPE
- declaration while you're editing them. If you are working on
- this source, for instance, it is an appendix chapter, so you
- would specify the document as an appendix
instance
- of a DocBook document by making the first line look like this:
-
-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
-
-
- This means that anything and everything that reads
-
SGML will get it right, and I can verify the
- document with nsgmls -s docguide.sgml. (But
- you need to take out that line before building the entire
- documentation set.)
-
-
+ Note that for historical reasons the documentation source files are named
+ with an extension .sgml even though they are now XML
+ files. So you might need to adjust your editor configuration to set the
+ correct mode.
+
-
<span class="marked">Other Emacs Mode</span>s
+
<span class="marked">Emac</span>s
-
GNU Emacs ships with a different
-
SGML mode, which is not quite as powerful as
-
PSGML, but it's less confusing and
- lighter weight. Also, it offers syntax highlighting (font lock),
- which can be very helpful.
- src/tools/editors/emacs.samples contains
- sample settings for this mode.
+
nXML Mode, which ships with
+
Emacs, is the most common mode for editing
+
XML documents with
Emacs.
+ It will allow you to use
Emacs to insert tags
+ and check markup consistency, and it supports
+
DocBook out of the box. Check the
+ url="https://www.gnu.org/software/emacs/manual/html_mono/nxml-mode.html">
+ nXML manual for detailed documentation.
- Norm Walsh offers a
- specifically for DocBook which also has font-lock and a number of features to
- reduce typing.
+ src/tools/editors/emacs.samples contains
+ recommended settings for this mode.
;;; documentation files
-(add-hook 'sgml-mode-hook
- (defun postgresql-sgml-mode-hook ()
+;; *.sgml files are actually XML
+(add-to-list 'auto-mode-alist '("/postgres\\(ql\\)?/.*\\.sgml\\'" . nxml-mode))
+
+(add-hook 'nxml-mode-hook
+ (defun postgresql-xml-mode-hook ()
(when (string-match "/postgres\\(ql\\)?/" buffer-file-name)
(setq fill-column 78)
- (setq indent-tabs-mode nil)
- (setq sgml-basic-offset 1))))
+ (setq indent-tabs-mode nil))))
+
+;; The *.xsl files use 2-space indent, which is consistent with
+;; docbook-xsl sources and also the nxml-mode default. But the *.sgml
+;; files use 1-space indent, mostly for historical reasons at this
+;; point.
+(add-hook 'nxml-mode-hook
+ (defun postgresql-xml-src-mode-hook ()
+ (when (string-match "/postgres\\(ql\\)?/.*\\.sgml\\'" buffer-file-name)
+ (setq nxml-child-indent 1))))
;;; Makefiles
projects / postgresql.git / commitdiff