Permalink
Browse files

- TODO: remove stuff that's been handled over the time, or doesn't fit

        current logic
- bin/generic-autogen: in generated glossary entry names (the ones that are
        displayed), replace dashes with spaces, for cleaner look
- docbook/literals.ent: add GPG entity (&GPG;)
- docbook/xmldocs.css: remove 2 small unneeded chunks
- docbook/symbol-templates/*: s/(DIRECTIVE TYPE)/\1 AND DEFAULT VALUE/
- glossary/expire: add text
- guides/install.xml: small fixes
- howtos/daemon-control: add hint on interchange -test
- refs/*.tag: more docs
  • Loading branch information...
1 parent 443aa8b commit 554f9d4275f0b2a4086ac54c671c5a8b9426449d @docelic docelic committed Jul 4, 2006
View
@@ -1,17 +1,6 @@
- in iccattut, s/item-field/item-param/ at least on some places.
- Make xmldocs tarball in ftp autoupdated
- Change -latest to version number in tarball download
-- In iccattut examples (files/*), replace catalog setting of ErrorFile,
- TrackFile and similar directives with relative filenames. Also see how
- Jon's file layout restructuring affects the examples
-- In reference pages, make special string, such as __FNAME__, that expands
- to name of the filename. Will speed up writing and eliminate errors such
- as copying "Setting ErrorFile" and forgetting to replace ErrorFile with
- another name. (With this option, both files would just have
- "Setting __FNAME__", and would magically work).
-- Parse default value for config directives (at least in cases where the
- value is a simple oneliner), and display it as a special field in the
- reference page.
- bin/whatsnew-update didn't pick up User: from messages
Outstanding:
@@ -33,9 +22,6 @@ Outstanding:
- Under AUTHORS, include cvs line where appropriate (guides, howtos, gloss... )
- In vars.html, include line if it appears in variable.txt
- why email, email-raw, SendMailProgram produce errors about usertags olink ID
-- Add docbook element to reference mailing list posts. Something like
- <ml list='users'>2004-December/041539</ml>, it expands to:
- <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
@@ -49,31 +35,13 @@ Coding:
- script to [un]comment debug lines!!
- use Interchange.pm to make an Interchange shell (External.pm!)
- finish ML stats <-- MAILPOND on ocelic2!
-
-DOCUMENTATION SYSTEM:
-- Add support to document tags which are NOT found in separate files
- (like [restrict] or [subject]).
-
-TODO: Create a pre-processor for the "docbook/docbookxi.dtd" and
-"docbook/olinkdb*xml" files that would automatically discover the path to
-the "docbookx.dtd" and "targetdatabase.dtd" files. Running a find(1) in
-"/usr/share" should do the trick on most GNU/Linux OSs, and will remove
-the need for distro-specific patches that will quickly grow stale due
-to package version number changes.
+- script to manipulate file headers
Mid-term:
-- Ask ndw about including [NEW!] and [TODO!] in titles in TOC. --> This is a
- bug and it will work when they fix it.
-- &glos-hello-world needs to give "hello world", not "hello-world" as text
- List of mv_s, descriptions and shortcuts
- 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, 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. Example for this could be taken directly out of
- mwforum demo on mwforum.org
- Generate leaf nodes (put bin/mkreport back in action)
- If filter returns Vend::xxx::something(), include that function in context
reports, and try to determine the "Uses" field (which also needs to be
View
@@ -29,7 +29,7 @@ my %ln = ( # long name
my %header = ( # item head
glossary => "<glossentry id=\"\$file\">
-<glossterm>\$file</glossterm>
+<glossterm>\$visible_name</glossterm>
<glossdef><para>
",
@@ -80,12 +80,13 @@ readdir DIR; readdir DIR;
while ( my $file = readdir DIR ) {
next if $file =~ /^\.|^CVS|\.xml$/;
open IN, "< $cat/$file" or die "Can't read-open $cat/$file ($!)\n";
+
+ ( my $visible_name = $file ) =~ s/-/ /g;
$items{$file} = [ prefix($cat, $file), <IN>, suffix($cat, $file) ];
$alphabet{ lc(substr($file, 0, 1)) }++;
push @loaded, $file;
- my $lcfile = lc $file;
- my $link = "<olink targetdoc='$cat' targetptr='$file'/>";
+ my $link = "<olink targetdoc='$cat' targetptr='$file'>$visible_name</olink>";
my $more = $cat eq 'howtos' ? " $ln{$cat}" : "";
print ENT <<ENDO;
@@ -141,7 +142,7 @@ print OUT $document;
close OUT or warn "Cant close $cat/$cat.xml ($!)\n";
# Print out missing list
-print "GEN: tmp/mising2\n";
+print "GEN: tmp/missing2\n";
open OUT, "> tmp/missing2" or
die "Can't wropen tmp/missing2 ($!)\n";
print OUT Dumper \%invalid;
@@ -155,6 +156,7 @@ exit 0;
sub prefix {
my ($cat, $file) = @_;
+ ( my $visible_name = $file ) =~ s/-/ /g;
if ( $header{$cat} ) {
my $tmp = $header{$cat};
$tmp =~ s/(\$\w+)/$1/gee;
@@ -165,6 +167,7 @@ sub prefix {
sub suffix {
my ($cat, $file) = @_;
+ ( my $visible_name = $file ) =~ s/-/ /g;
if ( $footer{$cat} ) {
my $tmp = $footer{$cat};
$tmp =~ s/(\$\w+)/$1/gee;
@@ -36,6 +36,7 @@
<!ENTITY SOAP "<ulink url='http://www.w3.org/TR/soap/'>SOAP</ulink>">
<!ENTITY WP "<ulink url='http://www.wikipedia.org/'>Wikipedia</ulink>">
<!ENTITY SWISH-E "<ulink url='http://www.swish-e.org/'>Swish-e</ulink>">
+<!ENTITY GPG "<ulink url='http://www.gnupg.org/'>GPG</ulink>">
@@ -25,7 +25,7 @@ $ag{"synopsis"}
</refsect1>
<refsect1 id='$ag{"name"}_type'>
-<title>DIRECTIVE TYPE</title>
+<title>DIRECTIVE TYPE AND DEFAULT VALUE</title>
<para>$ag{"directive type"}</para>
</refsect1>
@@ -25,7 +25,7 @@ $ag{"synopsis"}
</refsect1>
<refsect1 id='$ag{"name"}_type'>
-<title>DIRECTIVE TYPE</title>
+<title>DIRECTIVE TYPE AND DEFAULT VALUE</title>
<para>$ag{"directive type"}</para>
</refsect1>
View
@@ -409,10 +409,6 @@ thead {
color: #000;
}
- .filename {
- border: dashed 1px #000;
- }
-
.varname {
color: #000;
}
@@ -421,10 +417,6 @@ thead {
color: #000;
}
- .function {
- border: dashed 1px #000;
- }
-
thead {
color: #000;
background-color: gray;
View
@@ -0,0 +1,18 @@
+SDBM is an of in-file, non-&glos-SQL; database (similar to GDBM).
+</para><para>
+&IC; must work with some kind of a database. When no SQL database is
+specified, database source files (text) are still stored in a database,
+even though it's a file-based one (GDBM or similar) and requires no
+special setup from the user.
+</para><para>
+For in-file database backend, &IC; will either use &GDBM; or &BDBM;, depending
+on what it finds on the system.
+</para><para>
+Yet another option was SDBM, but it is severely handicapped &mdash; it does
+not support values bigger than 2048 bytes and at least two of our demo
+catalog databases fail to load for that reason.
+</para><para>
+Since early 2006, Interchange no longer considers SDBM an option, unless it is
+explicitly told so. You can explicitly instruct &IC; to use SDBM backend
+for particular databases, but that is not encouraged and SBDM should not
+be used.
View
@@ -0,0 +1,77 @@
+User &glos-session;s in Interchange are usually kept as files in the
+<filename class='directory'>session/</filename> directory (or inside
+a DBM database) for each &glos-catalog;. Since session
+data is not deleted after sessions end (or timeout), periodic expiring
+needs to be set up to keep the session database or session files from growing
+too large and wasting disk space.
+</para><para>
+There's no worry that expiring will do any harm, because all our scripts
+only clean up unused sessions. Active users will not notice any change.
+</para><para>
+The simplest way to expire catalog's session files is to run
+<command>expire -c <replaceable>CATALOG_NAME</replaceable></command>.
+</para><para>
+For convenience, there is also <command>expireall</command> script which
+reads all catalog entries in &gcf; and runs <command>expire</command> on them.
+</para><para>
+The <command>expire</command> script accepts a <literal>-r</literal> option
+which tells it to reorganize database files and recover lost disk space.
+</para><para>
+On a UNIX server, it's most useful to run <command>expireall</command>
+from <literal>crontab</literal>. As the &IC; user, run
+<command>crontab -e</command> to edit crontab data, and enter something like:
+<programlisting>
+# once a day at 4:40 am
+40 4 * * * /PATH/TO/perl /PATH/TO/INTERCHANGE/bin/expireall -r
+</programlisting>
+</para>
+<note>
+<para>
+If a session saved search paging files in &conf-ScratchDir;, they would
+be deleted too.
+</para>
+</note>
+
+<para>
+When file-based sessions are used (no DBM), then you can use a custom
+script like this:
+
+<programlisting><![CDATA[
+#!perl
+# expire_sessions.pl -- delete files 2 days old or older
+# invoke as: /PATH/TO/perl expire_sessions.pl /PATH/TO/CATALOG/session/ ...
+
+my @files;
+my $dir;
+foreach $dir (@ARGV) {
+ # just push files on the list
+ if (-f $dir) { push @files, $_; next; }
+
+ next unless -d $dir;
+
+ # get all the file names in the directory
+ opendir DIR, $dir or die "opendir $dir: $!\n";
+ push @files, ( map { "$dir/$_" } grep(! /^\.\.?$/, readdir DIR));
+}
+
+for (@files) {
+ unless (-f $_) {
+ warn "skipping $_, not a file.\n";
+ next;
+ }
+ next unless -M $_ >= 2;
+ unlink $_ or die "unlink $_: $!\n";
+}
+]]></programlisting>
+This script can be adjusted as necessary. Refinements might include reading
+the file to "eval" the session reference and expire only customers who are not
+registered members.
+</para><para>
+If your files get chown-ed to root every day, then you probably used root's
+instead of &IC; user's crontab file. Either move the crontab to the
+&IC; user, or use <command>su</command> to swith users from the root
+account:
+<programlisting>
+44 4 * * * su -c "/PATH/TO/INTERCHANGE/bin/expireall -r" IC_USERNAME
+</programlisting>
+
View
@@ -47,16 +47,22 @@
</para><para>
While the concepts will be properly explained and elaborated on,
the intention is to make this document a collection of pointers
- to other documentation that is, among other times, relevant
- during installation.
+ to other parts of &IC; documentation.
</para><para>
- The Guide is intended for people who want to install &IC; from
- generic tarballs. People installing from distribution-specific
+ People installing from distribution-specific
packages (Debian GNU, Red Hat-based platforms, Gentoo, ...) do
not need a guide this comprehensive &mdash; the package maintainers
- have taken care of most of the decisions themselves.
+ have already taken care of most of the issues.
+ </para><para>
+ The Guide is intended for people who want to install &IC; from
+ generic tarballs. You might want to prefer tarballs over
+ distribution-specific packages if you are either using a non-standard
+ platform, or want to always access the latest releases (when
+ distribution-specific packages are laggign behind).
+ <emphasis role='bold'>So far, it seems the tarballs are the
+ cleanest and most preferred installation method.</emphasis>
</para><para>
- Those impatient or familiar with Unix administration and software
+ Those impatient or already familiar with Unix administration and software
installations, might want to directly go unpacking the tarball and
running <command>perl Makefile.PL; make; make test &amp;&amp;
make install</command> in there.
@@ -142,7 +148,7 @@ $ /path/to/perl -MCPAN -e 'install "Bundle::InterchangeKitchenSink"'
<sect2 id='compiler'>
<title>C compiler</title>
<para>
- &IC; uses the so-called "link program" to provide a link between
+ &IC; uses the so-called "&glos-link-program;" to provide a link between
the web and Interchange servers. It is, in fact, a very simple C
program that is installed as a CGI script and that passes parameters
back and forth.
@@ -219,11 +225,10 @@ $ /path/to/perl -MCPAN -e 'install "Bundle::InterchangeKitchenSink"'
</para>
<para>
If you do not employ an SQL database, &IC; will use &GDBM; or
- &BDBM;, depending on what it finds on the system. Yet another option
- is SDBM, but it is severely handicapped &mdash; it does not support
- values bigger than 2048 bytes, and at least two of our demo catalog
- databases have problems with it out-of-the-box. Since early 2006,
- &IC; no longer considers SDBM an option, unless it is explicitly told so.
+ &BDBM;, depending on what it finds on the system.
+ Yet another option is &glos-SDBM;, but it is severely limited in
+ functionality and is not selected unless explicitly specified by the
+ user.
</para>
</sect2>
@@ -306,7 +311,7 @@ $ gzip -dc interchange-latest.tar.gz | tar xvf -
your best bet is to visit our
<ulink url="http://www.icdevgroup.org/i/dev/users/community">community</ulink>
page and drop by on IRC, or post your problem to
- the users mailing list.
+ the users mailing list (see &PUBLIC_MLS; page).
</para>
</sect1>
Oops, something went wrong.

0 comments on commit 554f9d4

Please sign in to comment.