guides/index.xml images/docbook.png images/lightlogo.png @@ -13,7 +13,7 @@ IC_VERSIONS = 4.6.0 4.8.0 5.0.0 5.2.0 cvs-head ############################################################# # Base definitions SYMBOL_TYPES= pragmas vars tags confs filters -GUIDES = iccattut programming-style upgrade faq +GUIDES = iccattut programming-style upgrade faq index HOWTOS = howtos GLOSSARY = glossary ALL_DOCS = $(GLOSSARY) $(HOWTOS) $(GUIDES) $(SYMBOL_TYPES) @@ -122,7 +122,7 @@ $T/%-c.db: %.xml ############################################################# # STANDARD TARGETS || two-pass processing method #OUTPUT/howtos.html: DEPTH = "--stringparam toc.max.depth 1" -OUTPUT/%.html: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autohowtos.ent +OUTPUT/%.html: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autohowtos.ent docbook/icfiles.ent echo "C $@" $(PSR) $(PSR_FLAGS) \ $(PROFILE) \ @@ -134,7 +134,7 @@ OUTPUT/%.html: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autoh --stringparam current.docid $* \ --stringparam target.database.document ../docbook/olinkdb-nc.xml \ -o $@ docbook/html-nochunks.xsl $T/$*-nc.profiled -OUTPUT/%: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autohowtos.ent +OUTPUT/%: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autohowtos.ent docbook/icfiles.ent echo "C $@/" $(PSR) $(PSR_FLAGS) \ $(PROFILE) \ @@ -146,7 +146,7 @@ OUTPUT/%: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autohowtos --stringparam current.docid $* \ --stringparam target.database.document ../docbook/olinkdb-nc.xml \ -o $@/ docbook/html-chunks.xsl $T/$*-c.profiled -OUTPUT/%.man: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autohowtos.ent +OUTPUT/%.man: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autohowtos.ent docbook/icfiles.ent echo "C $@/" mkdir -p "$@" $(PSR) $(PSR_FLAGS) \ @@ -167,8 +167,8 @@ OUTPUT/%.man: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autoho ############################################################# -# Supporting tagret - FO output -tmp/%.latex: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autohowtos.ent +# Supporting target - LATEX output +tmp/%.latex: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autohowtos.ent docbook/icfiles.ent $(PSR) $(PSR_FLAGS) \ $(PROFILE) \ --stringparam current.docid $* \ @@ -185,13 +185,6 @@ tmp/%.latex: %.xml docbook/autorefs.ent docbook/autoglossary.ent docbook/autohow --stringparam appendix.autolabel 0 \ --stringparam section.autolabel 0 \ -o $T/$*.latex docbook/latex.xsl $T/$*-nc.profiled -# -# -# --stringparam passivetex.extensions 1 -# --stringparam rootid "using" -# - - ############################################################# @@ -263,6 +256,7 @@ glossary/glossary.xml docbook/autoglossary.ent: $(shell find glossary/ -regex '. howtos/howtos.xml docbook/autohowtos.ent: $(shell find howtos/ -regex '.+[^(\.xml)]$$') bin/generic-autogen bin/generic-autogen howtos docbook/autorefs.ent: refxmls +docbook/icfiles.ent: refxmls ## Helper target, only used by docelic Makefile @@ -89,6 +89,8 @@ my %longname = ( var => "Global and catalog variable", ); +# Translation from granular internal types to +# XML output tag names. my %tagname = ( globvar => "varname", catvar => "varname", @@ -125,8 +127,8 @@ my %defaults = ( my @mandatory = (qw/synopsis example description purpose/); -# General section intros and "outros"; they are set per-item and not -# only per-section as you could achieve with putting them in a template. +# General section intros and "outros"; this header repeats per-item, +# unlike the effect of using templates which are just one per-section. # The header is inserted # *after* <title>, if title was specified in section definition. my %item_header = ( @@ -212,27 +214,31 @@ while ( $path = shift @paths) { # For each version specified } # Load in list of files. It's prepared for us by bin/stattree. - open IN, "< tmp/$i{ver}.filelist" or - die "Can't rdopen 'tmp/$i{ver}.filelist' ($!)\n"; - my @filelist = <IN>; + open IN, "< tmp/$i{ver}.MANIFEST" or + die "Can't rdopen 'tmp/$i{ver}.MANIFEST' ($!).\n" . + "Run 'make clean-cache cache'?\n"; + my @MANIFEST = <IN>; close IN; - chomp for @filelist; + chomp for @MANIFEST; # DocBook doesn't like '%' in entitity content, so let's # just weed out pages having %20 in the name - @filelist = grep {!/%/} @filelist; - my @filelist_ent = @filelist; - s/\//_/g for @filelist_ent; + @MANIFEST = grep {!/%/} @MANIFEST; + # The following line deals with /^MANIFEST/ line in MANIFEST file + s/\s.*// for @MANIFEST; + + my @MANIFEST_ent = @MANIFEST; + s/\//_/g for @MANIFEST_ent; - for (my $i=0; $i<@filelist_ent;$i++) { - $_ = $filelist_ent[$i]; + for (my $i=0; $i<@MANIFEST_ent;$i++) { + $_ = $MANIFEST_ent[$i]; print FILE_ENTITIES '<!ENTITY cvsfile' . $i{series} . '-' . $_ . qq{ "<ulink url='http://www.icdevgroup.org/cgi-bin/cvsweb/interchange/} . - $filelist[$i] . $i{cvstag} . "'>" . - $filelist[$i] . qq{</ulink>"} . ">\n"; + $MANIFEST[$i] . $i{cvstag} . "'>" . + $MANIFEST[$i] . qq{</ulink>"} . ">\n"; # If this is the last version we generate docs for, also provide # entity with no version in its name: @@ -242,8 +248,8 @@ while ( $path = shift @paths) { # For each version specified '-' . # Just $i{series} removed from here. $_ . qq{ "<ulink url='http://www.icdevgroup.org/cgi-bin/cvsweb/interchange/}. - $filelist[$i] . $i{cvstag} . "'>" . - $filelist[$i] . qq{</ulink>"} . ">\n"; + $MANIFEST[$i] . $i{cvstag} . "'>" . + $MANIFEST[$i] . qq{</ulink>"} . ">\n"; } } bin/refs-autogen @@ -40,7 +40,6 @@ my $ctx_n = 4; # after my %resolver_path; # Support for stack (a -> b -> c -> d => # a = d with full "path" recorded). This expands # MapRoutines, parse_ functions and things like that. -my ($filelist,@filelist); # Keep and dump list of all files found # All file types should be listed here or the stats wont be accurate. # It should be reported if an unknown file is found in the archive (you can @@ -133,6 +132,12 @@ find({ bydepth => 0, no_chdir=> 1, }, "."); + + +# Copy MANIFEST to "cache": +`cp MANIFEST "../../tmp/$i{ver}.MANIFEST"`; +print "GEN: tmp/$i{ver}.MANIFEST\n"; + chdir $cpath; # Return to starting location @@ -147,13 +152,6 @@ if ( $verbose ) { close OUT; } -# Dump out file list -local $" = "\n"; -open OUT, "> tmp/$i{ver}.filelist" or - die "Can't open tmp/$i{ver}.filelist ($!)\n"; -print OUT "@filelist"; -close OUT; - exit 0; ################################################################# @@ -162,8 +160,6 @@ sub wanted { ( my $file = $_ ) =~ s/^\.\///; return if $file eq '.'; - push @filelist, $file; - # Things we ignore return if /(^|\/)(CVS|\.cvs|\.svn|\.autoload)(\/.+[^\/])?$/; bin/stattree @@ -26,6 +26,19 @@ <xsl:param name="use.extensions">0</xsl:param> <xsl:param name="textinsert.extension">1</xsl:param> +  + <xsl:param name="generate.toc"> + article toc,title,figure,table,example,equation + reference toc,title,example + book nop + glossary toc,title + </xsl:param> + +  <xsl:template match="tag">[<xsl:call-template name="inline.monoseq"/>]</xsl:template> <xsl:template match="pragma"><xsl:call-template name="inline.monoseq"/></xsl:template> docbook/common.xsl @@ -23,6 +23,12 @@ <xsl:template name="user.footer.content" > <p class='w3c'> + <a href="http://www.docbook.org/"> + <img + src="../images/docbook.png" + alt="DocBook!" + class='w3cimg'/> + </a> <a href="http://jigsaw.w3.org/css-validator/"> <img src="../images/colophon_css.png" docbook/html-chunks.xsl @@ -11,6 +11,12 @@  <xsl:template name="user.footer.content" > <p class='w3c'> + <a href="http://www.docbook.org/"> + <img + src="images/docbook.png" + alt="DocBook!" + class='w3cimg'/> + </a> <a href="http://jigsaw.w3.org/css-validator/"> <img src="images/colophon_css.png" docbook/html-nochunks.xsl @@ -5,6 +5,7 @@ <!ENTITY upgrade SYSTEM "../tmp/upgrade-c.db"> <!ENTITY faq SYSTEM "../tmp/faq-c.db"> <!ENTITY programming-style SYSTEM "../tmp/programming-style-c.db"> + <!ENTITY index SYSTEM "../tmp/index-c.db"> <!ENTITY howtos SYSTEM "../tmp/howtos-c.db"> <!ENTITY glossary SYSTEM "../tmp/glossary-c.db"> <!ENTITY pragmas SYSTEM "../tmp/pragmas-c.db"> @@ -47,6 +48,12 @@ </document> </dir> + <dir name='index'> + <document targetdoc="index"> + &index; + </document> + </dir> + <dir name='howtos'> <document targetdoc="howtos"> &howtos; docbook/olinkdb-c.xml @@ -5,6 +5,7 @@ <!ENTITY upgrade SYSTEM "../tmp/upgrade-nc.db"> <!ENTITY faq SYSTEM "../tmp/faq-nc.db"> <!ENTITY programming-style SYSTEM "../tmp/programming-style-nc.db"> + <!ENTITY index SYSTEM "../tmp/index-nc.db"> <!ENTITY howtos SYSTEM "../tmp/howtos-nc.db"> <!ENTITY glossary SYSTEM "../tmp/glossary-nc.db"> <!ENTITY pragmas SYSTEM "../tmp/pragmas-nc.db"> @@ -26,6 +27,7 @@ <document targetdoc="upgrade" baseuri="upgrade.html"> &upgrade; </document> <document targetdoc="faq" baseuri="faq.html"> &faq; </document> <document targetdoc="programming-style" baseuri="programming-style.html"> &programming-style; </document> + <document targetdoc="index" baseuri="index.html"> &index; </document> <document targetdoc="howtos" baseuri="howtos.html"> &howtos; </document> <document targetdoc="glossary" baseuri="glossary.html"> &glossary; </document> <document targetdoc="pragmas" baseuri="pragmas.html"> &pragmas; </document> docbook/olinkdb-nc.xml @@ -330,6 +330,32 @@ thead { } /* + Book element styling. Only used for first index page + that links to other pages. +*/ + +.book thead { + background-color: #be7109; +} + + +.book td, .book table { + border: none; +} + +.book th { + border: 1px dashed #fff; +} + +.book table a { + font-size: 70%; +} + +.book .authorgroup { + background: url(images/lightlogo.png) no-repeat scroll center right; +} + +/* Glossary styling: .glossary .titlepage . . h2.title <a/> /h2 / / . / / docbook/xmldocs.css @@ -1974,7 +1974,6 @@ with user-entered data. </para> </answer></qandaentry> - + TIME: [benchmark] + +Benchmark loop-param list: [benchmark start=1] +  + TIME: [benchmark] ]]></programlisting> - Benchmark loop-field list: [benchmark start=1] - <!- [loop search="ra=yes/st=db"] - [loop-code] price: [loop-field price] [/loop] -> - TIME: [benchmark] - - Benchmark loop-param list: [benchmark start=1] - <!- [loop search="ra=yes/st=db/rf=sku,price"] - [loop-code] price: [loop-param price] [/loop] -> - TIME: [benchmark] but the second is much, much faster. @@ -2152,53 +2137,50 @@ row or data containers. I see a lot of: <programlisting><![CDATA[ - +[loop search="ra=yes"] + [calc] return '<tr>' if [loop-increment] == 1; return[/calc] + [calc] return '' if [loop-increment] % 3; return '</tr>' [/calc] +[/loop] ]]></programlisting> - [loop search="ra=yes"] - [calc] return '<tr>' if [loop-increment] == 1; return[/calc] - [calc] return '' if [loop-increment] % 3; return '</TR>' [/calc] - [/loop] Much faster, by a few orders of magnitude, is: <programlisting><![CDATA[ +[loop search="ra=yes"] + [loop-change 1][condition]1[/condition]<tr>[/loop-change 1] + [loop-alternate 3]</TR>[/loop-alternate] +[/loop] -]]></programlisting> - - [loop search="ra=yes"] - [loop-change 1][condition]1[/condition]<tr>[/loop-change 1] - [loop-alternate 3]</TR>[/loop-alternate] - [/loop] - - If you think you need to close the final row by checking the - final count, look at this: - - [loop search="ra=yes"] - [on-match] - <table> - <tr> - [/on-match] - - [list] - <td>[loop-code]</TD> - [loop-alternate 3]</TR><tr>[/loop-alternate] - [/list] - - [on-match] - </TR> - </TABLE> - [/on-match] - - [no-match] - No match, sorry. - [/no-match] +If you think you need to close the final row by checking the +final count, look at this: +[loop search="ra=yes"] + [on-match] + <table> + <tr> + [/on-match] + + [list] + <td>[loop-code]</TD> + [loop-alternate 3]</TR><tr>[/loop-alternate] + [/list] + + [on-match] + </tr> + </table> + [/on-match] + + [no-match] + No match, sorry. + [/no-match] [/loop] +]]></programlisting> + This is a hundred times faster than anything you can build with -multiple [calc] tags. +multiple &tag-calc; tags. * Use simple go/nogo comparisons in [if ...] @@ -2206,20 +2188,15 @@ Consider these two snippets: <programlisting><![CDATA[ - +[if scratch|value|cgi key] THEN [/if] ]]></programlisting> - [if scratch|value|cgi key] THEN [/if] - and: - <programlisting><![CDATA[ - +[if scratch|value|cgi key == '1'] THEN [/if] ]]></programlisting> - [if scratch|value|cgi key == '1'] THEN [/if] - The first one doesn't require &PERL; evaluation. It simply checks to see if the value is blank or 0, and returns true if it is anything but. Of course this requires setting your test values to blank or 0 instead @@ -2227,56 +2204,57 @@ of "No" or " " or somesuch, but it is anywhere from 20-35% faster. Try it on the foundation demo: - <programlisting><![CDATA[ +Overhead: + +[benchmark start=1] + + + +[benchmark] +<p> -]]></programlisting> - - begin test - - - Overhead: - [benchmark start=1] - <!- [loop search="ra=yes"] - [set cert][loop-field gift_cert][/set] - [/loop] -> - [benchmark] - <p> - - - if scratch compare: - [benchmark start=1] - <!- - [loop search="ra=yes"] - [set cert][loop-field gift_cert][/set] - [loop-code] [if scratch cert] YES [else] NO [/else][/if] - [loop-code] [if scratch cert] YES [else] NO [/else][/if] - [loop-code] [if scratch cert] YES [else] NO [/else][/if] - [loop-code] [if scratch cert] YES [else] NO [/else][/if] - [loop-code] [if scratch cert] YES [else] NO [/else][/if] - [/loop] - -> - - [benchmark] - <p> - - if scratch compare eq 1: - [benchmark start=1] - <!- - [loop search="ra=yes"] - [set cert][loop-field gift_cert][/set] - [loop-code] [if scratch cert == 1] YES [else] NO [/else][/if] - [loop-code] [if scratch cert == 1] YES [else] NO [/else][/if] - [loop-code] [if scratch cert == 1] YES [else] NO [/else][/if] - [loop-code] [if scratch cert == 1] YES [else] NO [/else][/if] - [loop-code] [if scratch cert == 1] YES [else] NO [/else][/if] - [/loop] - -> - [benchmark] - <p> - - [page @@MV_PAGE@@]Again</a> - - - end test - +if scratch compare: +[benchmark start=1] + + + +[benchmark] +<p> + + +if scratch compare eq 1: +[benchmark start=1] + + +[benchmark] +<p> + +[page @@MV_PAGE@@]Again</a> +]]></programlisting> * Use [PREFIX-calc] instead of [calc] or [perl] @@ -2293,25 +2271,23 @@ available for access inside of it, just do: <programlisting><![CDATA[ - +[perl tables="products pricing"] [/perl] ]]></programlisting> - [perl tables="products pricing"] [/perl] prior to list start. Now you can do something like: <programlisting><![CDATA[ - +[loop search="ra=yes"] + [loop-calc] + $desc = $Tag->data('products', 'description', '[loop-code]'); + $link = $Tag->page('[loop-code]'); + return "$link $desc </A>"; + [/loop-calc] <br> +[/loop] ]]></programlisting> - [loop search="ra=yes"] - [loop-calc] - $desc = $Tag->data('products', 'description', '[loop-code]'); - $link = $Tag->page('[loop-code]'); - return "$link $desc </A>"; - [/loop-calc] <br> - [/loop] * ADVANCED: Precompile and execute with [PREFIX-sub] and [PREFIX-exec] @@ -2333,37 +2309,37 @@ faster than separate [PREFIX-calc] calls. <programlisting><![CDATA[ +[benchmark start=1] + +loop-calc: + + +[benchmark] + +<p> + +[benchmark start=1] +loop-sub and loop-exec: + +[benchmark] ]]></programlisting> - [benchmark start=1] - loop-calc: - <!- - [loop search="st=db/fi=country/ra=yes/ml=1000"] - [loop-calc] - my $code = q{[loop-code]}; - return "code '$code' reversed is " . reverse($code); - [/loop-calc] - [/loop] - -> - - [benchmark] - - <p> - - [benchmark start=1] - loop-sub and loop-exec: - <!- - [loop search="st=db/fi=country/ra=yes/ml=1000"] - [loop-sub country_compare] - my $code = shift; - return "code '$code' reversed is " . reverse($code); - [/loop-sub] - [loop-exec country_compare][loop-code][/loop-exec] - [/loop] - -> - - [benchmark] * ADVANCED: Execute and save with [query ...], then use an embedded &PERL; routine. @@ -2379,50 +2355,54 @@ This is the fastest possible method to display a list. <programlisting><![CDATA[ +[set waiting_for]os28004[/set] -]]></programlisting> +[benchmark start=1] Embedded &PERL; + + +TIME: [benchmark] + + +[benchmark start=1] All loop + + + +TIME: [benchmark] +]]></programlisting> +</para> +</answer> +</qandaentry> + +<!-- * Other things that help: ** Avoid interpolate=1 when possible. A separate tag parser must be spawned guides/faq.xml @@ -1,5 +1,5 @@ __NAME__ purpose -backup Interchange databases, optionally +backup Interchange databases, even rows selectively __END__ __NAME__ synopsis refs/backup-database.tag @@ -14,7 +14,7 @@ __NAME__ online: Filter example [set online_commify_test]1234567890.123456[/set] My commified value, trimed to 2 decimal places is: -[filter commify.2]online_commify_test[/filter] +[filter commify.2][scratchd online_commify_test][/filter] </programlisting> __END__ refs/commify.filter 65794f3ef63a76ec59e62f7b1c68e06b24e09788 Davor Ocelic docelic@spinlocksolutions.com http://github.com/interchange/xmldocs/commit/a8653bb0aede739ad76ac94926874406aa4dec93 a8653bb0aede739ad76ac94926874406aa4dec93

2005-09-01T16:12:38-07:00

** Incompatible changes to bin/stattree and bin/refs-autogen force you to do: make clean-cache caches (to regenerate cache files) ** Besides other changes that follow, I have added the index page that links to other documents. This index page is necessary for the alpha release of xmldocs along with the new website. Update CVS, then do make OUTPUT/index.html , it's beautiful! - bin/stattree: - instead of going for the trouble of discovering distribution files ourselves, just copy the MANIFEST file - dump file is tmp/<version>.MANIFEST and not tmp/<version>.filelist any more - bin/refs-autogen: - same code as before but renamed .filelist to .MANIFEST - small comments added / clarified - improve one error message (suggest solution) - docbook/xmldocs.css: add CSS for index page - docbook/html-*.xsl: added docbook icon to documents' footer - docbook/*: rest of supporting elements, as always - images/lightlogo.png: small bright variant of IC logo for decoration - images/docbook.png: docbook icon - Makefile: - add document 'index' to list of docs to generate - add docbook/icfiles.ent to list of dependencies - remove comment that we don't need any more - refs/*: simple fixes - guides/faq.xml: further rearrangements and xml-ification b18492b702093e79c2cdba706f4017b0870d7540 Davor Ocelic docelic@spinlocksolutions.com