From dee302e611c51660a0dcafae0c6661768e6210e4 Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Fri, 18 Dec 1998 16:17:29 +0000 Subject: [PATCH] Include more details on editing with Emacs. Remove mention of the old "migration" flat files. Change URLs for resources to point to areas, not particular files. That way things stay correct even when version of tools change. Suggested by Vince Vielhaber. --- doc/src/sgml/docguide.sgml | 237 ++++++++++++++++++++++++------------- 1 file changed, 152 insertions(+), 85 deletions(-) diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 04a5195eb8..c24a6ad2fa 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -1,9 +1,16 @@ Documentation Files @@ -481,15 +540,6 @@ Status ./doc/README.support Not converted ./doc/TODO.GEQO Removed. Superceded by geqo.sgml ./doc/userguide.ps Removed (converted to SGML) - ./migration/1.02_to_1.02.1 Removed. Superceded by release.sgml - ./migration/1.09_to_6.0 Removed. Superceded by release.sgml - ./migration/1.0_to_1.01 Removed. Superceded by release.sgml - ./migration/6.0_to_6.1 Removed. Superceded by release.sgml - ./migration/6.1_to_6.1.1 Removed. Superceded by release.sgml - ./migration/6.1_to_6.2 Removed. Superceded by release.sgml - ./migration/6.2.1_to_6.3 Removed. Superceded by release.sgml - ./migration/6.2_to_6.2.1 Removed. Superceded by release.sgml - ./migration/6.3.1_to_6.3.2 Removed. Superceded by release.sgml ./src/DEVELOPERS Not converted ./src/backend/access/nbtree/README Not converted ./src/backend/catalog/README Not converted @@ -670,64 +720,6 @@ Status ---> - - -The Documentation Project - - -Packaged documentation is available in both -HTML and Postscript -formats. These are available as part of the standard -Postgres installation. We discuss here -working with the documentation sources and generating documentation -packages. - - - -This is the first release of new Postgres -documentation in three years. The content and environment are in flux -and still evolving. - - - - -The purpose of SGML is to allow an author to -specify the structure and content of a document (e.g. using the -DocBook DTD), and to -have the document style define how that content is rendered into a -final form (e.g. using Norm Walsh's stylesheets). - - -See -Introduction to DocBook for a nice "quickstart" summary of -DocBook features. - DocBook -Elements provides a powerful cross-reference for features of -DocBook. - - -This documentation set is constructed using several tools, including -James Clark's - jade - and Norm Walsh's -Modular DocBook Stylesheets. - - -Currently, hardcopy is produced by importing Rich Text -Format (RTF) output from -jade into -ApplixWare for minor formatting fixups then -exporting as a Postscript file. - - - -TeX is a supported format for -jade output, but was not used at this time -for several reasons, including the inability to make minor format -fixes before committing to hardcopy and generally inadequate table -support in the TeX -stylesheets. Styles and Conventions @@ -776,12 +768,12 @@ be included below. --> -Authoring Tools +SGML Authoring Tools -The current Postgres documentation set is written using +The current Postgres documentation set was written using a plain text editor (or emacs/psgml; see below) with the content marked up using -SGML. +SGML DocBook tags. SGML and DocBook do not suffer @@ -793,7 +785,63 @@ On some systems (e.g. RedHat Linux) these tools are provided in a typical full i emacs/psgml -When using emacs/psgml, a comfortable way of working with +emacs (and xemacs) have +an SGML major mode. When properly configured, +this will allow you to use emacs to insert tags and +check markup consistancy. + + + Put the following in your ~/.emacs environment file: + + +; ********** for SGML mode (psgml) + +(setq sgml-catalog-files "/usr/lib/sgml/CATALOG") +(setq sgml-local-catalogs "/usr/lib/sgml/CATALOG") + +(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t ) + + +and add an entry in the same file +for SGML into the (existing) definition for +auto-mode-alist: + + +(setq + auto-mode-alist + '(("\\.sgml$" . sgml-mode) + )) + + +Each SGML source file has the following block at the +end of the file: + + +!-- 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: +-- + + + + The Postgres distribution includes a + parsed DTD definitions file reference.ced. +You may find that + + +When using emacs/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's an appendix chapter, so you would specify the document as an "appendix" instance of @@ -1041,9 +1089,10 @@ and RTF. These instructions do not cover new jade/DocBook -support in the sgml-tools package. The authors have -not tried this package since it adopted DocBook, but it is almost certainly -a good candidate for use. +support in the +sgml-tools +package. The authors have not tried this package since it adopted DocBook, +but it is almost certainly a good candidate for use. Prerequisites @@ -1061,21 +1110,23 @@ a good candidate for use. - -James Clark's Jade version 1.1 + +James Clark's Jade +(version 1.1 in file jade1_1.zip was current at the time of writing) DocBook version 3.0 - -Norman Walsh's Modular Stylesheets -version 1.19 + +Norman Walsh's Modular Stylesheets +(version 1.19 was used to produce these documents) - -Lennart Staflin's PSGML version 1.0.1 + +Lennart Staflin's PSGML +(version 1.0.1 in psgml-1.0.1.tar.gz was available at the time of writing) @@ -1266,14 +1317,14 @@ kit in a suitable place. A good place to dot this would be directory tree under /usr/local/share/docbook. The command will be something like -unzip -aU db107.zip +unzip -aU db119.zip One way to test the installation is to build the HTML and RTF forms of the -PostgreSQL manual. +PostgreSQL User's Guide. @@ -1316,7 +1367,7 @@ URL. Unpack the distribution file, run configure, make and make install to put the byte-compiled files and info library in place. - + Then add the following lines to your /usr/local/share/emacs/site-lisp/site-start.el @@ -1522,3 +1573,19 @@ Run texhash to update the tex database. + -- 2.40.0