[docs] xmldocs - docelic modified 15 files

docs at icdevgroup.org docs at icdevgroup.org
Thu Feb 3 10:30:36 EST 2005


User:      docelic
Date:      2005-02-03 15:30:36 GMT
Modified:  .        Makefile
Modified:  bin      stattree
Modified:  docbook  xmldocs.css
Modified:  guides   programming-style.xml xmldocs.xml
Modified:  images   home.gif home.png new.png next.gif next.png
Modified:           prev.gif prev.png up.gif up.png
Added:     glossary attribute
Log:
- Makefile: removed xmldocs guide from build (obsolete, see WRITING)

- bin/stattree:
 - more comments
 - some changes in filename matching regexps (finer grained now)
 - added general mechanism which triggers functions on occurence of
   some tagCanon elements in tag files. This allows me to notice
   tag files which have Documentation sections that I need to move to xmldocs.
 - better parsing of "gray" lines (those with code+inline comment)

- docbook/xmldocs.css: some nice tuning of CSS

- guides/programming-style.xml
 - very nice; made notes about few things not to do if you dont want to
   break xmldocs code parser, and added code examples

- images/*:
 - made those bulky prev/up/home/next images much nicer

Revision  Changes    Path
1.55      +1 -1      xmldocs/Makefile


rev 1.55, prev_rev 1.54
Index: Makefile
===================================================================
RCS file: /var/cvs/xmldocs/Makefile,v
retrieving revision 1.54
retrieving revision 1.55
diff -u -r1.54 -r1.55
--- Makefile	2 Feb 2005 11:35:58 -0000	1.54
+++ Makefile	3 Feb 2005 15:30:35 -0000	1.55
@@ -13,7 +13,7 @@
 #############################################################
 # Base definitions
 SYMBOL_TYPES= pragmas vars tags confs filters
-GUIDES      = iccattut xmldocs programming-style
+GUIDES      = iccattut programming-style
 HOWTOS      = howtos
 GLOSSARY    = glossary
 ALL_DOCS    = $(GLOSSARY) $(HOWTOS) $(GUIDES) $(SYMBOL_TYPES)



1.37      +101 -37   xmldocs/bin/stattree


rev 1.37, prev_rev 1.36
Index: stattree
===================================================================
RCS file: /var/cvs/xmldocs/bin/stattree,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -r1.36 -r1.37
--- stattree	1 Feb 2005 21:35:07 -0000	1.36
+++ stattree	3 Feb 2005 15:30:35 -0000	1.37
@@ -40,8 +40,9 @@
 my %resolver_path; # Support for stack (a -> b -> c -> d   =>
                    # a = d with full "path" recorded). This expands MapRoutines.
 
-# All file types should be listed here or the stats wont. It should be
-# reported if an unknown file is found in the archive
+# 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 
+# see that output with -v).
 # Order is important. First match wins.
 my %binary_types = (
 	images => [qw/\.gif \.jpeg \.jpg \.png \.bmp/],
@@ -54,22 +55,29 @@
 	build_helpfile => [qw/configure ^debian.* ^SPECS.*/],
 	catalog_helpfile => [qw/\.access \.log \.error \.(auto)?number \.empty/],
 	config => [qw/\.cfg \.dist/],
-	c => [qw/\.c \.in/],
+	c => [qw/\.c [^A-Z]\.in/],
 	perl => [qw/\.pl \.pm/],
 	uitag => [qw|UI_Tag/\S+\.(core)?tag dist/lib/UI/usertag/\S+|],
 	systemtag => [qw|SystemTag/\S+\.(core)?tag|],
 	usertag => [qw|UserTag/\S+\.tag \.tag|],
 	filter => [qw/\.filter/],
 	actionmap => [qw/\.am/],
-	html => [qw/\.css \.html?/],
+	html => [qw/\.html?/],
 	widget => [qw/\.widget/],
 	profile => [qw|/profiles/.+ \.profiles \.login \.order|],
 	globalsub => [qw|/globalsub/.+|],
 	variable => [qw|/vars/.+ /variables/.+|],
 );
 
+# Only add items here if you want to provide sub{} for them which gets
+# triggered when they're found in source.
+my %tagCanon = (
+  documentation => sub{$verbose and warn "${$_[0]}{file} CONTAINS DOCS\n" },
+);
 
 # A general overview: how many different contents do we have
+# This part of the statistic ( $hash{total} ) should be processed by
+# bin/mkreport once.
 my $binary_types;
 my $ascii_types;
 for ( keys %binary_types ) { $binary_types += scalar @{ $binary_types{$_} } }
@@ -87,7 +95,7 @@
 @ARGV == 1 or die "Usage: $0 path[/] \n";
 
 # $path is the directory to process, $dumppath is relocated name, say
-# sources/cvs-head becomes output/cvs-head/cache
+# sources/cvs-head becomes cvs-head/cache/.cache.bin
 my $path = shift;
 ( my $dumppath = $path ) =~ s#.+?/##;
 my $dumpdir = $dumppath; # Directory to dump to, without file name
@@ -119,7 +127,7 @@
 
 # Convenient routine to just discover all files
 find({
-	wanted => \&wanted,
+	wanted => \&wanted, # <-- all the work is done here
 	bydepth => 0,
 	no_chdir=> 1,
 }, ".");
@@ -154,6 +162,7 @@
 		$hash{total}{directories}++;
 		$hash{tree}{$file}{type} = "directory";
 		return; # This is enough for directories
+
 	} else {
 		$hash{total}{files}++;
 		$hash{total}{size} += (stat _)[7];
@@ -167,10 +176,10 @@
 		ctime => (stat _)[10],
 	};
 
+
 	#
 	# Make sure the file extension is known (we're entering
 	# content-based processing now, not filename-based as above).
-
 	my $ftype;
 	my $fsubtype;
 	my $fext;
@@ -196,13 +205,16 @@
 	# even if we're not interested in some files, they *should* be matched
 	# in %ascii_types/%binary_types above to provide accurate statistics.
 	print STDERR "$file UNKNOWN\n" if $verbose;
-	return; # We're not interested in handling that
-
+	return; # We're not interested in handling unknown stuff (there should
+	        # be no single file matching this when the stattree gets
+	        # sophisticated enough)
 	EXTDONE:
+	##  At this point, file, ftype, fsubtype and fext are known.     ##
+	##  file is filename, ftype is binary/ascii, fsubtype is key in  ##
+	##  %ascii_types/%binary_types hash, fext is extension           ##
+
 
-	# file, ftype, fsubtype and fext are known here.
-	# file is filename, ftype is binary/ascii, fsubtype is key in 
-	# %ascii_types/%binary_types hash, fext is extension
+	# General statistics
 	$hash{total}{$ftype."_files"}++;
 	$hash{total}{filetypes}{$fsubtype}++;
 	$hash{total}{matches}{$fext}++;
@@ -210,24 +222,31 @@
 	$hash{tree}{$file}{subtype} = "$fsubtype";
 	$hash{tree}{$file}{ext} = "$fext";
 
-	# No more job with binary files
-	return if $ftype eq 'binary';
+	return if $ftype eq 'binary'; # No more job with binary files
+
 
 	# Also ignore some directories (don't parse contents in them)
-	# (following a -core discussion from Aug 2004).
+	# (following a -core discussion from Aug 2004). This is OK to do here
+	# because those files already did their job as part of the general
+	# statistic.
 	return if $file =~ m#^(eg|extra|SPECS|debian|scripts|extensions)/#;
 
+
 	# Open text file, parse contents
 	open IN, "< $file" or die "Can't open $file ($!)\n";
 	my @filedata = <IN>;
 	unshift @filedata, ""; # Match index numbers with line numbers # MINUS
 	close IN;
 
+
 	# Global variables to use in the loop below
-	my @gfunc = (qw/unknown 0/); # 2 elements: func name, line num
+	my @gfunc = (qw/unknown 0/); # keep track of func name & line num,
+	                             # if it appears in the file
 
 	# Prepare context hash so that all data is available to the
-	# line handler functions later
+	# line handler functions later. This is not all; some more is 
+	# initialized/updated as the loop below iterates
+	# (line numbers, for example).
 	my %c = ( 
 		file => $file,
 		ftype => $ftype,
@@ -240,6 +259,16 @@
 	);
 
 
+	# And here we go. We start parsing the file. Note that this gets a little
+	# ugly here. The loop is supposed to run all code for each line. This 
+	# leads us to three main program flows:
+	#  a) this main loop parses line by line, in each iteration the appropriate
+	#     regex/condition matches and that's it.
+	#  b) we detect a particular file type and we jump out to a custom parse
+	#     routine that parses the whole file and ends this first loop.
+	#  c) we parse line-by-line for a while, until we match something interesting
+	#     and *then* jump to custom parse routine.
+	#
 	for (my $lnum = 1; $lnum < scalar @filedata; $lnum++) {
 		$c{line} = $filedata[$lnum];
 		$c{lnum} = $lnum;
@@ -251,48 +280,62 @@
 			die;
 		};
 
+		# Again, general code statistics
 		$hash{tree}{$file}{lines}++ ;
 		$hash{total}{lines}++ ;
 
-		# BLEH!
+		# BLEH! Workaround issue with 4.6.0
 		last if $i{ver} eq '4.6.0'
 			and $c{file} =~ /Tagref\.pm$/ and $c{line} =~ /^__DATA__$/;
 
+
+		################################################################
 		# Perl program file
 		if ( $c{fsubtype} eq 'perl' ) {
 			my $pod = 0;
-			if ( $c{line} =~ /^\s*#/ ) {
+
+			if ( $c{line} =~ /^\s*#/ ) {         # commented line
 				$hash{tree}{$c{file}}{comments}++ ;
 				$hash{total}{perl_comments}++;
-				# TODO check if the comment contains ::log[A-Z]\w+
-				# to discover calls to logGlobal/logDebug/logError
-			} elsif ( $c{line} =~ /\s+#/ ) {
+				# PLANNED check if the comment contains ::log[A-Z]\w+
+				# to discover calls to logGlobal/logDebug/logError.
+				# I don't plan this anymore since wasn't there some talk
+				# on replacing those hack routines with some formal logging?
+
+			} elsif ( $c{line} =~ /\s+(?<!s)#/ ) {     # code + inline comment
 				$hash{tree}{$c{file}}{gray}++ ;
 				$hash{total}{perl_gray}++;
-			} elsif ( $c{line} =~ /^=(head|over|item)/) {
+				$c{line} =~ s/#.*//; # Remove inline comment
+				goto PERLCODE;       # Parse as if it was plain code line
+				
+			} elsif ( $c{line} =~ /^=(head|over|item)/) { # begin of POD
 				$hash{tree}{$c{file}}{pod}++;
 				$hash{total}{perl_pod}++;
 				$pod++;
-			} elsif ( $c{line} =~ /^=cut/) {
+				
+			} elsif ( $c{line} =~ /^=cut/) { # End of POD
 				$hash{tree}{$c{file}}{pod}++;
 				$hash{total}{perl_pod}++;
 				$pod = 0;
-			} elsif ( $c{line} =~ /^\s*$/ ) {
+				
+			} elsif ( $c{line} =~ /^\s*$/ ) { # Empty line
 				$hash{tree}{$c{file}}{empty}++;
 				$hash{total}{perl_empty}++;
-			} elsif ( ! $pod ) {
+				
+			} elsif ( ! $pod ) { # Pure code line, with no inline comment
 				# The default is code
 				$hash{tree}{$c{file}}{code}++;
 				$hash{total}{perl_code}++;
+				PERLCODE:
 
-				line_findFunctionName(\%c);
+				line_findFunctionName(\%c); # See if a function begins on that line
 
 				line_findPragmas(\%c);
 				line_findGlobVars(\%c);
 				line_findCatVars(\%c);
 
 			} else {
-				warn "IMPOSSIBLE case in $file\n";
+				die "IMPOSSIBLE case in $file:$c{file}:$c{lnum} -- $c{line}\n";
 			}
 
 		##########################################################
@@ -307,8 +350,9 @@
 				warn "I know $c{file} is a tag but regex doesn't match it\n";
 			}
 
-			my %specific; # Item-specific data
-			my @tags; # Support multiple tags defined in the same file
+			my %specific; # Item-specific data # Pretty ugly hack
+			my @tags; # Support multiple tags defined in the same file. Heh, had
+			          # my share of effort to hack this in.
 
 			# This is where we parse the tag file. We should discover settings like
 			# HasEndTag, Order, and so on.
@@ -316,14 +360,28 @@
 				my $_l = $filedata[$lnum];
 				next unless $_l =~ /^usertag\s/i;
 				my @lis = split /\s+/, $_l;
-				shift @lis; # Remove "Usertag" which is first in the list
+
+				# Remove "Usertag" which is first in the list. (Safety check
+				# done just above so we can go ahead unconditionally)
+				shift @lis;
 
 				# Tag name as really defined, not just the file name
 				# (Most often, the difference is in _ and -).
+				# See if this is ok, or makes only problems (since ITL is 
+				# dash-insensitive anyway).
 				my $tn = shift @lis;
 
 				my $tagopt = lc(shift @lis);
-				next if $tagopt =~ /^documentation$/;
+				# Check if there's a sub defined for this $tagopt.
+				$tagCanon{lc $tagopt} and &{ $tagCanon{lc $tagopt} }(\%c);
+				
+				next if $tagopt =~ /^documentation$/; # Docs sections are ignored
+				# in a way that the dony begin with ^UserTag so they're completely
+				# disregarded.
+
+
+				#
+				# Now follows a SWITCH series, based on value of $tagopt.
 
 				# See if it's a routine and parse routine lines as usual perl lines
 				if ( $tagopt =~ /^routine$/ and "@lis" =~ /\s*<<(\S+)\s*$/i ) {
@@ -359,7 +417,11 @@
 				}
 
 				# New tag name we didn't see yet
-				# (either first run or another tag definition in the same file)
+				# (either first run or another tag definition in the same file).
+				# We'll record all of them in @tags, then create appropriate records
+				# for each. Body will be shared, this just ensures that they are
+				# recognized under different names (that no tags 'slip through' as
+				# being undetected if they disguise themselves inside a "host" file).
 				{ no warnings;
 				if (!grep{/^$tn$/}@tags and $lis[0] !~ /^alias$/i) { push @tags, $tn }
 				}
@@ -421,7 +483,8 @@
 			$hash{total}{$fsubtype . "s"}++;
 			last;
 		}
-	} # END FOR each line
+	} # END of 'FOR each (line of file)'
+
 
 	# Now in addition to above general line-by-line processing, do some more
 	# processing on exactly *some* files:
@@ -506,9 +569,9 @@
 	
 	# This matches $::Pragma->{} or $$::Pragma{}
 	#if ( $line =~ /(()|\$())\$::Pragma(->\2|\3){(\w+?)}/ ) {
+	#push @{ $hash{symbols}{pragma}{$5} },
 	if ( $c{line} =~ /\$::Pragma->{(\w+?)}/ or         
 			$c{line} =~ /\$Vend::Cfg->{Pragma}{(\w+?)}/ ) {
-	#push @{ $hash{symbols}{pragma}{$5} }, <- for use with above
 		push @{ $hash{symbols}{pragma}{$1} }, {
 	# TODO Here, and 2 places below: make sure if ctx is say, 5:5,
 	# it always shows that much (that is, workaround file beginning/
@@ -543,7 +606,7 @@
 
 sub line_findCatVars {
 	######################################################
-	# Diskover global variables
+	# Diskover catalog variables
 	my %c = %{ (shift) };
 	my $context_data = shift;
 
@@ -642,7 +705,7 @@
 	$hash{total}{functions}++;
 }
 
-
+# Parse Config.pm and take out some great stuff ;-)
 sub file_parseVendConfig {
 	my %c = %{ (shift) };
 	my $content = shift; # Complete lib/Vend/Config.pm file
@@ -753,6 +816,7 @@
 }
 
 
+# This is basically an excersize in bracket-matching
 sub file_extractSub {
 	my $tagname = shift;
 	my $func = shift;



1.20      +5 -5      xmldocs/docbook/xmldocs.css


rev 1.20, prev_rev 1.19
Index: xmldocs.css
===================================================================
RCS file: /var/cvs/xmldocs/docbook/xmldocs.css,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- xmldocs.css	3 Jan 2005 20:36:39 -0000	1.19
+++ xmldocs.css	3 Feb 2005 15:30:35 -0000	1.20
@@ -227,7 +227,7 @@
 	/*background-color: #e5e5e5;*/
 	/*background-color: #f7e8e8;*/
 	padding: 4px 4px 4px 4px;
-	border-left: dashed 1px #ffd1d1;
+	border-left: dashed 1px #ff8300; /*#ffd1d1;*/
 	padding-left: 8px;
 	margin: 0;
 }
@@ -237,11 +237,11 @@
 	margin-bottom: 0;
 	/*background-color: #e8b9b9;*/
 	/*background-color: #ffd1d1;*/
-	border: dashed 1px #ffd1d1;
+	border: dashed 1px #ff8300; /*#ffd1d1;*/
 }
 
 .example p {
-	border-left: dashed 1px #ffd1d1;
+	border-left: dashed 1px #ff8300; /*#ffd1d1;*/
 	padding: 10px 0px 10px 4px;
 	margin: 0;
 }
@@ -258,9 +258,9 @@
 }
 
 .code {
-	background-color: #e5e5e5;
+	background-color: #e0e0e0;
 	padding: 1px 1px 1px 1px;
-	border: dashed 1px white;
+	border: dotted 1px #208cb0;
 }
 
 .option {



1.1                  xmldocs/glossary/attribute


rev 1.1, prev_rev 1.0
Index: attribute
===================================================================

&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 -->

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
&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>.
This effectively allows you to have different product options for different
or even same product &glos-SKU;s. Those specified in <mv>mv_UseModifier</mv> at
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>
places each ordered item on a separate line even if they have the same
&glos-SKU;, simplifying attribute handling.
</para><para>
The modifier value is accessed in the &tag-item-list; loop with the
<code>[item-modifier <replaceable>attribute_name</replaceable>]</code> tag,
and form input fields are created with
<code>[modifier-name <replaceable>attribute</replaceable>]</code>.
This is similar to the way that quantity
is handled, except that attributes can be "stacked" by setting multiple
values in an input form (whereas there can be only one quantity field
for each item).
</para><para>
When you want to provide a series of modifiers for an element, 
you can use the standard &tag-loop; tag (such as
<code>[loop arg="<replaceable>item item item</replaceable>"]</code>),
or you can use the built-in &tag-PREFIX-accessories; tag available with
most &IC; list operations.
The modifier value can then be used to select data from an arbitrary database
for attribute selection and display.
</para>
<para>
Below is a fragment from a shopping basket display form which 
shows a selectable size with "sticky" setting. Note that the example
can only work within the &tag-item-list; tag.
</para>

<programlisting><![CDATA[
  <select name="[modifier-name size]">
  <option [selected [modifier-name size] S]  /> S
  <option [selected [modifier-name size] M]  /> M
  <option [selected [modifier-name size] L]  /> L
  <option [selected [modifier-name size] XL] /> XL
  </select>
]]></programlisting>

<para>
It could just as easily be done with a radio button group as well
(when you combine them with the &lt;checked&gt; &glos-HTML; tag.
</para><para>
In addition, &IC; would automatically generate the above select box
if you called <code>[accessories <replaceable>code</replaceable> size]</code>
or <code>[item-accessories size]</code>.

<!--
>   [item_accessories attribute*, type*, field*, database*, name*, outboard*]
>
>   [accessories code attribute*, type*, field*, database*, name*, outboard*]

=over 4

=item code

Not needed for item-accessories, this is the product code of the item to
reference.
 
=item attribute

The item attribute as specified in the UseModifier configuration
directive. Typical are C<size> or C<color>.

=item type

The action to be taken. One of:

>  select          Builds a dropdown <SELECT> menu for the attribute.
>                  NOTE: This is the default.
>
>  multiple        Builds a multiple dropdown <SELECT> menu for the
>                  attribute.  The size is equal to the number of
>                  option choices.
>
>  display         Shows the label text for *only the selected option*.
>
>  show            Shows the option choices (no labels) for the option.
>
>  radio           Builds a radio box group for the item, with spaces
>                  separating the elements.
>
>  radio nbsp      Builds a radio box group for the item, with &nbsp;
>                  separating the elements.
>
>  radio left n    Builds a radio box group for the item, inside a
>                  table, with the checkbox on the left side. If "n"
>                  is present and is a digit from 2 to 9, it will align
>                  the options in that many columns.
>
>  radio right n   Builds a radio box group for the item, inside a
>                  table, with the checkbox on the right side. If "n"
>                  is present and is a digit from 2 to 9, it will align
>                  the options in that many columns.

>
>  check           Builds a checkbox group for the item, with spaces
>                  separating the elements.
>
>  check nbsp      Builds a checkbox group for the item, with &nbsp;
>                  separating the elements.
>
>  check left n    Builds a checkbox group for the item, inside a
>                  table, with the checkbox on the left side. If "n"
>                  is present and is a digit from 2 to 9, it will align
>                  the options in that many columns.
>
>  check right n   Builds a checkbox group for the item, inside a
>                  table, with the checkbox on the right side. If "n"
>                  is present and is a digit from 2 to 9, it will align
>                  the options in that many columns.

The default is 'select', which builds an HTML select form entry for
the attribute.  Also recognized is 'multiple', which generates a
multiple-selection drop down list, 'show', which shows the list of
possible attributes, and 'display', which shows the label text for the
selected option only.

=item field

The database field name to be used to build the entry (usually a field
in the products database).  Defaults to a field named the same as the
attribute.

=item database

The database to find B<field> in, defaults to the first products file
where the item code is found.

=item name

Name of the form variable to use if a form is being built. Defaults to
mv_order_B<attribute> - i.e.  if the attribute is B<size>, the form
variable will be named B<mv_order_size>.

=item outboard

If calling the item-accessories tag, and you wish to select from an
outboard database, you can pass the key to use to find the accessory
data.

=back

When called with an attribute, the database is consulted and looks for
a comma-separated list of attribute options. They take the form:

>    name=Label Text, name=Label Text*

The label text is optional - if none is given, the B<name> will
be used.

If an asterisk is the last character of the label text, the item is
the default selection. If no default is specified, the first will be
the default. An example:

>    [item_accessories color]

This will search the product database for a field named "color". If
an entry "beige=Almond, gold=Harvest Gold, White*, green=Avocado" is found,
a select box like this will be built:

>    <SELECT NAME="mv_order_color">
>    <OPTION VALUE="beige">Almond
>    <OPTION VALUE="gold">Harvest Gold
>    <OPTION SELECTED>White
>    <OPTION VALUE="green">Avocado
>    </SELECT>

In combination with the C<mv_order_item> and C<mv_order_quantity> variables
this can be used to allow entry of an attribute at time of order.

If used in an item list, and the user has changed the value, the generated
select box will automatically retain the current value the user has selected.

The value can then be displayed with C<[item-modifier size]> on the
order report, order receipt, or any other page containing an
C<[item-list]>. 

-->



1.2       +70 -0     xmldocs/guides/programming-style.xml


rev 1.2, prev_rev 1.1
Index: programming-style.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/programming-style.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- programming-style.xml	1 Feb 2005 21:30:11 -0000	1.1
+++ programming-style.xml	3 Feb 2005 15:30:36 -0000	1.2
@@ -103,6 +103,15 @@
 		and white space around operators increases readability.
 		Lining up <literal>=</literal>s in a series of assignments can be
 		used to emphasize the parallel structure.
+<programlisting><![CDATA[
+sub init_calc {
+#::logDebug("reset_state=$Vend::Calc_reset init_state=$Vend::Calc_initialized -- initting calc from " . caller);
+	reset_calc() unless $Vend::Calc_reset;
+	$CGI_array  = \%CGI::values_array;
+	$CGI        = \%CGI::values;
+	$Carts      = $::Carts;
+	$Items      = $Vend::Items;
+]]></programlisting>
 	</para></listitem>
 
 	<listitem><para>
@@ -113,6 +122,10 @@
 		Items in the main package should be referenced as
 		<literal>$::<replaceable>Foo</replaceable></literal>, not
 		<literal>$main::<replaceable>Foo</replaceable></literal>.
+<programlisting>
+## Allow no substitution of downloads
+return if $::Pragma->{download};
+</programlisting>
 	</para></listitem>
 
 	<listitem><para>
@@ -168,6 +181,12 @@
 		With non-container tags, such as &lt;input&gt;, &lt;br&gt; or &lt;hr&gt;,
 		a new &glos-pragma; will be introduced to automatically replace the 
 		closing <literal>&gt;</literal> with <literal>/&gt;</literal>.
+<programlisting><![CDATA[
+<form action="[process]">
+  <input type="text"   name="city" value="[value city]" >
+  <input type="submit"             value=" Submit "     >
+</form>
+]]></programlisting>
 	</para></listitem>
 
 <!--
@@ -179,8 +198,59 @@
 -->
 
 </itemizedlist>
+</sect1>
+
+
+<sect1 id='XMLDOCS'>
+	<title>XMLDOCS notes</title>
 
+	<para>
+	As you might know, XMLDOCS documentation system contains 
+	<filename>bin/stattree</filename> script which parses complete &IC;
+	source tree. Although I really tried to make it recognize code regardless
+	of formatting (much like &PERL; interpreter does), there are still some
+	little suggestions on the programming style to make it easier for XMLDOCS.
+	</para>
+
+	<itemizedlist>
+		<listitem><para>
+		Do not use the hash character <literal>#</literal> in weird contexts.
+		Use it only for comments (putting a space between eventual inline code and
+		comment) or simple substitution such as <literal>s#A#B#g</literal>.
+		(Impact: cosmetic)
+<programlisting><![CDATA[
+# Line comment
+my $test = 12; # Only used for test
+]]></programlisting>
+		</para></listitem>
+		<listitem><para>
+		Do not break word <literal>sub</literal> and subroutine name to separate
+		lines.
+		<code>sub test....</code> is OK, <code>sub \n test</code> is NOT.
+		(Impact: might confuse function tracking code)
+<programlisting><![CDATA[
+sub test1 {
+
+sub test2
+{
+]]></programlisting>
+		</para></listitem>
+		<listitem><para>
+		Do not break obviously "solid" blocks of code to multiple lines. To give
+		you an idea of what I am talking about, let's say you should not break
+		typical xmldocs regexps, such as <literal>/\$::Pragma->{(\w+?)}/</literal>
+		or <literal>/\$Vend::Cfg->{Pragma}{(\w+?)}/</literal>.
+<programlisting><![CDATA[
+return if $::Pragma->{download};
+
+if (
+  $Vend::Cfg->{Pragma}{download}
+  ) {
+]]></programlisting>
+		</para></listitem>
+	</itemizedlist>
 </sect1>
+
 
 </article>
 



1.12      +0 -2      xmldocs/guides/xmldocs.xml


rev 1.12, prev_rev 1.11
Index: xmldocs.xml
===================================================================
RCS file: /var/cvs/xmldocs/guides/xmldocs.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- xmldocs.xml	1 Feb 2005 21:30:11 -0000	1.11
+++ xmldocs.xml	3 Feb 2005 15:30:36 -0000	1.12
@@ -1,5 +1,3 @@
-</sect1>
-
 <sect1 id='XMLGuidelines'>
 	<title>XML Guidelines</title>
 



1.3       +6 -5      xmldocs/images/home.gif


<<home.gif: GIF image data, version 89a, 20 x 19>>


1.2       +5 -3      xmldocs/images/home.png


<<home.png: PNG image data, 20 x 19, 8-bit/color RGBA, non-interlaced>>


1.2       +2 -2      xmldocs/images/new.png


<<new.png: PNG image data, 28 x 10, 8-bit colormap, non-interlaced>>


1.2       +1 -7      xmldocs/images/next.gif


<<next.gif: GIF image data, version 89a, 22 x 9>>


1.2       +2 -2      xmldocs/images/next.png


<<next.png: PNG image data, 22 x 9, 8-bit/color RGBA, non-interlaced>>


1.2       +4 -8      xmldocs/images/prev.gif


<<prev.gif: GIF image data, version 89a, 22 x 8>>


1.2       +2 -1      xmldocs/images/prev.png


<<prev.png: PNG image data, 22 x 8, 8-bit/color RGBA, non-interlaced>>


1.3       +4 -10     xmldocs/images/up.gif


<<up.gif: GIF image data, version 89a, 8 x 24>>


1.2       +1 -1      xmldocs/images/up.png


<<up.png: PNG image data, 8 x 24, 8-bit/color RGBA, non-interlaced>>







More information about the docs mailing list