diff --git a/Makefile b/Makefile index dee684f..deb53a1 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/README b/README index 43afbcf..0428afc 100644 --- a/README +++ b/README @@ -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 diff --git a/TODO b/TODO index 7923e05..d8020d7 100644 --- a/TODO +++ b/TODO @@ -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/ with all the documentation for a symbol instead of refs//. +- 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. + +William Safire + +Knowing how things work is the basis for appreciation, and is +thus a source of civilized delight. + + diff --git a/docbook/docbookxi.dtd b/docbook/docbookxi.dtd index e6f5e2a..ecf0814 100644 --- a/docbook/docbookxi.dtd +++ b/docbook/docbookxi.dtd @@ -5,7 +5,7 @@ Red Hat"> Debian"> Debian GNU"> -tarball"> +download"> CVS"> Apache"> diff --git a/docbook/xmldocs.css b/docbook/xmldocs.css index 98c7b3b..49cfeb4 100644 --- a/docbook/xmldocs.css +++ b/docbook/xmldocs.css @@ -17,7 +17,7 @@ a { text-decoration: none; } .reference .refsect1

/ */ -.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 / / . / /

*/ -.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; +} + diff --git a/guides/iccattut.xml b/guides/iccattut.xml index d667d19..ff9bd53 100644 --- a/guides/iccattut.xml +++ b/guides/iccattut.xml @@ -112,12 +112,12 @@ Interchange and the Standard Demo Catalog Installation - The easiest way to prepare the environment (that is, install Interchange and the standard catalog) is to use installable packages prepared for you in RPM (&RH;, SuSE or Mandrake Linux systems) or DEB (&DEBGNU;) formats. Try running apt-get install interchange interchange-ui interchange-cat-standard interchange-doc 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 RPM (&RH;, SuSE or Mandrake Linux systems) or DEB (&DEBGNU;) formats. On Debian systems, run apt-get install interchange interchange-ui interchange-cat-standard interchange-doc. For other formats, see the Interchange &ICDL; page. Interchange version 5.2.0 is the last one to ship with the Foundation demo catalog. If you suspect you only have the old packages, install interchange-cat-foundation instead of interchange-cat-standard. - 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. 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). @@ -201,8 +201,8 @@ You need to locate the existing link program (found in the cgi-bin directory) and copy it to a new name, making sure the permissions stay intact. Run cd /usr/lib/cgi-bin/ic; cp -p vlink tutorial. If everything is working correctly, typing ls -l /usr/lib/cgi-bin/ic/ should describe your files roughly like this: --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 The link program enables communication with the Interchange daemon. @@ -277,7 +277,7 @@ ErrorFile /var/log/interchange/error.log 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. - If you need more entries for the sample products database, you can use the dbgen 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 /usr/share/dict/words file (in Debian, it's provided by the wenglish package), and then run perl dbgen -c 10 -r /usr/share/dict/words > products/products.txt. 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 dbgen 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 /usr/share/dict/words file (in Debian, it's provided by the wenglish package), and then run perl dbgen -c 10 -r /usr/share/dict/words > products/products.txt. See the script source for available options and the complete usage syntax. Now that we have the majority of base files ready, we just need to create the HTML page templates. @@ -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.) - 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 ls 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 ls command. 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. diff --git a/howtos/custom-sendmail-routine.xml b/howtos/custom-sendmail-routine.xml new file mode 100644 index 0000000..b2a4c81 --- /dev/null +++ b/howtos/custom-sendmail-routine.xml @@ -0,0 +1,97 @@ + + + + Custom Sendmail Routine + customsendmail + + + custom + send + mail + routine + delay + + + + + Mike + Heins + + mheins@perusion.net + + + + + + + + + Introduction + + Someone was wondering how to optimize the order processing on a busy site. It was observed that about once in every ten times, the etc/mail_receipt takes a few extra seconds before it's mailed out. + + + The delay occured because in the code used, the 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: + + + +| ] + +... email contents ... + +[/email] +]]> + + + + + Solution + + To eliminate this "delay", you could use a custom script that accepts the message on standard input (STDIN), and then calls Sendmail in the background. + + Save the script with the following contents to /usr/local/bin/sendmail-bg: + + + +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" } + +]]> + + + + And of course, don't forget to add/modify the directive: + + + +SendMailProgram /usr/local/bin/sendmail-bg + + + + + + diff --git a/howtos/howtos.xml b/howtos/howtos.xml new file mode 100644 index 0000000..57bb544 --- /dev/null +++ b/howtos/howtos.xml @@ -0,0 +1,57 @@ + + + +]> + + + + + + Interchange HOWTOs collection + howtos + + + + + + Copyright (C) 2004, Interchange Development Group + + + 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. + + + 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. + + + + + + + +&custom-sendmail-routine; + + diff --git a/refs/init_page/example b/refs/init_page/example index 0f9e4f7..7475142 100644 --- a/refs/init_page/example +++ b/refs/init_page/example @@ -16,11 +16,11 @@ The following is needed in catalog.cfg: Pragma init_page=wrap_page Sub <} and $Scratch->{page_title} = $1; - $$pref = <} and $Scratch->{page_title} = $1; + $$pref = < $$pref @@ -28,8 +28,8 @@ $$pref \@_MYTEMPLATE_BOTTOM_\@ EOF - return; - } + return; + } EOS ]]> diff --git a/refs/post_page/example b/refs/post_page/example index 4a2d085..03b39b7 100644 --- a/refs/post_page/example +++ b/refs/post_page/example @@ -16,37 +16,37 @@ Pragma post_page=relative_urls ### Take hrefs like and make relative to current ### directory Sub <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{( - ( - ]+?\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{( + ( + ]+?\s+)? + href \s*=\s* + ) + (["']) ([^\s"'>]+) \3 + )} + { + $sub->($1,$2,$4) + }gsiex; - return; - } + return; + } EOR ]]>