From: Peter Eisentraut <peter_e@gmx.net>
Date: Fri, 13 Jul 2018 19:23:41 +0000 (+0200)
Subject: Update documentation editor setup instructions
X-Git-Tag: REL_11_BETA3~77
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=bc4e355f013d6122e4ae17fa99e9db20babbb86a;p=postgresql

Update documentation editor setup instructions

Now that the documentation sources are in XML rather than SGML, some of
the documentation about the editor, or more specifically Emacs, setup
needs updating.  The updated instructions recommend using nxml-mode,
which works mostly out of the box, with some small tweaks in
emacs.samples and .dir-locals.el.

Also remove some obsolete stuff in .dir-locals.el.  I did, however,
leave the sgml-mode settings in there so that someone using Emacs
without emacs.samples gets those settings when editing a *.sgml file.
---

diff --git a/.dir-locals.el b/.dir-locals.el
index 9525d6b604..eff4671ef8 100644
--- a/.dir-locals.el
+++ b/.dir-locals.el
@@ -5,8 +5,8 @@
             (fill-column . 78)
             (indent-tabs-mode . t)
             (tab-width . 4)))
- (dsssl-mode . ((indent-tabs-mode . nil)))
- (nxml-mode . ((indent-tabs-mode . nil)))
+ (nxml-mode . ((fill-column . 78)
+               (indent-tabs-mode . nil)))
  (perl-mode . ((perl-indent-level . 4)
                (perl-continued-statement-offset . 2)
                (perl-continued-brace-offset . 4)
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index b4338e0e73..21bb429745 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -393,112 +393,36 @@ ADDITIONAL_FLAGS='-Xmx1500m'
   <title>Documentation Authoring</title>
 
    <para>
-    <acronym>SGML</acronym> and <productname>DocBook</productname> do
-    not suffer from an oversupply of open-source authoring tools. The
-    most common tool set is the
-    <productname>Emacs</productname>/<productname>XEmacs</productname>
-    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
+    <productname>DocBook</productname> syntax specifically.
    </para>
 
-   <sect2>
-    <title>Emacs/PSGML</title>
-
-    <para>
-     <productname>PSGML</productname> is the most common and most
-     powerful mode for editing <acronym>SGML</acronym> documents.
-     When properly configured, it will allow you to use
-     <application>Emacs</application> to insert tags and check markup
-     consistency.  You could use it for <acronym>HTML</acronym> as
-     well.  Check the <ulink url="http://www.lysator.liu.se/projects/about_psgml.html">
-     PSGML web site</ulink> for downloads, installation instructions, and
-     detailed documentation.
-    </para>
-
-    <para>
-     There is one important thing to note with
-     <productname>PSGML</productname>: its author assumed that your
-     main <acronym>SGML</acronym> <acronym>DTD</acronym> directory
-     would be <filename>/usr/local/lib/sgml</filename>.  If, as in the
-     examples in this chapter, you use
-     <filename>/usr/local/share/sgml</filename>, you have to
-     compensate for this, either by setting
-     <envar>SGML_CATALOG_FILES</envar> environment variable, or you
-     can customize your <productname>PSGML</productname> installation
-     (its manual tells you how).
-    </para>
-
-    <para>
-     Put the following in your <filename>~/.emacs</filename>
-     environment file (adjusting the path names to be appropriate for
-     your system):
-
-<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-exposed-tags nil)
-(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
-
-(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
-</programlisting>
-
-     and in the same file add an entry for <acronym>SGML</acronym>
-     into the (existing) definition for
-     <varname>auto-mode-alist</varname>:
-<programlisting>
-(setq
-  auto-mode-alist
-  '(("\\.sgml$" . sgml-mode)
-   ))
-</programlisting>
-    </para>
-
-    <para>
-     You might find that when using <productname>PSGML</productname>, a
-     comfortable way of working with these separate files of book
-     parts is to insert a proper <literal>DOCTYPE</literal>
-     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 <quote>appendix</quote> instance
-     of a DocBook document by making the first line look like this:
-
-<programlisting>
-&lt;!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN"&gt;
-</programlisting>
-
-     This means that anything and everything that reads
-     <acronym>SGML</acronym> will get it right, and I can verify the
-     document with <command>nsgmls -s docguide.sgml</command>.  (But
-     you need to take out that line before building the entire
-     documentation set.)
-    </para>
-   </sect2>
+   <para>
+    Note that for historical reasons the documentation source files are named
+    with an extension <filename>.sgml</filename> even though they are now XML
+    files.  So you might need to adjust your editor configuration to set the
+    correct mode.
+   </para>
 
    <sect2>
-    <title>Other Emacs Modes</title>
+    <title>Emacs</title>
 
     <para>
-     <productname>GNU Emacs</productname> ships with a different
-     <acronym>SGML</acronym> mode, which is not quite as powerful as
-     <productname>PSGML</productname>, but it's less confusing and
-     lighter weight.  Also, it offers syntax highlighting (font lock),
-     which can be very helpful.
-     <filename>src/tools/editors/emacs.samples</filename> contains
-     sample settings for this mode.
+     <productname>nXML Mode</productname>, which ships with
+     <productname>Emacs</productname>, is the most common mode for editing
+     <acronym>XML</acronym> documents with <productname>Emacs</productname>.
+     It will allow you to use <application>Emacs</application> to insert tags
+     and check markup consistency, and it supports
+     <productname>DocBook</productname> out of the box.  Check the <ulink
+     url="https://www.gnu.org/software/emacs/manual/html_mono/nxml-mode.html">
+     nXML manual</ulink> for detailed documentation.
     </para>
 
     <para>
-     Norm Walsh offers a
-     <ulink url="http://nwalsh.com/emacs/docbookide/index.html">major mode</ulink>
-     specifically for DocBook which also has font-lock and a number of features to
-     reduce typing.
+     <filename>src/tools/editors/emacs.samples</filename> contains
+     recommended settings for this mode.
     </para>
    </sect2>
 
diff --git a/src/tools/editors/emacs.samples b/src/tools/editors/emacs.samples
index 5f08c71dd1..a7152b04bc 100644
--- a/src/tools/editors/emacs.samples
+++ b/src/tools/editors/emacs.samples
@@ -62,12 +62,23 @@
 
 ;;; 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