Skip to content

Commit

Permalink
- Makefile: added support for howtos
Browse files Browse the repository at this point in the history
- README: replaced unintended tabs with spaces
- TODO: items
- docbook/docbookxi.dtd: ICTBALL renamed to ICDL
- docbook/xmldocs.css: quite a lot of tuning
- guides/iccattut.xml: little wording and XML fixes
- refs/*/example*: replacing tabs with spaces (XML wants that)
- other...
  • Loading branch information
docelic committed Aug 9, 2004
1 parent 3669160 commit 7b35729
Show file tree
Hide file tree
Showing 10 changed files with 266 additions and 77 deletions.
9 changes: 6 additions & 3 deletions Makefile
Expand Up @@ -16,14 +16,14 @@ XMLTO = xmlto
XMLTO_FLAGS = --skip-validation
IC_VERSIONS = 4.6.0 4.8.0 5.0.0 5.2.0 cvs-head

VPATH = guides refs
VPATH = guides refs howtos
.SILENT:

############## No need to modify below ##############

.PHONY: all guides refs %.man
.PHONY: all guides refs howtos %.man

all: tmp/refs-autogen tmp/olinkdbs guides refs
all: tmp/refs-autogen tmp/olinkdbs guides refs howtos
echo all done

guides: $(OUTPUT)/images $(OUTPUT)/files \
Expand All @@ -34,6 +34,9 @@ refs: $(OUTPUT)/images $(OUTPUT)/files
make $(OUTPUT)/pragmas.html $(OUTPUT)/pragmas $(OUTPUT)/pragmas.man
make $(OUTPUT)/globvars.html $(OUTPUT)/globvars $(OUTPUT)/globvars.man

howtos: howtos/howtos.xml howtos/*.xml
make $(OUTPUT)/howtos.html
make $(OUTPUT)/howtos

#
# All documents
Expand Down
18 changes: 9 additions & 9 deletions README
Expand Up @@ -19,13 +19,13 @@ targets would include:
make guides
make refs

make OUTPUT/iccattut.html
make OUTPUT/iccattut
make OUTPUT/iccattut.man
make OUTPUT/iccattut.html
make OUTPUT/iccattut
make OUTPUT/iccattut.man

make OUTPUT/xmldocs.css
make tmp/refs-autogen
make tmp/olinkdbs
make tmp/refs-autogen
make tmp/olinkdbs


PREREQUISITES
Expand All @@ -39,8 +39,8 @@ must be available:
- docbook-xsl
- xsltproc
- xmlto
- exuberant-ctags
- passivetex (for FO output - ps, pdf, ...)
- exuberant-ctags
- passivetex (for FO output - ps, pdf, ...) (not used yet)


FINAL OUTPUT
Expand Down Expand Up @@ -161,8 +161,8 @@ DEVELOPMENT NOTES
file for each section.
To supply more examples, you could keep them in an informal structure
like this:
refs/post_page/example
refs/post_page/example2
refs/post_page/example
refs/post_page/example2
refs/post_page/example-relative_pages
refs/post_page/example:used-often
refs/post_page/example.something
Expand Down
25 changes: 18 additions & 7 deletions TODO
Expand Up @@ -3,28 +3,39 @@ DOCUMENTATION SYSTEM:
- Make docbook/symbol-type-skel/* contents of a glossary, and display a
glossary entry instead of those files.
- For tags documentation, have a field if it's a container or not
- bin/stattree, in format_ctx(), see how many spacings all the lines have
in common, and trim that.

Mid-term:
- Think about adding "online example" (role=html in combination with
a flag that says if html is to be static or for hosting on IC-enabled site)
- for "online" docs, also provide a form where users can add comments or
ask for clarification. (this could be done with either pure IC (forum?), or
XML forms capability)..
- filenames in Source contexts should also be clickable
XML forms capability, or wiki?)..
- in html, make source contexts "rollable" by either using some css
properties or javascript. this is not really needed when you only have
say, 15 lines of context, but it'll come great when you have a copy
of a 300-lines usertag.
say, 15 lines of context, but it'll come great when you have a copy
of a 300-lines usertag. Example for this could be taken directly out of
mwforum demo on mwforum.org

Long-term:
- Support using refs/<filename> with all the documentation for a symbol
instead of refs/<directory>/<files>.
- filenames in Source contexts should also be clickable. this is longterm
because it'll involve perltidy and other stuff I have in mind ...

DOCUMENTATION ITSELF:
- Resolve items from tmp/missing file. (You need to run 'make' in your tree
first, to get that file generated). I did what I could, now the list only
contains items which don't even exist in the old docs, so I can't copy/paste;
someone who is able to write the description/examples from scratch should
do that.
contains items which don't even exist in the old docs, so I can't copy/paste;
someone who is able to write the description/examples from scratch should
do that.


<epigraph>
<attribution>William Safire</attribution>
<para>
Knowing how things work is the basis for appreciation, and is
thus a source of civilized delight.
</para>
</epigraph>
2 changes: 1 addition & 1 deletion docbook/docbookxi.dtd
Expand Up @@ -5,7 +5,7 @@
<!ENTITY RH "<ulink url='http://www.redhat.com'>Red Hat</ulink>">
<!ENTITY DEB "<ulink url='http://www.debian.org'>Debian</ulink>">
<!ENTITY DEBGNU "<ulink url='http://www.debian.org'>Debian GNU</ulink>">
<!ENTITY ICTBALL "<ulink url='http://www.icdevgroup.org/i/dev/download.html'>tarball</ulink>">
<!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>">

Expand Down
51 changes: 36 additions & 15 deletions docbook/xmldocs.css
Expand Up @@ -17,7 +17,7 @@ a { text-decoration: none; }
.reference .refsect1 <h2/> /
*/

.reference .titlepage h1, .article .titlepage h1 {
.titlepage h1 {
background-color: #208cbd; /* #6CA6C8; */
margin: 0;
margin-bottom: 20px;
Expand All @@ -30,7 +30,15 @@ a { text-decoration: none; }
background-repeat: no-repeat; */
}

.reference hr {
/*
Book:
.book .titlepage . . h1.title / / . .legalnotice p / / / / . / hr /
.toc p b / / dl dt .chapter / /
dt .sect1 / /
.chapter .titlepage h1
*/

.reference hr, .book hr {
margin: 0;
padding: 2px 4px 2px 4px;
height: 4px;
Expand All @@ -40,7 +48,7 @@ a { text-decoration: none; }
visibility: hidden;
}

.reference .toc, .article .toc {
.reference .toc, .article .toc, .book .toc {
margin: 0;
margin-bottom: 40px;
border: 1px dashed #cee7f6;
Expand All @@ -55,7 +63,16 @@ a { text-decoration: none; }
color: #FFF;
}

.reference .toc dl, .article .toc dl {
.book .toc p {
margin: 0;
padding: 0;
background-color: #cee7f6;
border-bottom: 1px dashed #fff;
padding: 1px 4px 1px 4px;
/*color: #FFF;*/
}

.toc dl {
padding: 2px 4px 2px 4px;
}

Expand Down Expand Up @@ -112,21 +129,21 @@ a { text-decoration: none; }
.sect2 .titlepage . . h3.title / / . / / <p/>
*/

.article .authorgroup {
.authorgroup {
margin: 0;
margin-bottom: 40px;
border: 1px dashed #cee7F6;
border: 1px dashed #cee7f6;
padding: 2px 4px 8px 4px;
}

.article .abstract {
.abstract {
margin: 0;
margin-bottom: 40px;
border: 1px dashed #cee7F6;
border: 1px dashed #cee7f6;
border-bottom: none;
}

.article .abstract p.title {
.abstract p.title {
margin: 0;
padding: 0;
background-color: #6ca6c8;
Expand All @@ -135,11 +152,11 @@ a { text-decoration: none; }
color: #fff;
}

.article .abstract p {
.abstract p {
padding: 1px 4px 1px 4px;
}

.article .sect1 .titlepage h2.title {
.titlepage h2.title {
margin: 0;
padding: 0;
background-color: #6ca6c8;
Expand All @@ -150,17 +167,17 @@ a { text-decoration: none; }
margin-bottom: 20px;
}

.article .sect2 .titlepage h3.title {
.titlepage h3.title {
margin: 0;
padding: 0;
background-color: #cee7F6;
background-color: #cee7f6;
border: 1px dashed #fff;
padding: 4px 4px 4px 4px;
color: #000;
font-weight: bold;
}

.article .footnotes hr {
.footnotes hr {
margin: 0;
padding: 2px 4px 2px 4px;
width: 100%;
Expand Down Expand Up @@ -243,7 +260,7 @@ a { text-decoration: none; }
}

.filename {
background-color: #cee7F6;
background-color: #cee7f6;
padding: 1px 1px 1px 1px;
border: dashed 1px white;
}
Expand All @@ -268,3 +285,7 @@ a { text-decoration: none; }
border: dashed 1px white;
}

a {
color: #208cbd;
}

12 changes: 6 additions & 6 deletions guides/iccattut.xml
Expand Up @@ -112,12 +112,12 @@
<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 <firstterm>RPM</firstterm> (&RH;, SuSE or Mandrake Linux systems) or <firstterm>DEB</firstterm> (&DEBGNU;) formats. Try running <userinput>apt-get install interchange interchange-ui interchange-cat-standard interchange-doc</userinput> on Debian GNU systems.
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-standard 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 &ICTBALL; 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.
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 RPM or DEB 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 ("interchange" by default).
</para> <para>
Expand Down Expand Up @@ -201,8 +201,8 @@
<para>
You need to locate the existing link program (found in the <filename class='directory'>cgi-bin</filename> directory) and copy it to a new name, making sure the permissions stay intact. Run <userinput>cd /usr/lib/cgi-bin/ic; cp -p vlink tutorial</userinput>. If everything is working correctly, typing <userinput>ls -l /usr/lib/cgi-bin/ic/</userinput> should describe your files roughly like this:
<screen>
-rwsr-xr-x 1 interch interch 7708 Dec 16 22:47 tlink
-rwsr-xr-x 1 interch interch 7708 Dec 16 22:47 tutorial
-rwsr-xr-x 1 interchange interchange 7708 Dec 16 22:47 tlink
-rwsr-xr-x 1 interchange interchange 7708 Dec 16 22:47 tutorial
</screen>
</para> <para>
The link program enables communication with the Interchange daemon.
Expand Down Expand Up @@ -277,7 +277,7 @@ ErrorFile /var/log/interchange/error.log
</para> <para>
You may notice that the columns don't line up in your text editor. This is the nature of tab-delimited files. Do not try to fix these.
</para> <para>
If you need more entries for the sample products database, you can use the <ulink url="files/dbgen">dbgen</ulink> Perl script to automatically create random database files for testing. It's output is much more meaningful if you provide it a list of words to work on (instead of just random characters) so make sure you have the <filename>/usr/share/dict/words</filename> file (in Debian, it's provided by the wenglish package), and then run <userinput>perl dbgen -c 10 -r /usr/share/dict/words > products/products.txt</userinput>. See the script source for available options and the complete usage syntax.
If you need more entries for the sample products database, you can use the <ulink url="files/dbgen">dbgen</ulink> Perl script to automatically create random database files for testing. It's output is much more meaningful if you provide it a list of words to work on (instead of just random characters) so make sure you have the <filename>/usr/share/dict/words</filename> file (in Debian, it's provided by the <literal>wenglish</literal> package), and then run <userinput>perl dbgen -c 10 -r /usr/share/dict/words > products/products.txt</userinput>. See the script source for available options and the complete usage syntax.
</para> <para>
Now that we have the majority of base files ready, we just need to create the HTML page templates.
</para>
Expand Down Expand Up @@ -431,7 +431,7 @@ ErrorFile /var/log/interchange/error.log
Have you created directories with the proper names in the proper locations? (See Appendix A for a full directory and file structure of the tutorial catalog.) <!-- todo link to appendix -->
</para></listitem>
<listitem><para>
Have you misspelled any file names or put them in the wrong directories? Are the files and parent directories readable by the interch user? Double-check with the <command>ls</command> command.
Have you misspelled any file names or put them in the wrong directories? Are the files and parent directories readable by the interchange user? Double-check with the <command>ls</command> command.
</para></listitem>
<listitem><para>
Did you type letters in the proper case? Remember that both Unix and Interchange are case-sensitive, and for the most part you may not switch upper- and lower-case letters.
Expand Down
97 changes: 97 additions & 0 deletions howtos/custom-sendmail-routine.xml
@@ -0,0 +1,97 @@
<chapter id="CustomSendmailRoutine">

<chapterinfo>
<title>Custom Sendmail Routine</title>
<titleabbrev>customsendmail</titleabbrev>

<keywordset>
<keyword>custom</keyword>
<keyword>send</keyword>
<keyword>mail</keyword>
<keyword>routine</keyword>
<keyword>delay</keyword>
</keywordset>

<authorgroup>
<author>
<firstname>Mike</firstname>
<surname>Heins</surname>
<affiliation>
<email>mheins@perusion.net</email>
</affiliation>
</author>
</authorgroup>


</chapterinfo>

<sect1 id='introduction'>
<title>Introduction</title>
<para>
Someone <ulink url="http://www.icdevgroup.org/pipermail/interchange-users/2004-July/039811.html">was wondering</ulink> how to optimize the order processing on a busy site. It was observed that about once in every ten times, the <filename>etc/mail_receipt</filename> takes a few <emphasis>extra</emphasis> seconds before it's mailed out.
</para>
<para>
The delay occured because in the code used, the <option>SendMailProgram</option> ran in foreground so the ordering process "stalled" for a few seconds (or at least that's how the average customer saw it). The critical section was reduced to:
</para>

<screen>
<![CDATA[
[email to="[scratch to_email], __MAIL_RECEIPT_CC__"
subject="__COMPANY__ Order #[value mv_order_number]: [scratch subject_end]"
from=|"__COMPANY__ Order Confirmation" <orders at company.com>| ]
... email contents ...
[/email]
]]>
</screen>
</sect1>

<sect1 id='solution'>
<title>Solution</title>
<para>
To eliminate this "delay", you could use a custom script that accepts the message on standard input (STDIN), and then calls <application>Sendmail</application> in the background.
</para> <para>
Save the script with the following contents to <filename>/usr/local/bin/sendmail-bg</filename>:
</para>

<programlisting>
<![CDATA[
#!/usr/bin/perl
#use strict;
#use warnings;
use File::Temp;
my $basedir = '/tmp/sendmail';
my $sendmail = '/usr/sbin/sendmail -t';
umask 2;
mkdir $basedir unless -d $basedir;
my $tmp = File::Temp->new( DIR => $basedir );
my $tmpnam = $tmp->filename;
open OUT, "> $tmpnam" or die "Cannot create $tmpnam: $!\n";
my $cmdline = join " ", $sendmail, '<', $tmpnam, '&';
while(<>) { print OUT $_; }
close OUT;
system($cmdline);
if($?) { die "Failed to fork sendmail: $!\n" }
]]>
</programlisting>

<para>
And of course, don't forget to add/modify the <option>SendMailProgram</option> directive:
</para>

<programlisting>
SendMailProgram /usr/local/bin/sendmail-bg
</programlisting>

</sect1>

</chapter>

0 comments on commit 7b35729

Please sign in to comment.