[docs] xmldocs - docelic modified 10 files
docs at icdevgroup.org
docs at icdevgroup.org
Mon Aug 9 11:53:58 EDT 2004
User: docelic
Date: 2004-08-09 15:53:57 GMT
Modified: . Makefile README TODO
Modified: docbook docbookxi.dtd xmldocs.css
Modified: guides iccattut.xml
Modified: refs/init_page example
Modified: refs/post_page example
Added: howtos custom-sendmail-routine.xml howtos.xml
Log:
- 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...
Revision Changes Path
1.13 +6 -3 xmldocs/Makefile
rev 1.13, prev_rev 1.12
Index: Makefile
===================================================================
RCS file: /var/cvs/xmldocs/Makefile,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- Makefile 8 Aug 2004 20:05:21 -0000 1.12
+++ Makefile 9 Aug 2004 15:53:57 -0000 1.13
@@ -16,14 +16,14 @@
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 @@
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
1.7 +9 -9 xmldocs/README
rev 1.7, prev_rev 1.6
Index: README
===================================================================
RCS file: /var/cvs/xmldocs/README,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- README 6 Aug 2004 15:57:27 -0000 1.6
+++ README 9 Aug 2004 15:53:57 -0000 1.7
@@ -19,13 +19,13 @@
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 @@
- 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 @@
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
1.8 +18 -7 xmldocs/TODO
rev 1.8, prev_rev 1.7
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- TODO 8 Aug 2004 21:04:24 -0000 1.7
+++ TODO 9 Aug 2004 15:53:57 -0000 1.8
@@ -3,28 +3,39 @@
- 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>
1.5 +1 -1 xmldocs/docbook/docbookxi.dtd
rev 1.5, prev_rev 1.4
Index: docbookxi.dtd
===================================================================
RCS file: /var/cvs/xmldocs/docbook/docbookxi.dtd,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- docbookxi.dtd 8 Aug 2004 20:05:22 -0000 1.4
+++ docbookxi.dtd 9 Aug 2004 15:53:57 -0000 1.5
@@ -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>">
1.9 +36 -15 xmldocs/docbook/xmldocs.css
rev 1.9, prev_rev 1.8
Index: xmldocs.css
===================================================================
RCS file: /var/cvs/xmldocs/docbook/xmldocs.css,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- xmldocs.css 8 Aug 2004 20:05:22 -0000 1.8
+++ xmldocs.css 9 Aug 2004 15:53:57 -0000 1.9
@@ -17,7 +17,7 @@
.reference .refsect1 <h2/> /
*/
-.reference .titlepage h1, .article .titlepage h1 {
+.titlepage h1 {
background-color: #208cbd; /* #6CA6C8; */
margin: 0;
margin-bottom: 20px;
@@ -30,7 +30,15 @@
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 @@
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 @@
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 @@
.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 @@
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 @@
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 @@
}
.filename {
- background-color: #cee7F6;
+ background-color: #cee7f6;
padding: 1px 1px 1px 1px;
border: dashed 1px white;
}
@@ -266,5 +283,9 @@
background-color: #d2aa55;
padding: 1px 1px 1px 1px;
border: dashed 1px white;
+}
+
+a {
+ color: #208cbd;
}
1.10 +6 -6 xmldocs/guides/iccattut.xml
rev 1.10, prev_rev 1.9
Index: iccattut.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/iccattut.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- iccattut.xml 8 Aug 2004 21:21:45 -0000 1.9
+++ iccattut.xml 9 Aug 2004 15:53:57 -0000 1.10
@@ -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 @@
</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 @@
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.
1.1 xmldocs/howtos/custom-sendmail-routine.xml
rev 1.1, prev_rev 1.0
Index: custom-sendmail-routine.xml
===================================================================
<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 at 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>
1.1 xmldocs/howtos/howtos.xml
rev 1.1, prev_rev 1.0
Index: howtos.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook-Interchange XML V4.2//EN"
"../docbook/docbookxi.dtd" [
<!ENTITY custom-sendmail-routine SYSTEM "custom-sendmail-routine.xml">
]>
<book id="howtos">
<bookinfo>
<title>Interchange HOWTOs collection</title>
<titleabbrev>howtos</titleabbrev>
<!--
<author>
<firstname></firstname>
<surname></surname>
<affiliation>
<address>
<email></email>
</address>
</affiliation>
</author>
-->
<legalnotice>
<para>
Copyright (C) 2004, Interchange Development Group
</para>
<para>
This documentation is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
</para>
<para>
It is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
</para>
</legalnotice>
</bookinfo>
<!--
<preface>
<title>Foreword</title>
<para></para>
</preface>
-->
&custom-sendmail-routine;
</book>
1.3 +7 -7 xmldocs/refs/init_page/example
rev 1.3, prev_rev 1.2
Index: example
===================================================================
RCS file: /var/cvs/xmldocs/refs/init_page/example,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- example 8 Aug 2004 20:05:24 -0000 1.2
+++ example 9 Aug 2004 15:53:57 -0000 1.3
@@ -16,11 +16,11 @@
Pragma init_page=wrap_page
Sub <<EOS
- sub wrap_page {
- my $pref = shift;
- return if $$pref =~ m{\@_[A-Z]\w+_\@};
- $$pref =~ m{<!--+ title:\s*(.*?)\s+-->} and $Scratch->{page_title} = $1;
- $$pref = <<EOF;
+ sub wrap_page {
+ my $pref = shift;
+ return if $$pref =~ m{\@_[A-Z]\w+_\@};
+ $$pref =~ m{<!--+ title:\s*(.*?)\s+-->} and $Scratch->{page_title} = $1;
+ $$pref = <<EOF;
\@_MYTEMPLATE_TOP_\@
<!--BEGIN CONTENT -->
$$pref
@@ -28,8 +28,8 @@
\@_MYTEMPLATE_BOTTOM_\@
EOF
- return;
- }
+ return;
+ }
EOS
]]></programlisting>
</example>
1.2 +29 -29 xmldocs/refs/post_page/example
rev 1.2, prev_rev 1.1
Index: example
===================================================================
RCS file: /var/cvs/xmldocs/refs/post_page/example,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- example 21 Jul 2004 20:24:52 -0000 1.1
+++ example 9 Aug 2004 15:53:57 -0000 1.2
@@ -16,37 +16,37 @@
### Take hrefs like <A HREF="about.html"> and make relative to current
### directory
Sub <<EOR
- sub relative_urls {
- my $page = shift;
- my @dirs = split "/", $Tag->var('MV_PAGE', 1);
- pop @dirs;
- my $basedir = join "/", @dirs;
- $basedir ||= '';
- $basedir .= '/' if $basedir;
+ sub relative_urls {
+ my $page = shift;
+ my @dirs = split "/", $Tag->var('MV_PAGE', 1);
+ pop @dirs;
+ my $basedir = join "/", @dirs;
+ $basedir ||= '';
+ $basedir .= '/' if $basedir;
- my $sub = sub {
- my ($entire, $pre, $url) = @_;
- return $entire if $url =~ /^\w+:/;
- my($page, $form) = split /\?/, $url, 2;
- my $u = $Tag->area({
- href => "$basedir$page",
- form => $form,
- });
- return qq{$pre"$u"};
- };
- $$page =~ s{(
- (
- <a \s+ (?:[^>]+?\s+)?
- href \s*=\s*
- )
- (["']) ([^\s"'>]+) \3
- )}
- {
- $sub->($1,$2,$4)
- }gsiex;
+ my $sub = sub {
+ my ($entire, $pre, $url) = @_;
+ return $entire if $url =~ /^\w+:/;
+ my($page, $form) = split /\?/, $url, 2;
+ my $u = $Tag->area({
+ href => "$basedir$page",
+ form => $form,
+ });
+ return qq{$pre"$u"};
+ };
+ $$page =~ s{(
+ (
+ <a \s+ (?:[^>]+?\s+)?
+ href \s*=\s*
+ )
+ (["']) ([^\s"'>]+) \3
+ )}
+ {
+ $sub->($1,$2,$4)
+ }gsiex;
- return;
- }
+ return;
+ }
EOR
]]></programlisting>
More information about the docs
mailing list