database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-04-25 21:42:33 +03:00
Code

Update documentation build instructions.

Browse Source
This commit is contained in:
Peter Eisentraut 2003-06-06 14:17:08 +00:00
parent 7ea8e491c8
commit 2c93861f7c
1 changed files with 244 additions and 433 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

677
doc/src/sgml/docguide.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.43 2003/02/19 04:06:27 momjian Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.44 2003/06/06 14:17:08 petere Exp $ -->
<appendix id="docguide"> <appendix id="docguide">
<title>Documentation</title> <title>Documentation</title>
@ -20,7 +20,7 @@
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Postscript, for printing PDF or Postscript, for printing
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -35,56 +35,14 @@
documenting various implementation issues. documenting various implementation issues.
</para> </para>
<para>
The documentation is organized into several <quote>books</quote>:
<itemizedlist>
<listitem>
<para>
<citetitle>Tutorial</citetitle>: introduction for new users
</para>
</listitem>
<listitem>
<para>
<citetitle>User's Guide</citetitle>: documents the SQL implementation
</para>
</listitem>
<listitem>
<para>
<citetitle>Reference Manual</citetitle>: reference pages for programs and SQL commands
</para>
</listitem>
<listitem>
<para>
<citetitle>Administrator's Guide</citetitle>: installation and server maintenance
</para>
</listitem>
<listitem>
<para>
<citetitle>Programmer's Guide</citetitle>: programming client
applications and server extensions
</para>
</listitem>
<listitem>
<para>
<citetitle>Developer's Guide</citetitle>: assorted information
for developers of <productname>PostgreSQL</> proper
</para>
</listitem>
</itemizedlist>
All books are available as HTML and Postscript. The
<citetitle>Reference Manual</citetitle> contains reference entries which
are also shipped as man pages.
</para>
<para> <para>
<acronym>HTML</acronym> documentation and man pages are part of a <acronym>HTML</acronym> documentation and man pages are part of a
standard distribution and are installed by default. Postscript standard distribution and are installed by default. PDF and
format documentation is available separately for download. Postscript format documentation is available separately for
download.
</para> </para>
<sect1> <sect1 id="docguide-docbook">
<title>DocBook</title> <title>DocBook</title>
<para> <para>
The documentation sources are written in The documentation sources are written in
@ -115,7 +73,7 @@
</sect1> </sect1>
<sect1 id="doc-toolsets"> <sect1 id="docguide-toolsets">
<title>Tool Sets</title> <title>Tool Sets</title>
<para> <para>
@ -211,18 +169,17 @@
the various tools that are needed to process the documentation. the various tools that are needed to process the documentation.
These will be described below. There may be some other packaged These will be described below. There may be some other packaged
distributions for these tools. Please report package status to the distributions for these tools. Please report package status to the
docs mailing list and we will include that information here. documentation mailing list, and we will include that information
here.
</para> </para>
<sect2> <sect2>
<title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title> <title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>
<para> <para>
Many vendors provide a complete RPM set for DocBook processing in Most vendors provide a complete RPM set for DocBook processing in
their distribution, which is usually based on the <ulink their distribution. Look for an <quote>SGML</quote> option while
url="http://sources.redhat.com/docbook-tools/">docbook-tools</ulink> installing, or the following packages:
effort at Red Hat Software. Look for an <quote>SGML</quote>
option while installing, or the following packages:
<filename>sgml-common</filename>, <filename>docbook</filename>, <filename>sgml-common</filename>, <filename>docbook</filename>,
<filename>stylesheets</filename>, <filename>openjade</filename> <filename>stylesheets</filename>, <filename>openjade</filename>
(or <filename>jade</filename>). Possibly (or <filename>jade</filename>). Possibly
@ -475,8 +432,8 @@ CATALOG "docbook-dsssl--1.<replaceable>xx</>/catalog
Because stylesheets change rather often, and it's sometimes Because stylesheets change rather often, and it's sometimes
beneficial to try out alternative versions, beneficial to try out alternative versions,
<productname>PostgreSQL</productname> doesn't use this catalog <productname>PostgreSQL</productname> doesn't use this catalog
entry. See <xref linkend="doc-build"> for information about how entry. See <xref linkend="docguide-toolsets-configure"> for
to select the stylesheets instead. information about how to select the stylesheets instead.
</para> </para>
</sect3> </sect3>
@ -533,17 +490,15 @@ CATALOG "docbook-dsssl--1.<replaceable>xx</>/catalog
</sect3> </sect3>
</sect2> </sect2>
</sect1>
<sect2 id="docguide-toolsets-configure">
<sect1 id="doc-build"> <title>Detection by <command>configure</command></title>
<title>Building The Documentation</title>
<para> <para>
Before you can build the documentation you need to run the Before you can build the documentation you need to run the
<filename>configure</filename> script as you would when building <filename>configure</filename> script as you would when building
the programs themselves. Check the output near the end of the run, the PostgreSQL programs themselves. Check the output near the end
it should look something like this: of the run, it should look something like this:
<screen> <screen>
<computeroutput> <computeroutput>
checking for onsgmls... onsgmls checking for onsgmls... onsgmls
@ -566,85 +521,46 @@ checking for sgmlspl... sgmlspl
<filename>configure</filename> afterwards. <filename>configure</filename> afterwards.
</para> </para>
</sect2>
</sect1>
<sect1 id="docguide-build">
<title>Building The Documentation</title>
<para> <para>
Once you have everything set up, change to the directory Once you have everything set up, change to the directory
<filename>doc/src/sgml</filename> and run one of the following <filename>doc/src/sgml</filename> and run one of the commands
commands: (Remember to use GNU make.) described in the following subsections to build the
<itemizedlist> documentation. (Remember to use GNU make.)
<listitem>
<para>
To build the <acronym>HTML</acronym> version of the
<citetitle>Administrator's Guide</citetitle>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.html</userinput>
</screen>
</para>
</listitem>
<listitem>
<para>
For the RTF version of the same:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.rtf</userinput>
</screen>
</para>
</listitem>
<listitem>
<para>
To get a <acronym>DVI</acronym> version via
<productname>JadeTeX</productname>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.dvi</userinput>
</screen>
</para>
</listitem>
<listitem>
<para>
And Postscript from the <acronym>DVI</acronym>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.ps</userinput>
</screen>
</para>
<note>
<para>
The official Postscript format documentation is generated
differently. See <xref linkend="doc-hardcopy"> below.
</para>
</note>
</listitem>
</itemizedlist>
The other books can be built with analogous commands by replacing
<literal>admin</literal> with one of <literal>developer</literal>,
<literal>programmer</literal>, <literal>tutorial</literal>, or
<literal>user</literal>. Using <literal>postgres</literal> builds
an integrated version of all 5 books, which is practical since the
browser interface makes it easy to move around all of the
documentation by just clicking.
</para> </para>
<sect2> <sect2>
<title>HTML</title> <title>HTML</title>
<para> <para>
When building <acronym>HTML</acronym> documentation in To build the <acronym>HTML</acronym> version of the documentation:
<filename>doc/src/sgml</filename>, some of the resulting files <screen>
will possibly (or quite certainly) have conflicting names between <prompt>doc/src/sgml$ </prompt><userinput>gmake html</userinput>
books. Therefore the files are not in that directory in the </screen>
regular distribution. Instead, the files belonging to each book This is also the default target.
are stored in a tar archive that is unpacked at installation time. </para>
To create a set of <acronym>HTML</acronym> documentation packages
use the commands <para>
When the HTML documentation is built, the process also generates
the linking information for the index entries. Thus, if you want
your documentation to have a concept index at the end, you need to
build the HTML documentation once, and then build the
documentation again in whatever format you like.
</para>
<para>
To allow for easier handling in the final distribution, the files
comprising the HTML documentation are stored in a tar archive that
is unpacked at installation time. To create the
<acronym>HTML</acronym> documentation package, use the commands
<programlisting> <programlisting>
cd doc/src cd doc/src
gmake tutorial.tar.gz
gmake user.tar.gz
gmake admin.tar.gz
gmake programmer.tar.gz
gmake postgres.tar.gz gmake postgres.tar.gz
gmake install
</programlisting> </programlisting>
In the distribution, these archives live in the In the distribution, these archives live in the
<filename>doc</filename> directory and are installed by default <filename>doc</filename> directory and are installed by default
@ -652,118 +568,142 @@ gmake install
</para> </para>
</sect2> </sect2>
<sect2 id="doc-manpages"> <sect2>
<title>Manpages</title> <title>Manpages</title>
<para> <para>
We use the <application>docbook2man</application> utility to We use the <application>docbook2man</application> utility to
convert <productname>DocBook</productname> convert <productname>DocBook</productname>
<sgmltag>REFENTRY</sgmltag> pages to *roff output suitable for man <sgmltag>refentry</sgmltag> pages to *roff output suitable for man
pages. The man pages are also distributed as a tar archive, pages. The man pages are also distributed as a tar archive,
similar to the <acronym>HTML</acronym> version. To create the man page package, use the commands similar to the <acronym>HTML</acronym> version. To create the man
page package, use the commands
<programlisting> <programlisting>
cd doc/src cd doc/src
gmake man gmake man.tar.gz
</programlisting> </programlisting>
which will result in a tar file being generated in the which will result in a tar file being generated in the
<filename>doc/src</filename> directory. <filename>doc/src</filename> directory.
</para> </para>
<para> <para>
The man build leaves a lot of confusing output, and special care To generate quality man pages, it might be necessary to use a
must be taken to produce quality results. There is still room for hacked version of the conversion utility or do some manual
improvement in this area. postprocessing. All man pages should be manually inspected before
distribution.
</para> </para>
</sect2> </sect2>
<sect2 id="doc-hardcopy"> <sect2>
<title>Hardcopy Generation</title> <title>Print Output via <application>JadeTex</application></title>
<para>
The hardcopy Postscript documentation is generated by converting the
<acronym>SGML</acronym> source code to <acronym>RTF</acronym>, then
importing into <productname>Applixware</productname>.
After a little cleanup (see the following
section) the output is <quote>printed</quote> to a postscript file.
</para>
<!--
<para>
Some figures were redrawn to avoid having bitmap
<acronym>GIF</acronym> files in the hardcopy documentation. One
figure, of the system catalogs, was sufficiently complex that there
was not time to redraw it. It was converted to fit using the
following commands:
<programlisting>
% convert -monochrome -v -geometry 500x500'>' catalogs.ps catalogs.gif
% convert -v -crop 400x500 catalogs.gif catalogs-cropped.gif
</programlisting>
</para>
-->
<para> <para>
Several areas are addressed while generating Postscript If you want to use <application>JadeTex</application> to produce a
hardcopy, including RTF repair, ToC generation, and page break printable rendition of the documentation, you can use one of the
adjustments. following commands:
<itemizedlist>
<listitem>
<para>
To make a <acronym>DVI</acronym> version:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.dvi</userinput>
</screen>
</para>
</listitem>
<listitem>
<para>
To generate Postscript from the <acronym>DVI</acronym>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.ps</userinput>
</screen>
</para>
</listitem>
<listitem>
<para>
To make a <acronym>PDF</acronym>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.pdf</userinput>
</screen>
(Of course you can also make a <acronym>PDF</acronym> version
from the Postscript, but if you generate <acronym>PDF</acronym>
directly, it will have hyperlinks and other enhanced features.)
</para>
</listitem>
</itemizedlist>
</para> </para>
</sect2>
<sect2>
<title>Print Output via <acronym>RTF</acronym></title>
<para>
You can also create a printable version of the PostgreSQL
documentation by converting it to <acronym>RTF</acronym> and
applying minor formatting corrections using an office suite.
Depending on the capabilities of the particular office suite, you
can then convert the documentation to Postscript of
<acronym>PDF</acronym>. The procedure below illustrates this
process using <productname>Applixware</productname>.
</para>
<note>
<para>
It appears that current versions of the PostgreSQL documentation
trigger some bug in or exceed the size limit of OpenJade. If the
build process of the <acronym>RTF</acronym> version hangs for a
long time and the output file still has size 0, then you may have
hit that problem. (But keep in mind that a normal build takes 5
to 10 minutes, so don't abort too soon.)
</para>
</note>
<procedure> <procedure>
<title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title> <title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title>
<para> <para>
<application>jade</application>, an integral part of the <application>OpenJade</application> omits specifying a default
hardcopy procedure, omits specifying a default style for body style for body text. In the past, this undiagnosed problem led to
text. In the past, this undiagnosed problem led to a long process a long process of table of contents generation. However, with
of Table of Contents (ToC) generation. However, with great help great help from the <productname>Applixware</productname> folks
from the <productname>Applixware</productname> folks the symptom was diagnosed and a the symptom was diagnosed and a workaround is available.
workaround is available.
</para> </para>
<step performance="required"> <step performance="required">
<para> <para>
Generate the <acronym>RTF</acronym> input by typing (for example): Generate the <acronym>RTF</acronym> version by typing:
<programlisting> <screen>
% cd doc/src/sgml <prompt>doc/src/sgml$ </prompt><userinput>gmake postgres.rtf</userinput>
% make tutorial.rtf </screen>
</programlisting>
</para> </para>
</step> </step>
<step performance="required"> <step performance="required">
<para> <para>
Repair the RTF file to correctly specify all Repair the RTF file to correctly specify all styles, in
styles, in particular the default style. If the document particular the default style. If the document contains
contains <sgmltag>REFENTRY</sgmltag> sections, one must also <sgmltag>refentry</sgmltag> sections, one must also replace
replace formatting hints which tie a formatting hints which tie a preceding paragraph to the current
<emphasis>preceding</emphasis> paragraph to the current paragraph, and instead tie the current paragraph to the
paragraph, and instead tie the current paragraph to the following one. A utility, <command>fixrtf</command>, is
following one. A utility, <application>fixrtf</application> is available in <filename>doc/src/sgml</filename> to accomplish
available in these repairs:
<filename>doc/src/sgml</filename> to accomplish these repairs:
<programlisting> <screen>
% cd doc/src/sgml <prompt>doc/src/sgml$ </prompt><userinput>./fixrtf --refentry postgres.rtf</userinput>
% fixrtf tutorial.rtf </screen>
</programlisting> </para>
or <para>
The script adds <literal>{\s0 Normal;}</literal> as the zeroth
<programlisting> style in the document. According to
% cd doc/src/sgml <productname>Applixware</productname>, the RTF standard would
% fixrtf --refentry reference.rtf prohibit adding an implicit zeroth style, though Microsoft Word
</programlisting> happens to handle this case. For repairing
</para> <sgmltag>refentry</sgmltag> sections, the script replaces
<literal>\keepn</literal> tags with <literal>\keep</literal>.
<para>
The script adds <literal>{\s0 Normal;}</literal> as
the zero-th style in the document. According to <productname>Applixware</productname>, the
RTF standard would prohibit adding an implicit zero-th style,
though M$Word happens to handle this case. For repairing
<sgmltag>REFENTRY</sgmltag> sections, the script replaces
<literal>\keepn</literal> tags with <literal>\keep</literal>.
</para> </para>
</step> </step>
@ -776,92 +716,70 @@ gmake man
<step performance="required"> <step performance="required">
<para> <para>
Generate a new ToC using <productname>Applixware</productname>. Generate a new table of contents (ToC) using
<productname>Applixware</productname>.
</para> </para>
<substeps> <substeps>
<step> <step>
<para> <para>
Select the existing ToC lines, from the beginning of the first Select the existing ToC lines, from the beginning of the first
character on the first line to the last character of the last character on the first line to the last character of the last
line. line.
</para> </para>
</step> </step>
<step> <step>
<para> <para>
Build a new ToC using Build a new ToC using
<literal>Tools.BookBuilding.CreateToC</literal>. Select the <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
first three levels of headers for inclusion in the ToC. Building</guisubmenu><guimenuitem>Create Table of
This will Contents</guimenuitem></menuchoice>. Select the first three
replace the existing lines imported in the RTF with a native levels of headers for inclusion in the ToC. This will replace
<productname>Applixware</productname> ToC. the existing lines imported in the RTF with a native
<productname>Applixware</productname> ToC.
</para> </para>
</step> </step>
<step> <step>
<para> <para>
Adjust the ToC formatting by using Adjust the ToC formatting by using
<literal>Format.Style</literal>, selecting each of the three <menuchoice><guimenu>Format</guimenu><guimenuitem>Style</guimenuitem></menuchoice>,
ToC styles, and adjusting the indents for <literal>First</literal> and selecting each of the three ToC styles, and adjusting the
<literal>Left</literal>. Use the following values: indents for <literal>First</literal> and
<literal>Left</literal>. Use the following values:
<table> <informaltable>
<title>Indent Formatting for Table of Contents</title> <tgroup cols="3">
<tgroup cols="3"> <thead>
<thead> <row>
<row> <entry>Style</entry>
<entry> <entry>First Indent (inches)</entry>
Style <entry>Left Indent (inches)</entry>
</entry> </row>
<entry> </thead>
First Indent (inches)
</entry>
<entry>
Left Indent (inches)
</entry>
</row>
</thead>
<tbody> <tbody>
<row> <row>
<entry> <entry><literal>TOC-Heading 1</literal></entry>
<literal>TOC-Heading 1</literal> <entry><literal>0.4</literal></entry>
</entry> <entry><literal>0.4</literal></entry>
<entry> </row>
<literal>0.4</literal>
</entry>
<entry>
<literal>0.4</literal>
</entry>
</row>
<row> <row>
<entry> <entry><literal>TOC-Heading 2</literal></entry>
<literal>TOC-Heading 2</literal> <entry><literal>0.8</literal></entry>
</entry> <entry><literal>0.8</literal></entry>
<entry> </row>
<literal>0.8</literal>
</entry>
<entry>
<literal>0.8</literal>
</entry>
</row>
<row> <row>
<entry> <entry><literal>TOC-Heading 3</literal></entry>
<literal>TOC-Heading 3</literal> <entry><literal>1.2</literal></entry>
</entry> <entry><literal>1.2</literal></entry>
<entry> </row>
<literal>1.2</literal> </tbody>
</entry> </tgroup>
<entry> </informaltable>
<literal>1.2</literal>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para> </para>
</step> </step>
</substeps> </substeps>
@ -873,32 +791,15 @@ gmake man
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
Adjust page breaks. Adjust page breaks.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Adjust table column widths. Adjust table column widths.
</para> </para>
</listitem>
<listitem>
<para>
Insert figures into the document. Center each figure on the page using
the centering margins button on the <productname>Applixware</productname> toolbar.
<note>
<para>
Not all documents have figures.
You can grep the <acronym>SGML</acronym> source files for
the string <literal>graphic</literal> to identify those parts of the
documentation that may have figures. A few figures are replicated in
various parts of the documentation.
</para>
</note>
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@ -907,24 +808,11 @@ gmake man
<step performance="required"> <step performance="required">
<para> <para>
Replace the right-justified page numbers in the Examples and Replace the right-justified page numbers in the Examples and
Figures portions of the ToC with Figures portions of the ToC with correct values. This only takes
correct values. This only takes a few minutes per document. a few minutes.
</para> </para>
</step> </step>
<!--
Later stylesheets seem to not need this adjustment - thomas 2001-11-29
<step performance="required">
<para>
If a bibliography is present, remove the <firstterm>short
form</firstterm> reference title from each entry. The
<productname>DocBook</productname> stylesheets from Norm Walsh
seem to print these out, even though this is a subset of the
information immediately following.
</para>
</step>
-->
<step performance="optional"> <step performance="optional">
<para> <para>
Delete the index section from the document if it is empty. Delete the index section from the document if it is empty.
@ -938,39 +826,41 @@ Later stylesheets seem to not need this adjustment - thomas 2001-11-29
<substeps> <substeps>
<step> <step>
<para> <para>
Select the ToC field. Select the ToC field.
</para> </para>
</step> </step>
<step> <step>
<para> <para>
Select Select <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book
<literal>Tools->Book Building->Create Table of Building</guisubmenu><guimenuitem>Create Table of
Contents</literal>. Contents</guimenuitem></menuchoice>.
</para> </para>
</step> </step>
<step> <step>
<para> <para>
Unbind the ToC by selecting Unbind the ToC by selecting
<literal>Tools->Field Editing->Unprotect</literal>. <menuchoice><guimenu>Tools</guimenu><guisubmenu>Field
</para> Editing</guisubmenu><guimenuitem>Unprotect</guimenuitem></menuchoice>.
</para>
</step> </step>
<step> <step>
<para> <para>
Delete the first line in the ToC, which is an entry for the Delete the first line in the ToC, which is an entry for the
ToC itself. ToC itself.
</para> </para>
</step> </step>
</substeps> </substeps>
</step> </step>
<step performance="required"> <step performance="required">
<para> <para>
Save the document as native <productname>Applixware Words</productname> format to allow easier last Save the document as native <productname>Applixware
minute editing later. Words</productname> format to allow easier last minute editing
later.
</para> </para>
</step> </step>
@ -980,13 +870,6 @@ Later stylesheets seem to not need this adjustment - thomas 2001-11-29
to a file in Postscript format. to a file in Postscript format.
</para> </para>
</step> </step>
<step performance="required">
<para>
Compress the Postscript file using <application>gzip</application>.
Place the compressed file into the <filename>doc</filename> directory.
</para>
</step>
</procedure> </procedure>
</sect2> </sect2>
@ -996,16 +879,16 @@ Later stylesheets seem to not need this adjustment - thomas 2001-11-29
<para> <para>
Several files are distributed as plain text, for reading during Several files are distributed as plain text, for reading during
the installation process. The <filename>INSTALL</filename> file the installation process. The <filename>INSTALL</filename> file
corresponds to the chapter in the <citetitle>Administrator's corresponds to <xref linkend="installation">, with some minor
Guide</citetitle>, with some minor changes to account for the changes to account for the different context. To recreate the
different context. To recreate the file, change to the directory file, change to the directory <filename>doc/src/sgml</filename>
<filename>doc/src/sgml</filename> and enter <userinput>gmake and enter <userinput>gmake INSTALL</userinput>. This will create
INSTALL</userinput>. This will create a file a file <filename>INSTALL.html</filename> that can be saved as text
<filename>INSTALL.html</filename> that can be saved as text with with <productname>Netscape Navigator</productname> and put into
<productname>Netscape Navigator</productname> and put into the the place of the existing file.
place of the existing file. <productname>Netscape</productname> <productname>Netscape</productname> seems to offer the best
seems to offer the best quality for <acronym>HTML</acronym> to quality for <acronym>HTML</acronym> to text conversions (over
text conversions (over <application>lynx</application> and <application>lynx</application> and
<application>w3m</application>). <application>w3m</application>).
</para> </para>
@ -1015,96 +898,24 @@ Later stylesheets seem to not need this adjustment - thomas 2001-11-29
file <filename>src/test/regress/README</filename> the command is file <filename>src/test/regress/README</filename> the command is
<userinput>gmake regress_README</userinput>. <userinput>gmake regress_README</userinput>.
</para> </para>
</sect2>
<!-- <sect2>
* This is how you can create text files via RTF and ApplixWare, <title>Syntax Check</title>
* for historical reference.
<procedure>
<title>Plain Text Generation</title>
<para>
Both <filename>INSTALL</filename> and
<filename>HISTORY</filename> are generated from existing
<acronym>SGML</acronym> sources. They are extracted from the same
intermediate <acronym>RTF</acronym> file.
</para>
<step performance="required">
<para>
Generate <acronym>RTF</acronym> by typing:
<programlisting>
% cd doc/src/sgml
% make installation.rtf
</programlisting>
</para>
</step>
<step performance="required">
<para>
Import <filename>installation.rtf</filename> into
<productname>Applix Words</productname>.
</para>
</step>
<step performance="required">
<para>
Set the page width and margins.
</para>
<substeps>
<step performance="required">
<para>
Adjust the page width in File.PageSetup to 10 inches.
</para>
</step>
<step performance="required">
<para>
Select all text.
Adjust the right margin using the ruler to 9.5 inches. This
will give a maximum column width of 79 characters, within the
80 columns upper limit goal.
</para>
</step>
</substeps>
</step>
<step performance="required">
<para>
Lop off the parts of the document that are not needed.
</para>
<para>
For <filename>INSTALL</filename>, remove all release notes from
the end of the text, except for those from the current release.
For <filename>HISTORY</filename>, remove all text up to the
release notes, preserving and modifying the title and ToC.
</para>
</step>
<step performance="required">
<para>
Export the result as <literal>ASCII Layout</literal>.
</para>
</step>
<step performance="required">
<para>
Using emacs or vi, clean up the tabular information in
<filename>INSTALL</filename>. Remove the <literal>mailto</literal>
<acronym>URLs</acronym> for the porting contributors to shrink
the column heights.
</para>
</step>
</procedure>
-->
<para>
Building the documentation can take very long. But there is a
method to just check the correct syntax of the documentation
files, which only takes a few seconds:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake check</userinput>
</screen>
</para>
</sect2> </sect2>
</sect1> </sect1>
<sect1 id="doc-sources"> <sect1 id="docguide-authoring">
<title>Documentation Authoring</title> <title>Documentation Authoring</title>
<para> <para>
@ -1222,7 +1033,7 @@ End:
the first line look like this: the first line look like this:
<programlisting> <programlisting>
&lt;!doctype appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN"&gt; &lt;!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN"&gt;
</programlisting> </programlisting>
This means that anything and everything that reads This means that anything and everything that reads
@ -1255,7 +1066,7 @@ End:
</sect1> </sect1>
<sect1 id="doc-style"> <sect1 id="docguide-style">
<title>Style Guide</title> <title>Style Guide</title>
<sect2> <sect2>