Permalink
Browse files

- Makefile: added support for howtos

- 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...
1 parent 3669160 commit 7b35729b30a8f5ff73896ac5d66b497a4534079a @docelic docelic committed Aug 9, 2004
Showing with 266 additions and 77 deletions.
  1. +6 −3 Makefile
  2. +9 −9 README
  3. +18 −7 TODO
  4. +1 −1 docbook/docbookxi.dtd
  5. +36 −15 docbook/xmldocs.css
  6. +6 −6 guides/iccattut.xml
  7. +97 −0 howtos/custom-sendmail-routine.xml
  8. +57 −0 howtos/howtos.xml
  9. +7 −7 refs/init_page/example
  10. +29 −29 refs/post_page/example
View
@@ -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 \
@@ -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
View
@@ -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
@@ -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
@@ -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
View
@@ -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>
@@ -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>">
View
@@ -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;
@@ -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;
@@ -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;
@@ -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;
}
@@ -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;
@@ -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;
@@ -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%;
@@ -243,7 +260,7 @@ a { text-decoration: none; }
}
.filename {
- background-color: #cee7F6;
+ background-color: #cee7f6;
padding: 1px 1px 1px 1px;
border: dashed 1px white;
}
@@ -268,3 +285,7 @@ a { text-decoration: none; }
border: dashed 1px white;
}
+a {
+ color: #208cbd;
+}
+
View
@@ -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>
@@ -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.
@@ -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>
@@ -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.
@@ -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>
+
Oops, something went wrong. Retry.

0 comments on commit 7b35729

Please sign in to comment.