1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>G.4.Documentation Authoring</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="docguide.html" title="AppendixG.Documentation">
<link rel="prev" href="docguide-build.html" title="G.3.Building The Documentation">
<link rel="next" href="docguide-style.html" title="G.5.Style Guide">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="docguide-authoring"></a>G.4.Documentation Authoring</h2></div></div></div>
<p> <acronym class="acronym">SGML</acronym> and <span class="productname">DocBook</span> do
not suffer from an oversupply of open-source authoring tools. The
most common tool set is the
<span class="productname">Emacs</span>/<span class="productname">XEmacs</span>
editor with appropriate editing mode. On some systems
these tools are provided in a typical full installation.
</p>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id902308"></a>G.4.1.Emacs/PSGML</h3></div></div></div>
<p> <span class="productname">PSGML</span> is the most common and most
powerful mode for editing <acronym class="acronym">SGML</acronym> documents.
When properly configured, it will allow you to use
<span class="application">Emacs</span> to insert tags and check markup
consistency. You could use it for <acronym class="acronym">HTML</acronym> as
well. Check the <a href="http://www.lysator.liu.se/projects/about_psgml.html" target="_top"> PSGML web site</a> for downloads, installation instructions, and
detailed documentation.
</p>
<p> There is one important thing to note with
<span class="productname">PSGML</span>: its author assumed that your
main <acronym class="acronym">SGML</acronym> <acronym class="acronym">DTD</acronym> directory
would be <code class="filename">/usr/local/lib/sgml</code>. If, as in the
examples in this chapter, you use
<code class="filename">/usr/local/share/sgml</code>, you have to
compensate for this, either by setting
<code class="envar">SGML_CATALOG_FILES</code> environment variable, or you
can customize your <span class="productname">PSGML</span> installation
(its manual tells you how).
</p>
<p> Put the following in your <code class="filename">~/.emacs</code>
environment file (adjusting the path names to be appropriate for
your system):
</p>
<pre class="programlisting">; ********** 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-default-dtd-file "./reference.ced")
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
(setq sgml-ecat-files nil)
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )</pre>
<p>
and in the same file add an entry for <acronym class="acronym">SGML</acronym>
into the (existing) definition for
<code class="varname">auto-mode-alist</code>:
</p>
<pre class="programlisting">(setq
auto-mode-alist
'(("\\.sgml$" . sgml-mode)
))</pre>
<p>
</p>
<p> Currently, each <acronym class="acronym">SGML</acronym> source file has the
following block at the end of the file:
</p>
<pre class="programlisting"><!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
--></pre>
<p>
This will set up a number of editing mode parameters even if you
do not set up your <code class="filename">~/.emacs</code> file, but it is
a bit unfortunate, since if you followed the installation
instructions above, then the catalog path will not match your
location. Hence you might need to turn off local variables:
</p>
<pre class="programlisting">(setq inhibit-local-variables t)</pre>
<p>
</p>
<p> The <span class="productname">PostgreSQL</span> distribution includes a
parsed DTD definitions file <code class="filename">reference.ced</code>.
You may find that when using <span class="productname">PSGML</span>, a
comfortable way of working with these separate files of book
parts is to insert a proper <code class="literal">DOCTYPE</code>
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 “<span class="quote">appendix</span>” instance
of a DocBook document by making the first line look like this:
</p>
<pre class="programlisting"><!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN"></pre>
<p>
This means that anything and everything that reads
<acronym class="acronym">SGML</acronym> will get it right, and I can verify the
document with <code class="command">nsgmls -s docguide.sgml</code>. (But
you need to take out that line before building the entire
documentation set.)
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id902546"></a>G.4.2.Other Emacs modes</h3></div></div></div>
<p> <span class="productname">GNU Emacs</span> ships with a different
<acronym class="acronym">SGML</acronym> mode, which is not quite as powerful as
<span class="productname">PSGML</span>, but it's less confusing and
lighter weight. Also, it offers syntax highlighting (font lock),
which can be very helpful.
</p>
<p> Norm Walsh offers a
<a href="http://nwalsh.com/emacs/docbookide/index.html" target="_top">major mode</a>
specifically for DocBook which also has font-lock and a number of features to
reduce typing.
</p>
</div>
</div></body>
</html>
|
