[docs] xmldocs - docelic modified 21 files
docs at icdevgroup.org
docs at icdevgroup.org
Wed Jun 15 06:30:14 EDT 2005
User: docelic
Date: 2005-06-15 10:30:14 GMT
Modified: . Makefile README TODO
Modified: bin generic-autogen refs-autogen stattree
Modified: glossary ITL attribute locale
Modified: howtos custom-sendmail-routine daemon-control
Modified: implement-banners log-files
Modified: obtain-and-run-interchange professional-support
Modified: quantity-in-basket validate
Modified: refs MailOrderTo UseModifier
Added: files/attributes attributes.html products.txt
Log:
- Makefile: remove dependence on bin/stattree
- bin/stattree:
- include parse_* function in source context for config directives
- howtos/*: remove <titleabbrev> and some updates
- glossary/*: fixes, updates
- refs/*: fixes, updates
- bin/generic-autogen:
- detect howto/glossary items that have TODO lines, out of band comments or
XML comments
- produce tmp/missing2 a-la tmp/missing from bin/refs-autogen
- bin/refs-autogen:
- detect reference files that have TODO lines, out of band comments or
XML comments
- TODO: finished items, and rearranged priorities
- README: update for note on Red Hat, and tmp/missing* files
Revision Changes Path
1.65 +1 -1 xmldocs/Makefile
rev 1.65, prev_rev 1.64
Index: Makefile
===================================================================
RCS file: /var/cvs/xmldocs/Makefile,v
retrieving revision 1.64
retrieving revision 1.65
diff -u -r1.64 -r1.65
--- Makefile 11 Jun 2005 08:28:59 -0000 1.64
+++ Makefile 15 Jun 2005 10:30:09 -0000 1.65
@@ -214,7 +214,7 @@
#############################################################
# Cache files
cache caches: $(foreach icver,$(IC_VERSIONS),cache/$(icver)/.cache.bin) $T
-cache/%/.cache.bin: sources/% bin/stattree
+cache/%/.cache.bin: sources/%
echo "C $@"
bin/stattree $<
1.17 +17 -1 xmldocs/README
rev 1.17, prev_rev 1.16
Index: README
===================================================================
RCS file: /var/cvs/xmldocs/README,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- README 25 May 2005 22:28:58 -0000 1.16
+++ README 15 Jun 2005 10:30:10 -0000 1.17
@@ -68,6 +68,13 @@
- exuberant-ctags
- passivetex
+If running on Red Hat and not Debian GNU, apply this patch:
+http://icdevgroup.org/~docelic/xmldocs-rh.diff . It allows you to get
+usable results, although it's flaky and Debian GNU is really the preferred
+platform. (I suppose with a better patch, by someone know knows Red Hat
+and its DocBook XML setup, Red Hat would produce completely good results
+too - patches welcome)
+
FINAL OUTPUT
@@ -103,6 +110,13 @@
This can also be OUTPUT<yourprefix>, if you pass e.g.
OUTPUT=-std in a call to make (as shown near the top).
+ tmp/missing[2] - After you build the documentation, there will be a file
+ named tmp/missing autogenerated, and it will contain a list
+ of symbols with all the parts of the documentation they
+ still miss for the item to be considered complete.
+ tmp/missing2 will also be created that will list HOWTO
+ items and glossary entries that need work.
+
DEVELOPMENT NOTES
@@ -274,7 +288,9 @@
** After you build the documentation, there will be a file named
** tmp/missing autogenerated, and it will contain a list of symbols with all
** the parts of the documentation they still miss for the item to be
-** considered complete. Clearing out this list is a priority;
+** considered complete. tmp/missing2 will also be created that will list
+** HOWTO items and glossary entries that need work.
+** Clearing out this list is a priority;
** given that the new system is so convenient and cool, you have no excuse ;-)
1.75 +6 -11 xmldocs/TODO
rev 1.75, prev_rev 1.74
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.74
retrieving revision 1.75
diff -u -r1.74 -r1.75
--- TODO 11 Jun 2005 23:39:25 -0000 1.74
+++ TODO 15 Jun 2005 10:30:10 -0000 1.75
@@ -1,16 +1,5 @@
Outstanding:
=======
-- across glossary entries, insert <section>s
-- s/crypt/cypher/ , encrypt/encypher, etc..
-- in refs, replace "database" with "database_name", that kind of things
-- import my hand-made test from /var/lib/.../pages/* to appropriate
- ref pages as online examples
-- At least in filters, <<EOR messes up the thing, only < is printed and stops
-- bin/refs-autogen should report which refs/* files have comments in them
- (text outside __NAME__ __END__ markers). It indicates there's a work to do
- on the item. Also XML files that have <!-- --> in them
-s/0-1/No-Yes/
-On config directives, include parse_<> function in source context
- See that if 'crypt' is put in see also, all symbols of that name appear
in see also line and their type is distinguished visually.
- TAXAREA is not discovered in source by bin/stattree
@@ -32,6 +21,12 @@
<ulink url="http://www.icdevgroup.org/pipermail/interchange-users/2004-December/041539.html">2004-December/041539</ulink>.
- match style (no starting verb or all starting verbs) in all Example titles
- check if all Default fields are properly formated (<literal> or none)
+- make regexp matching better, to properly scan parse_subroutine(); (gets
+ confused by { { in a substitution)
+- in refs, replace "database" with "database_name", that kind of things
+- import my hand-made test from /var/lib/.../pages/* to appropriate
+ ref pages as online examples
+- At least in filters, <<EOR messes up the thing, only < is printed and stops
Coding:
- script to [un]comment debug lines!!
1.13 +18 -1 xmldocs/bin/generic-autogen
rev 1.13, prev_rev 1.12
Index: generic-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/generic-autogen,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- generic-autogen 1 Feb 2005 21:35:07 -0000 1.12
+++ generic-autogen 15 Jun 2005 10:30:10 -0000 1.13
@@ -8,10 +8,14 @@
use warnings;
use strict;
+use Data::Dumper;
+
my %items;
my %alphabet;
my $verbose = 0;
my $cat = shift; $cat ||= "glossary";
+my %invalid;
+my $invalid_file = "tmp/missing2";
my @loaded;
my $document;
my %sn = ( # short name
@@ -56,7 +60,6 @@
<bookinfo>
<title>Interchange HOWTOs collection</title>
- <titleabbrev>howtos</titleabbrev>
<legalnotice>
<para>
@@ -116,6 +119,12 @@
}
closedir DIR or warn "Error closing $cat/ ($!)\n";
+# Find TODO notes or XML comments
+while (my ($k,$v)= each %items ) {
+ "@$v" =~ m/TODO/s and push @{ $invalid{$k} }, "Contains TODO item";
+ "@$v" =~ m/<!--/s and push @{ $invalid{$k} }, "Contains XML comment";
+}
+
# ADD ITEMS TO HEAD (TYPE-SPECIFIC)
if ( $cat eq 'glossary' ) {
@@ -151,6 +160,14 @@
die "Can't wropen $cat/$cat.xml ($!)\n";
print OUT $document;
close OUT or warn "Cant close $cat/$cat.xml ($!)\n";
+
+# Print out missing list
+print "GEN: tmp/mising2\n";
+open OUT, "> tmp/missing2" or
+die "Can't wropen tmp/missing2 ($!)\n";
+print OUT Dumper \%invalid;
+close OUT or warn "Cant close tmp/missing2 ($!)\n";
+
exit 0;
1.87 +15 -1 xmldocs/bin/refs-autogen
rev 1.87, prev_rev 1.86
Index: refs-autogen
===================================================================
RCS file: /var/cvs/xmldocs/bin/refs-autogen,v
retrieving revision 1.86
retrieving revision 1.87
diff -u -r1.86 -r1.87
--- refs-autogen 9 Jun 2005 12:02:43 -0000 1.86
+++ refs-autogen 15 Jun 2005 10:30:10 -0000 1.87
@@ -36,6 +36,7 @@
my %templates; # Templates for various symbol types
my $max_ctxs = 20; # Trim more than $max_ctxs source context reports
my @set_missing_all; # Helper to better manage %invalid
+my %todo; # Helper to better manage "Contains TODO item" messages
my @set_unused; # Notice which files inside refs/ were not used
my @parsed_versions; # IC versions we parsed
my $specific_only; # Build only one specific .xml ?
@@ -722,6 +723,7 @@
# Output the 'invalid' list
$invalid{$_} = ("Missing all (undocumented)") for @set_missing_all;
+print "GEN: tmp/missing\n";
open INVOUT, "> tmp/missing" or
die "Can't open tmp/missing ($!)\n";
print INVOUT Dumper \%invalid;
@@ -946,9 +948,21 @@
$pre_content = "";
$content = "";
$post_content = "";
+ } elsif ( $line =~ /TODO/ ) {
+ push @{ $invalid{$name} }, "Contains TODO item" unless
+ $todo{$group}{$name}++
}
# If not a beginning or end of section, simply add line to content
- $content .= $line if $section;
+ if ( $section ) {
+ $content .= $line;
+ push @{ $invalid{$name} }, "Contains XML comment" if
+ $line =~ /<!--/ and !$todo{$group}{$name}++
+ } elsif ( $line =~ /^__END__/ ) {
+ # Nothing
+ } elsif ( $line =~ /\S/ ) {
+ push @{ $invalid{$name} }, "Contains 'out of band' text" unless
+ $todo{$group}{$name}++
+ }
}
} else {
1.40 +38 -2 xmldocs/bin/stattree
rev 1.40, prev_rev 1.39
Index: stattree
===================================================================
RCS file: /var/cvs/xmldocs/bin/stattree,v
retrieving revision 1.39
retrieving revision 1.40
diff -u -r1.39 -r1.40
--- stattree 1 Mar 2005 10:31:12 -0000 1.39
+++ stattree 15 Jun 2005 10:30:10 -0000 1.40
@@ -765,9 +765,14 @@
$opens -= ( $line =~ s/([\)\]\}])/$1/g );
$directive .= $line;
- if (! $opens) { # Read the whole thing
+ if (! $opens) { # Have read the whole thing
$multiline = 0;
+ # Discover parse function for a directive
+ $directive =~ m/^\s*\['(.*?)',\s*'(.*?)',/s and
+ file_extractSub($1, "Vend::Config::parse_$2",
+ \%c, {group => $context,name=>$1});
+
# Register the directive and do some statistics
if ( $context eq 'globconf' ) {
push @globconf, [ $directive, $startline ] ;
@@ -803,6 +808,22 @@
%c,
lnum => $lnum,
ctx => [ format_ctx(split(/\n/, $ln)) ],
+ };
+
+ # Push whole resolved chain (parse_* function), but only if the catalog
+ # version of this directive doesn't exist, or exists but doesn't use the
+ # same parse function.
+ if ( $resolver_path{globconf}{$1} and
+ ( !$resolver_path{catconf}{$1} or
+ ( $resolver_path{globconf}{$1}->[0]->{ctx}->[0] ne
+ $resolver_path{catconf}{$1}->[0]->{ctx}->[0]))) {
+ while (my $spath=shift @{ $resolver_path{globconf}{$1}}){
+ push @{ $hash{symbols}{globconf}{$1} }, {
+ ctxpre => 0,
+ ctxpost => 0,
+ %$spath,
+ };
+ }
}
}
for my $itm (@catconf) {
@@ -812,6 +833,18 @@
%c,
lnum => $lnum,
ctx => [ format_ctx(split(/\n/, $ln)) ],
+ };
+
+ # Push whole resolved chain (parse_* function).
+ # (Here, we do it unconditionally, unlike 25 lines above)
+ if ( $resolver_path{catconf}{$1} ) {
+ while (my $spath=shift @{ $resolver_path{catconf}{$1}}){
+ push @{ $hash{symbols}{catconf}{$1} }, {
+ ctxpre => 0,
+ ctxpost => 0,
+ %$spath,
+ };
+ }
}
}
}
@@ -867,7 +900,10 @@
if ( !$opens) { $done++; $end = $j+1; last }
}
- die "NOT FOUND FOR $func ?\n" unless $done;
+ unless ( $done ) {
+ warn "NOT FOUND OR RUNAWAY FOR $func\n";
+ return
+ }
}
}
1.1 xmldocs/files/attributes/attributes.html
rev 1.1, prev_rev 1.0
Index: attributes.html
===================================================================
<html>
<body>
<table cellpadding="5">
<tr>
<th>Test #</th>
<th>Description</th>
<th>Price</th>
<th>Modifiers</th>
</tr>
[loop search="ra=yes/fi=products"]
<tr>
<td>[loop-code]</td>
<td>
[page [loop-code]]
[loop-field description]
</a>
</td>
<td align="right">[loop-field price]</td>
<td>
[loop-accessories size]
[loop-accessories color]
</td>
</tr>
[/loop]
</table>
</body>
</html>
1.1 xmldocs/files/attributes/products.txt
rev 1.1, prev_rev 1.0
Index: products.txt
===================================================================
sku description price size color
50595 Standard T-Shirt 15 S=Small, M=Medium, L=Large*, XL=Extra Large red=Red, blue=Blue, white=White
50623 Winter Jacket 140 S=Small, M=Medium, L=Large, XL=Extra Large*, XXL=Extra Extra Large blue=Blue, white=White, black=Black
50198 Long-sleeved Cotton Shirt 45 M=Medium*, L=Large red=Red, blue=Blue, white=White, maroon=Maroon
1.11 +8 -3 xmldocs/glossary/ITL
rev 1.11, prev_rev 1.10
Index: ITL
===================================================================
RCS file: /var/cvs/xmldocs/glossary/ITL,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- ITL 30 Apr 2005 22:56:52 -0000 1.10
+++ ITL 15 Jun 2005 10:30:11 -0000 1.11
@@ -44,13 +44,18 @@
</para>
<para>
Additionally, container tags for which you do not provide any
-<emphasis>body</emphasis> can be closed using "XML-style", but make sure to
-add an extra space, to unambiguously separate <literal>/]</literal> from the
-tag arguments. The following two lines are identical in effect:
+<emphasis>body</emphasis> can be closed using "XML-style" syntax.
+The following two lines are identical in effect:
<programlisting>
[forum top="[item-code]" display_page="forum/display"][/forum]
[forum top="[item-code]" display_page="forum/display" /]
</programlisting>
+</para>
+<para>
+Note, however, that <emphasis role='bold'>you can use "<literal>/]</literal>"
+only with tags for which you provide no parameters, or the parameters are named
+and quoted</emphasis>. Positional parameters "eat" everything (including
+the "<literal>/</literal>") up to the closing bracket.
</para>
<para>
It's probably also useful to mention that there must be no whitespace
1.2 +13 -34 xmldocs/glossary/attribute
rev 1.2, prev_rev 1.1
Index: attribute
===================================================================
RCS file: /var/cvs/xmldocs/glossary/attribute,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- attribute 3 Feb 2005 15:30:35 -0000 1.1
+++ attribute 15 Jun 2005 10:30:11 -0000 1.2
@@ -1,47 +1,26 @@
+Attributes are various "sub-features" of a product. If you are selling
+t-shirts in different colors and sizes, you are an ideal candidate for
+item attributes.
&IC; allows item <emphasis>attributes</emphasis> (also called
<emphasis>modifiers</emphasis> or <emphasis>options</emphasis>)
-to be set for each ordered item. This
-allows a varying size, color, or any other modifier to be attached to
-an otherwise common
-part number.
-
-<!-- TODO move some of this to UseModifier -->
+to be set for each ordered item. This allows a varying size, color, or
+any other modifier to be attached to an otherwise common part number.
+</para>
+<para>
+See &conf-UseModifier; for more information and concrete examples.
+</para>
+<!-- TODO move some of this to UseModifier
If multiple attributes are set, then they should be
separated by commas. Previous attribute values can be saved by means
of a hidden field on a form, and multiple attributes for each item
can be "stacked" on top of each other.
+ -->
-The configuration file directive &conf-UseModifier; is used to set
-the name of the modifier or modifiers. Here's an example of attaching
-both the size and color attributes to each item ordered.
-</para>
-
-<programlisting>
-UseModifier size,color
-</programlisting>
-
-<important>
-<para>
-Some of the names are reserved for use by &IC;, and you must not use them
-in modifier names. Namely, they include
- <literal>item</literal>,
- <literal>group</literal>,
- <literal>quantity</literal>,
- <literal>free</literal>,
- <literal>free_message</literal>,
- <literal>code</literal> and, of course,
- all <literal>mv_</literal> variables.
-</para>
-<para>
-You can see a quick list of those "reserved" names by entering the &IC;
-source tree and issuing <userinput>grep -r 'item->{[^$]' * | less</userinput>.
-</para>
-</important>
<para>
-Besides setting modifier names the config files, you can also set them as
+Besides setting modifier names in the config files, you can also set them as
&glos-scratch; variables with <mv>mv_UseModifier</mv>. For example,
the above modifiers would be set with
<code>[set mv_UseModifier]size color[/set]</code>.
@@ -50,7 +29,7 @@
the time of order will be used (just be careful, because you cannot set it
more than once on the same page).
</para><para>
-Setting &conf-SeparateItems; or <mv>mv_separate_items</mv>
+In addition, setting &conf-SeparateItems; or <mv>mv_separate_items</mv>
places each ordered item on a separate line even if they have the same
&glos-SKU;, simplifying attribute handling.
</para><para>
1.4 +15 -6 xmldocs/glossary/locale
rev 1.4, prev_rev 1.3
Index: locale
===================================================================
RCS file: /var/cvs/xmldocs/glossary/locale,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- locale 11 Jun 2005 08:29:00 -0000 1.3
+++ locale 15 Jun 2005 10:30:11 -0000 1.4
@@ -3,7 +3,11 @@
</para><para>
Localization (or "I10N") is a process of making an I18N-enabled application
to use specific locale definition (messages, currency format, etc.).
-</para><para>
+</para>
+
+<section>
+<title>Localized Catalogs</title>
+<para>
The important thing to have in mind is that &IC; allows customers to access
the same catalog in an unlimited number of languages, currencies and regional
settings. What's more, you can switch locales at will, at any time!
@@ -20,14 +24,19 @@
session, of course), or temporary (if you're, say, displaying pricing
information in multiple currencies). See &tag-setlocale; for more discussion
and examples.
-</para><para>
+</para>
+<para>
Besides using actual "programmatic" methods to set locales, you can achieve
the same effect by using one terrific feature of the <literal>process</literal>
&glos-ActionMap;; to display page named "<literal>pricelist</literal>" in
locale <literal>fr_FR</literal> and currency <literal>en_US</literal>, simply
-call &glos-ITL; tag
+Sall &glos-ITL; tag
<code>[page process/locale/fr_FR/currency/en_US/page/pricelist]</code>.
-</para><para>
+</para>
+</section>
+<section>
+<title>Locale-specific Messages and Locale Database</title>
+<para>
The localized messages you want to display must previously be defined, of
course.
The simplest way to define localized messages is to use
@@ -115,10 +124,10 @@
isn't just ingenious?!).
</para>
</note>
-
+</section>
<section>
- <title>Effect of locales on sorting</title>
+ <title>Effect of Locales on Sorting</title>
<para>
&IC; sorting features (such as — but not only — the
&tag-sort; tag)
1.5 +1 -2 xmldocs/howtos/custom-sendmail-routine
rev 1.5, prev_rev 1.4
Index: custom-sendmail-routine
===================================================================
RCS file: /var/cvs/xmldocs/howtos/custom-sendmail-routine,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- custom-sendmail-routine 20 Nov 2004 14:40:39 -0000 1.4
+++ custom-sendmail-routine 15 Jun 2005 10:30:12 -0000 1.5
@@ -2,7 +2,6 @@
<chapterinfo>
<title>Define Custom Sendmail Routine</title>
- <titleabbrev>customsendmail</titleabbrev>
<keywordset>
<keyword>custom</keyword>
@@ -27,7 +26,7 @@
<sect1 id='customsendmail_introduction'>
<title>Introduction</title>
<para>
- HOW-TO version: $Id: custom-sendmail-routine,v 1.4 2004/11/20 14:40:39 docelic Exp $
+ HOW-TO version: $Id: custom-sendmail-routine,v 1.5 2005/06/15 10:30:12 docelic Exp $
</para>
<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.
1.3 +1 -2 xmldocs/howtos/daemon-control
rev 1.3, prev_rev 1.2
Index: daemon-control
===================================================================
RCS file: /var/cvs/xmldocs/howtos/daemon-control,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- daemon-control 22 Nov 2004 00:18:43 -0000 1.2
+++ daemon-control 15 Jun 2005 10:30:12 -0000 1.3
@@ -2,7 +2,6 @@
<chapterinfo>
<title>Control Interchange Daemon</title>
- <titleabbrev>daemon-control</titleabbrev>
<keywordset>
<keyword>control</keyword>
@@ -35,7 +34,7 @@
<sect1 id='daemon-control_introduction'>
<title>Introduction</title>
<para>
- HOW-TO version: $Id: daemon-control,v 1.2 2004/11/22 00:18:43 docelic Exp $
+ HOW-TO version: $Id: daemon-control,v 1.3 2005/06/15 10:30:12 docelic Exp $
</para>
<para>
Knowing how to manage the Interchange daemon is one of the very basic
1.5 +1 -2 xmldocs/howtos/implement-banners
rev 1.5, prev_rev 1.4
Index: implement-banners
===================================================================
RCS file: /var/cvs/xmldocs/howtos/implement-banners,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- implement-banners 12 Nov 2004 22:26:26 -0000 1.4
+++ implement-banners 15 Jun 2005 10:30:12 -0000 1.5
@@ -2,7 +2,6 @@
<chapterinfo>
<title>Implement Banner Ads</title>
- <titleabbrev>implementbanners</titleabbrev>
<keywordset>
<keyword>banner</keyword>
@@ -29,7 +28,7 @@
<sect1 id='implementbanners_introduction'>
<title>Introduction</title>
<para>
- HOW-TO version: $Id: implement-banners,v 1.4 2004/11/12 22:26:26 docelic Exp $
+ HOW-TO version: $Id: implement-banners,v 1.5 2005/06/15 10:30:12 docelic Exp $
</para>
<para>
Banner display in &IC; is implemented using the <tag>banner</tag> tag.
1.2 +1 -2 xmldocs/howtos/log-files
rev 1.2, prev_rev 1.1
Index: log-files
===================================================================
RCS file: /var/cvs/xmldocs/howtos/log-files,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- log-files 23 Nov 2004 18:01:00 -0000 1.1
+++ log-files 15 Jun 2005 10:30:12 -0000 1.2
@@ -2,7 +2,6 @@
<chapterinfo>
<title>Setup and Monitor Log Files</title>
- <titleabbrev>setupandmonitorlog</titleabbrev>
<keywordset>
<keyword>log</keyword>
@@ -31,7 +30,7 @@
<sect1 id='setupandmonitorlog_introduction'>
<title>Introduction</title>
<para>
- HOW-TO version: $Id: log-files,v 1.1 2004/11/23 18:01:00 docelic Exp $
+ HOW-TO version: $Id: log-files,v 1.2 2005/06/15 10:30:12 docelic Exp $
</para>
<para>
To monitor all relevant log files at once, first adjust the
1.2 +157 -86 xmldocs/howtos/obtain-and-run-interchange
rev 1.2, prev_rev 1.1
Index: obtain-and-run-interchange
===================================================================
RCS file: /var/cvs/xmldocs/howtos/obtain-and-run-interchange,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- obtain-and-run-interchange 11 Jun 2005 23:39:25 -0000 1.1
+++ obtain-and-run-interchange 15 Jun 2005 10:30:12 -0000 1.2
@@ -1,130 +1,201 @@
-=head1 DISTRIBUTION AND SUPPORT INFORMATION
+<chapter id="obtain">
-Interchange is free of charge, and is distributed under the GNU
-General Public License. This means that individuals and organizations,
-both commercial and non-commercial, may use Interchange without charge. If
-you modify and redistribute it, there are certain obligations you
-must fulfill. See the file Copying which came with your Interchange
-distribution for the full license.
-
-Interchange is not guaranteed to be supported other than by making
-full source code available. If it breaks you get to keep both pieces.
-However, in practice Interchange is supported by a developer group and
-user community at it's mail list, interchange-users at icdevgroup.org. There
-are dozens of consultants who make Interchange-based systems their full-time
-work, and their are scores more who develop Interchange catalogs and sites.
-
-=head2 Where to Download Interchange
-
-The Interchange version described in this document is available from:
-
- http://ftp.icdevgroup.org/
+ <chapterinfo>
+ <title>Obtain and Run &IC;</title>
-=head2 Perl
+ <keywordset>
+ <keyword>interchange</keyword>
+ <keyword>obtain</keyword>
+ <keyword>get</keyword>
+ <keyword>download</keyword>
+ <keyword>find</keyword>
+ <keyword>minivend</keyword>
+ <keyword>tallyman</keyword>
+ <keyword>vend</keyword>
+ <keyword>install</keyword>
+ <keyword>run</keyword>
+ <keyword>configure</keyword>
+ <keyword>reconfig</keyword>
+ </keywordset>
+
+ <authorgroup>
+ <author>
+ <firstname>Mike</firstname>
+ <surname>Heins</surname>
+ <affiliation>
+ <email>mheins at icdevgroup.org</email>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ </chapterinfo>
+
+ <sect1 id='obtain_introduction'>
+ <title>Introduction</title>
+ <para>
+ HOW-TO version: $Id: obtain-and-run-interchange,v 1.2 2005/06/15 10:30:12 docelic Exp $
+ </para>
+ <para>
+ How to obtain and run &IC;.
+ </para>
+ </sect1>
-You will need Perl version 5.601 or higher to run Interchange 5.4, and
-Perl 5.8.3 or higher is recommended. Interchange requires the modules
-in Bundle::Interchange plus one of GDBM_File and DB_File.
+ <sect1 id='obtain_solution'>
+ <title>Solution</title>
-Interchange can run on Windows with the cygwin extensions,
+<para>
+&IC; is free of charge, and is distributed under the GNU
+General Public License. This means that individuals and organizations,
+both commercial and non-commercial, may use &IC; without charge. If
+you modify and redistribute it, there are certain obligations you
+must fulfill. See the file <filename>LICENSE</filename> which came with your
+&IC; distribution for the full license.
+</para><para>
+&IC; is not guaranteed to be supported other than by making
+full source code available. If it breaks you get to keep both pieces.
+However, in practice &IC; is supported by a developer group and
+user community at its mail lists,
+<ulink url="http://new.icdevgroup.org/i/new/community.html">http://new.icdevgroup.org/i/new/community.html</ulink>.
+. There
+are dozens of consultants who make &IC;-based systems their full-time
+work, and there are many more who develop &IC; catalogs and sites.
+</para><para>
+&IC; is officially available from
+<ulink url="http://new.icdevgroup.org/i/new/download.html">http://new.icdevgroup.org/i/new/download.html</ulink>. If you are not a skilled Unix user and do
+not have experience with Unix software installation and configuration,
+definitely choose ready-to-use &IC; packages for Red Hat or Debian GNU based
+systems. The rest of the notes apply to the manual, tarball installation
+process.
+</para>
+
+<sect2>
+<title>Pre-requirements</title>
+<para>
+You will need &PERL; version 5.601 or higher to run &IC;, and
+Perl 5.8.3 or higher is recommended. &IC; requires the modules
+in <classname>Bundle::&IC;</classname> plus one of GDBM_File and DB_File.
+</para><para>
+&IC; can run on Windows with the cygwin extensions,
but it is not supported and there are no known production sites
-using Windows. The majority of Interchange sites run on Linux,
+using Windows. The majority of &IC; sites run on Linux,
but there are also sites running FreeBSD, Irix, Mac OS/X, and Solaris.
-There is no reason Interchange cannot run on any Unix-like
-operating system.
-
-=head2 Setup for HTTP Servers
-
-Interchange requires a that a web server be installed on your system
+&IC; can run on any Unix-like operating system.
+</para><para>
+&IC; requires that a web server be installed on your system
in the normal course of events.
-
-As detailed previously, Interchange is always running in the background
-as a daemon. It monitors either 1) a UNIX-domain file-based socket, located
-in the RunDir directory (often etc/ in the main directory); or 2) a
-series of INET-domain sockets.
-
-The small CGI link program, called in the demo standard, is run to
-connect to one of those sockets and provide the link between Interchange
-and the web server.
-
-NOTE: Since Apache servers are the most popular, we will talk in the
-terms they use.
-
-You need to have a ScriptAlias or other CGI execution capability
-to use the link program. (The default ScriptAlias for many web
-servers is /cgi-bin.) If you have ExecCGI set for all of your
+As detailed previously, &IC; is always running in the background
+as a daemon. It monitors either a UNIX-domain file-based socket (located
+in the &conf-RunDir; directory) or a series of INET-domain sockets.
+The small CGI &glos-link-program; is used to connect to one of those sockets
+and provide the link between &IC; and the web server.
+(Since Apache web servers are the most popular, in the rest of the HOW-TO
+we will talk in the terms they use.)
+</para>
+</sect2>
+
+<sect2>
+<title>Web Server Setup</title>
+<para>
+You need to have a ScriptAlias or other CGI execution capability on your
+web server to use the &glos-link-program;. (The default ScriptAlias for many web
+servers is <literal>/cgi-bin</literal>.) If you have ExecCGI set for all of your
directories, then any program ending in a particular file suffix (usually
.cgi) will be seen as a CGI program.
+</para>
+</sect2>
-=head2 UNIX-domain sockets
-
-This is a socket which is not reachable from the Internet directly,
-but which must come from a request on your own server. The link program
-vlink is the provided facility for such communication with Interchange.
-
+<sect2>
+<title>UNIX Domain Sockets</title>
+<para>
+Unix domain sockets are not reachable from the Internet directly,
+but only locally from a request on your own server. The link program
+vlink is the provided facility for such communication with &IC;.
+(Note that this does not prevent visitors from seeing an &IC; website,
+in only makes it mandatory to run the Web server and &IC; server on
+the same computer).
This is the most secure way to run your catalog, for there is no way
-for systems on the Internet to interact with Interchange except through
-its link program.
-
-The most important issue with UNIX-domain sockets on Interchange is the
-permissions with which the CGI program and the Interchange server run.
-
-To improve security, Interchange normally runs with the socket file
-having 0600 permissions (rw-------), which mandates that the CGI
+for systems on the Internet to interact with &IC; except through
+its &glos-link-program;.
+</para><para>
+The most important issue with UNIX-domain sockets on &IC; is the
+permissions with which the CGI program and the &IC; server run.
+To improve security, &IC; normally runs with the socket file
+having &glos-mode; <literal>0600 (rw———-)</literal>, which mandates that
+the CGI
program and the server run as the same user ID. This means
that the vlink program must be SUID to the same user ID as
the server executes under. (Or that CGIWRAP or suexec is used
on a single catalog system).
-
-With Interchange multiple catalog capability, the permissions situation
-gets a bit tricky. Interchange comes with a program, makecat, which
+</para><para>
+With &IC; multiple catalog capability, the permissions situation
+gets a bit tricky. &IC; comes with a program, <command>makecat</command>, which
configures catalogs for a multiple catalog system. It should properly set
up ownership and permissions for multiple users if run as the superuser.
+</para>
+</sect2>
-=head2 INET-domain sockets
-
+<sect2>
+<title>INET Domain Sockets</title>
+<para>
These are sockets which are reachable from the Internet directly.
The link program tlink is the provided facility for such communication with
-Interchange; you may also use your browser to talk to the socket directly
+&IC;; you may also use your browser to talk to the socket directly
if you have it mapped to a catalog with the global TcpMap directive.
-To improve security, Interchange usually checks that the request comes
+To improve security, &IC; usually checks that the request comes
from one of a limited number of systems, defined in the global TcpHost
directive.
+</para>
+</sect2>
-=head1 QUICK START
+<sect2>
+<title>Quick Start</title>
+<para>
Obtain, decompress and untar the distribution:
- gzip -dc interchange-5.x.tar.gz | tar xvf -
+<programlisting>
+gzip -dc interchange-5.x.tar.gz | tar xvf -
+</programlisting>
Change to the created directory, something like:
-
- cd interchange-5.4.0
+
+<programlisting>
+cd interchange-5.4.0
+</programlisting>
Run the configure script with:
- ./configure
-
-If you have trouble with ./configure, try this:
-
- perl Makefile.PL
- make
- make test
- make install
+<programlisting>
+./configure
+</programlisting>
+
+If you have trouble with <command>./configure</command>, try this:
+
+<programlisting>
+perl Makefile.PL
+make
+make test
+make install
+</programlisting>
Replace the perl with the proper path to your Perl binary.
-
-You will be asked for the directory where you want to install Interchange --
+</para><para>
+You will be asked for the directory where you want to install &IC; —
any directory will do. You must of course have write permission there;
and you will eventually need to have write permission on your CGI-BIN
and HTML directories. This directory is referred to later in the
-documentation as VendRoot or the Interchange software directory.
-
+documentation as VendRoot or the &glos-ICROOT; directory.
+</para><para>
The process should be self-explanatory. If you have trouble answering
the questions asked, look closely at the examples provided. If you
still have trouble, you will need to find a tutorial about the World
-Wide Web -- the WWW FAQ at http://www.boutell.com/newfaq/ would be a
+Wide Web — the WWW FAQ at http://www.boutell.com/newfaq/ would be a
good place to look.
+ </para>
+ </sect2>
+</sect1>
+
+</chapter>
1.2 +1 -2 xmldocs/howtos/professional-support
rev 1.2, prev_rev 1.1
Index: professional-support
===================================================================
RCS file: /var/cvs/xmldocs/howtos/professional-support,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- professional-support 20 Nov 2004 14:40:39 -0000 1.1
+++ professional-support 15 Jun 2005 10:30:12 -0000 1.2
@@ -2,7 +2,6 @@
<chapterinfo>
<title>Request Professional Interchange Support</title>
- <titleabbrev>professionalsupport</titleabbrev>
<keywordset>
<keyword>interchange</keyword>
@@ -33,7 +32,7 @@
<sect1 id='professionalsupport_introduction'>
<title>Introduction</title>
<para>
- HOW-TO version: $Id: professional-support,v 1.1 2004/11/20 14:40:39 docelic Exp $
+ HOW-TO version: $Id: professional-support,v 1.2 2005/06/15 10:30:12 docelic Exp $
</para>
<para>
</para>
1.5 +1 -2 xmldocs/howtos/quantity-in-basket
rev 1.5, prev_rev 1.4
Index: quantity-in-basket
===================================================================
RCS file: /var/cvs/xmldocs/howtos/quantity-in-basket,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- quantity-in-basket 24 May 2005 21:42:18 -0000 1.4
+++ quantity-in-basket 15 Jun 2005 10:30:12 -0000 1.5
@@ -2,7 +2,6 @@
<chapterinfo>
<title>Provide Item Quantity Fields in the Basket Page</title>
- <titleabbrev>quantityfields</titleabbrev>
<keywordset>
<keyword>quantity</keyword>
@@ -39,7 +38,7 @@
<sect1 id='quantityfields_introduction'>
<title>Introduction</title>
<para>
- HOW-TO version: $Id: quantity-in-basket,v 1.4 2005/05/24 21:42:18 docelic Exp $
+ HOW-TO version: $Id: quantity-in-basket,v 1.5 2005/06/15 10:30:12 docelic Exp $
</para>
<para>
On your Interchange pages, you must provide some kind of an HTML form
1.4 +1 -2 xmldocs/howtos/validate
rev 1.4, prev_rev 1.3
Index: validate
===================================================================
RCS file: /var/cvs/xmldocs/howtos/validate,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- validate 21 May 2005 11:09:24 -0000 1.3
+++ validate 15 Jun 2005 10:30:12 -0000 1.4
@@ -2,7 +2,6 @@
<chapterinfo>
<title>Validate Interchange-produced Markup</title>
- <titleabbrev>validate</titleabbrev>
<keywordset>
<keyword>markup</keyword>
@@ -34,7 +33,7 @@
<sect1 id='validate_introduction'>
<title>Introduction</title>
<para>
- HOW-TO version: $Id: validate,v 1.3 2005/05/21 11:09:24 docelic Exp $
+ HOW-TO version: $Id: validate,v 1.4 2005/06/15 10:30:12 docelic Exp $
</para>
<para>
Validate pages at W3C.
1.2 +1 -1 xmldocs/refs/MailOrderTo
rev 1.2, prev_rev 1.1
Index: MailOrderTo
===================================================================
RCS file: /var/cvs/xmldocs/refs/MailOrderTo,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- MailOrderTo 11 Jun 2005 23:39:25 -0000 1.1
+++ MailOrderTo 15 Jun 2005 10:30:13 -0000 1.2
@@ -17,7 +17,7 @@
__END__
__NAME__ notes
-&conf-MailOrder>To; is one of the basic Interchange &glos-configuration;
+&conf-MailOrderTo; is one of the basic Interchange &glos-configuration;
directives.
</para><para>
If the &ccf; file, expected in the catalog base directory, is not found, or is
1.3 +36 -16 xmldocs/refs/UseModifier
rev 1.3, prev_rev 1.2
Index: UseModifier
===================================================================
RCS file: /var/cvs/xmldocs/refs/UseModifier,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- UseModifier 11 Jun 2005 08:29:00 -0000 1.2
+++ UseModifier 15 Jun 2005 10:30:13 -0000 1.3
@@ -21,28 +21,48 @@
Specify item &glos-attribute;s (or <emphasis>modifiers</emphasis>) that can
be be attached to items.
</para><para>
-Some of the names are protected and can't be used as modifier names
-are
-<literal>mv_*</literal> variables,
-<literal>group</literal>,
-<literal>code</literal>,
-<literal>quantity</literal> and
-<literal>item</literal>.
-Don't worry about it too much, however, as &IC; will warn you if you
-happen to accidentally use some of them.
+Some of the names are reserved for use by &IC;, and you must not use them
+in modifier names. Namely, they include
+ <literal>item</literal>,
+ <literal>group</literal>,
+ <literal>quantity</literal>,
+ <literal>free</literal>,
+ <literal>free_message</literal>,
+ <literal>code</literal> and, of course,
+ all <literal>mv_</literal> variables.
+</para>
+<para>
+You can see a quick list of those "reserved" names by entering the &IC;
+source tree and issuing <userinput>grep -r 'item->{[^$]' * | less</userinput>.
__END__
-__NAME__ example: Defining UseModifier
+__NAME__ example: Simple and standalone UseModifier example
+We first need to define &conf-UseModifier; in the &ccf; file (and restart
+&IC; afterwards):
<programlisting>
UseModifier size,color
</programlisting>
+Then we need to add the appropriate columns —
+<database class='field'>size</database> and
+<database class='field'>color</database> — to the
+<database>products</database> database. Here's
+<ulink url="files/attributes/products.txt">an example</ulink>:
+<programlisting>
+<xi:include parse='text' href='../files/attributes/products.txt'/>
+</programlisting>
+(The entry signified with "<literal>*</literal>" will be understood as the
+default).
+</para><para>
+And now all we need to display item size options is call
+<code>[accessories <replaceable>SKU</replaceable> size]</code> on an
+&IC; page. Let's create a sample
+<ulink url="files/attributes/attributes.html">attributes.html</ulink> page:
+<programlisting>
+<xi:include parse='text' href='../files/attributes/attributes.html'/>
+</programlisting>
+I hope this completes a very simple but working example, and
+breaks the entry-barrier to the world of &IC; modifiers.
__END__
-
-
-
-
-
-
More information about the docs
mailing list