Permalink
Browse files

- guides/xmldocs.xml: guide about writing XMLDOCS (in progress)

- docbbok/*.xml and Makefile: added new documents to sitemap and build
- guides/*.xml: work on guides, reorganizing faq, adding stuff to optimization
- refs/*: some number of 1-line fixes to reduce number of build warnings
- glossary/*: placeholders
- some more docs to bin/* scripts and README
  • Loading branch information...
docelic committed Oct 20, 2005
1 parent dee3e64 commit 3139e04b365367932e5677e173004e03fbdc7e6e
View
@@ -13,7 +13,7 @@ IC_VERSIONS = 4.6.0 4.8.0 5.0.0 5.2.0 cvs-head
#############################################################
# Base definitions
SYMBOL_TYPES= pragmas vars tags confs filters orderchecks
-GUIDES = iccattut programming-style upgrade faq index optimization search
+GUIDES = iccattut programming-style upgrade faq index optimization search xmldocs
HOWTOS = howtos
GLOSSARY = glossary
ALL_DOCS = $(GLOSSARY) $(HOWTOS) $(GUIDES) $(SYMBOL_TYPES)
View
5 README
@@ -69,8 +69,9 @@ must be available:
- docbook-xsl
- xsltproc
- exuberant-ctags (to be)
- - db2latex-xsl
- - tetex-extra (and actually, packages it depends on)
+ - db2latex-xsl
+ - tetex-extra (and actually, packages it depends on)
+ - XML::Twig Perl module (if you want to call bin/refs-autogen --validate)
If running on Red Hat and not Debian GNU, apply this patch:
http://icdevgroup.org/~docelic/xmldocs-rh.diff . It allows you to get
View
@@ -66,14 +66,16 @@ unless ( GetOptions (
"skip-invalid|s" => \$skip_invalid,
)) { die "Error parsing options\n" }
-# Determine which stuff to output
+# Determine which stuff to output (only lists of symbols, or the real
+# XMLs files, or both unless --output is specified).
my ( $output_list, $output_xml ) = (1,1);
if (!$output_both and $output_spec) {
$output_spec =~ /\.?list$/ and ($output_list,$output_xml) = (1,0) or
$output_spec =~ /\.?xml$/ and ($output_list,$output_xml) = (0,1) or
die "Unknown output combination '$output_spec'\n";
}
+# Help find XML irregularities in documentation blocks
if ($validate) {
require XML::Twig;
}
@@ -168,10 +170,10 @@ my %preamble = (
"please see the &glos-variable; glossary entry.",
);
-my @paths = @ARGV; # Versions requested
+my @paths = @ARGV; # Versions for which documentation build is requested
my $path; # Current path, used in loop for each version requested
-my $dumppath; # Path to cache dump file
-my $dumpdir;
+my $dumppath; # Directory containing cache dump file (corresponding to $path)
+my $dumpdir; # Full path to current version's .cache.bin
load_templates();
@@ -182,14 +184,18 @@ opendir DIR, "refs" or die "Can't opendir refs/ ($!)\n";
@set_unused = readdir DIR; @set_unused = grep {!/^\.|^CVS$/} @set_unused;
closedir DIR;
+# We will make this file contain autogenerated entities that point to
+# CVS. For example, &cvsfile-README; will point to icdevgroup/..viewcvs../README
open FILE_ENTITIES, "> $fileentitiespath" or
die "Can't open '$fileentitiespath' ($!)\n";
+
+### The main part of the script begins.
while ( $path = shift @paths) { # Now, for each IC version specified
- $dumppath = $path;
- $i{ver} = $dumppath;
- $dumpdir = "$dumppath/";
- $dumppath .= "/.cache.bin";
+ $dumppath = $path; # say, "5.2.0"
+ $i{ver} = $dumppath; # Version number for internal use
+ $dumpdir = "$dumppath/"; # "5.2.0/"
+ $dumppath .= "/.cache.bin"; # "5.2.0/.cache.bin"
# Load %hash with the cache for particular version (replaces previous one).
# (which is OK since the data was extraced and we need previous cache
@@ -209,9 +215,9 @@ while ( $path = shift @paths) { # Now, for each IC version specified
#
# However, entities for last version will, in addition to above,
# get a default entity (like &cvsfile-README;) where no version is specified
- # in the entity, and it will point to some particular file in CVS-HEAD.
+ # in the entity, and it will point to file in CVS-HEAD.
- # First derive IC series_ (in format X_Y) and series (in format X.Y),
+ # First derive IC series_ (in format X_Y) and series (in format X.Y) tags,
# and cvs tag for non-cvs-head. (If we're in cvs-head, we don't make cvs tag
# since cvs-head has no special tag).
unless ( $i{ver} eq 'cvs-head' ) {
@@ -223,6 +229,8 @@ while ( $path = shift @paths) { # Now, for each IC version specified
$i{series} = '';
$i{cvstag} = '';
}
+
+
# Now load in list of files for which to generate entities.
# The list is already prepared for us by bin/stattree (a MANIFEST file,
# basically).
@@ -264,9 +272,10 @@ while ( $path = shift @paths) { # Now, for each IC version specified
$MANIFEST[$i] . qq{</ulink>"} . ">\n";
}
}
- # File entities dumped....
- #########################################################################
+ # File entities dumped.... Job done.
+
+ #########################################################################
View
@@ -12,6 +12,7 @@
<!ENTITY ICDL "<ulink url='http://www.icdevgroup.org/i/dev/download.html'>download</ulink>">
<!ENTITY ICCVS "<ulink url='http://www.icdevgroup.org/i/dev/cvs.html'>CVS</ulink>">
<!ENTITY APACHE "<ulink url='http://www.apache.org/'>Apache</ulink>">
+<!ENTITY MATHOPD "<ulink url='http://www.mathopd.org/'>Mathopd</ulink>">
<!ENTITY W3 "<ulink url='http://www.w3c.org/'>W3C</ulink>">
<!ENTITY W3C "<ulink url='http://www.w3c.org/'>W3C</ulink>">
<!ENTITY PERL "<ulink url='http://www.perl.org/'>Perl</ulink>">
@@ -23,6 +24,8 @@
<!ENTITY GDBM "<ulink url='http://www.delorie.com/gnu/docs/gdbm/'>GNU DBM</ulink>">
<!ENTITY NFS "<ulink url='http://nfs.sourceforge.net/'>NFS</ulink>">
<!ENTITY IMAGEMAGICK "<ulink url='http://www.imagemagick.org/'>ImageMagick</ulink>">
+<!ENTITY DOCBOOK "<ulink url='http://www.docbook.org/'>DocBook</ulink>">
+<!ENTITY ECHO "<ulink url='http://www.echo-inc.com/'>ECHO</ulink>">
View
No changes.
View
No changes.
View
No changes.
View
@@ -59,68 +59,26 @@
<qandaset>
+<qandadiv><title>Interchange Installation</title>
-<qandadiv><title>How does Interchange work</title>
-
-<qandaentry>
+<qandaentry id="install-howto">
<question><para>
-Where are the pages?
+How do I install Interchange?
</para></question>
<answer><para>
-&IC; pages are not kept in normal HTML space. Look in the catalog subdirectory pages. The pages are always filtered through the &IC; daemon before being delivered.
-</para>
-</answer></qandaentry>
-
-<qandaentry>
-<question><para>
-Where are the images?
-</para></question>
-<answer><para>
-&IC; is a &glos-CGI;; program, and if relative image paths were used, erroneous
-&glos-img; output like the following would have occured:
-
-<programlisting><![CDATA[
-<img src="/cgi-bin/simple/../whatever.jpg">
-]]></programlisting>
-
-For that reason, by default, &IC; uses &conf-ImageDir; or
-&conf-ImageDirSecure; for a prefix used to rewrite image URLs.
-In the demo, image
-specs that have no absolute path information are prefixed with
-<literal>/simple/images/</literal>.
+&ICDEVGROUP; distributes &IC; in the basic format of &glos-tarball;s.
+To install &IC; this way, obtain the tarball from the &ICDL; page
+and read file &cvsfile-README;.
</para><para>
-In an &IC; page, this tag:
-
-<programlisting><![CDATA[
-<img src="ordernow.gif">
-]]></programlisting>
-
-will become this:
-
-<programlisting><![CDATA[
-<img src="/simple/images/ordernow.gif">
-]]></programlisting>
-
-This tag:
-
-<programlisting><![CDATA[
-<img src="items/00-0011.jpg">
-]]></programlisting>
-
-will become this:
-
-<programlisting><![CDATA[
-<img src="/simple/images/items/00-0011.jpg">
-]]></programlisting>
-
-Absolute image paths are not affected. An image such as
-<literal>/other/images/whatever.gif</literal> will not be changed.
+Besides tarballs, there are also "precompiled" packages available
+for specific platforms. For &DEBGNU;, see file &cvsfile-README.debian;.
+For &RH; and derivatives, see file &cvsfile-README.rpm-dist;.
+</para><para>
+Finally, you can install &IC; directly out of CVS to get a copy
+of the latest code. To do so, see file &cvsfile-README.cvs;.
</para>
-</answer></qandaentry>
-
-</qandadiv>
-
-<qandadiv><title>Installation</title>
+</answer>
+</qandaentry>
<qandaentry>
<question><para>
@@ -200,8 +158,8 @@ user has a &IC; catalogs directory <filename>/home/user/catalogs</filename>).
</para><para>
The best way to set permissions on a multi-user system is to make all
-files group readable and writable (<literal>660</literal> or
-<literal>664</literal> &glos-mode;). If you have a
+files group readable and writable (&glos-mode; <literal>660</literal> or
+<literal>664</literal>). If you have a
system setup that places each user in their own group, make
<systemitem class='username'>interch</systemitem> a member of each user's
group and set ownership and permissions with:
@@ -545,6 +503,67 @@ If, for some reason, you can't use the distribution media,
</answer></qandaentry>
</qandadiv>
+<qandadiv><title>How does Interchange work</title>
+
+<qandaentry>
+<question><para>
+Where are the pages?
+</para></question>
+<answer><para>
+&IC; pages are not kept in normal HTML space. Look in the catalog subdirectory pages. The pages are always filtered through the &IC; daemon before being delivered.
+</para>
+</answer></qandaentry>
+
+<qandaentry>
+<question><para>
+Where are the images?
+</para></question>
+<answer><para>
+&IC; is a &glos-CGI;; program, and if relative image paths were used, erroneous
+&glos-img; output like the following would have occured:
+
+<programlisting><![CDATA[
+<img src="/cgi-bin/simple/../whatever.jpg">
+]]></programlisting>
+
+For that reason, by default, &IC; uses &conf-ImageDir; or
+&conf-ImageDirSecure; for a prefix used to rewrite image URLs.
+In the demo, image
+specs that have no absolute path information are prefixed with
+<literal>/simple/images/</literal>.
+</para><para>
+In an &IC; page, this tag:
+
+<programlisting><![CDATA[
+<img src="ordernow.gif">
+]]></programlisting>
+
+will become this:
+
+<programlisting><![CDATA[
+<img src="/simple/images/ordernow.gif">
+]]></programlisting>
+
+This tag:
+
+<programlisting><![CDATA[
+<img src="items/00-0011.jpg">
+]]></programlisting>
+
+will become this:
+
+<programlisting><![CDATA[
+<img src="/simple/images/items/00-0011.jpg">
+]]></programlisting>
+
+Absolute image paths are not affected. An image such as
+<literal>/other/images/whatever.gif</literal> will not be changed.
+</para>
+</answer></qandaentry>
+
+</qandadiv>
+
+
<qandadiv><title>SSL problems</title>
View
@@ -126,19 +126,8 @@
<sect2 id='InterchangeandtheStandardDemoCatalogInstallation'>
<title>Interchange and the Standard Demo Catalog Installation</title>
<para>
- The easiest way to prepare the environment (that is, install Interchange and the standard catalog) is to use installable packages prepared for you in the <firstterm>RPM</firstterm> (&RH;, SuSE or Mandrake Linux systems) or <firstterm>DEB</firstterm> (&DEBGNU;) formats. On Debian systems, run <userinput>apt-get install interchange interchange-ui interchange-cat-&std-catalog; interchange-doc</userinput>. For other formats, see the Interchange &ICDL; page.
- </para>
- <!--
- <note><para>
- Interchange version 5.2.0 is the last one to ship with the <emphasis>Foundation</emphasis> demo catalog. If you suspect you only have the old packages, install interchange-cat-foundation instead of interchange-cat-standard.
- </para></note>
- -->
- <para>
- You can also get Interchange by downloading and unpacking the basic Interchange tarball or checking out a copy of the &ICCVS; repository, and performing manual installation yourself. These installations can be done either as a regular user, or as root installing for a special Interchange user, but are out of scope of this tutorial.
- </para> <para>
- During the Debian package installation, you will be asked to select the Interchange username. To eliminate basic security issues, the Interchange daemon will not run as root, and it should not run as the web server user either. Therefore, a new system account to run the Interchange daemon will be created (<systemitem class='username'>interchange</systemitem> by default). With RPM packages, the default Interchange username will be <systemitem class='username'>interch</systemitem><footnote><para>There are a lot of packaging differences between Debian and Red Hat packages. Some are mandated by system policies (which is especially the case with Debian GNU), while others (such as the default username) reflect preferences of the package maintainers and the corresponding user groups.</para></footnote>.
- </para> <para>
- You must access the demo catalog to verify that your Interchange installation was successful. The interchange-cat-&std-catalog; package, containing catalog "&std-catalog;", was supposed to install itself and register with Interchange by modifying the main <filename moreinfo='refentry'>interchange.cfg</filename> config file (or some other file, such as <filename>/etc/interchange/catalogs.cfg</filename>, which logically puts all catalog definitions in a separate file and is read by <filename>interchange.cfg</filename>). The catalog should have also placed the <firstterm>link program</firstterm> in your <filename class='directory'>cgi-bin</filename> directory - the link program connects the web server software with the Interchange daemon. The demo catalog should be accessible by visiting the <ulink url="http://localhost/cgi-bin/ic/&std-catalog;/index.html">&Std-catalog;</ulink> (or <ulink url="http://localhost/cgi-bin/ic/&prev-catalog;/index.html">&Prev-catalog;</ulink>) Demo index page on your local host. (This also means you need to have a web server running, such as <application>Apache</application> or <application>mathopd</application>.)
+ For installation instructions, see
+ <olink targetdoc='faq' targetptr='install-howto'/> FAQ entry.
</para>
</sect2>
View
@@ -280,7 +280,7 @@ Benchmark loop-param list: [benchmark start=1]
<para>
For repetitive routines, you can achieve a considerable savings
in CPU by pre-compiling your embedded &PERL; code. The precompilation
- can occur either once at &conf-catalog; configuration time,
+ can occur either once at &glos-catalog; configuration time,
or once at time of list execution.
</para><para>
When you compile routines at the time of the list execution
Oops, something went wrong.

0 comments on commit 3139e04

Please sign in to comment.