sqlpostgres 1.2.4

data/tools/rdoc/README

@@ -0,0 +1,390 @@
+= RDOC - Ruby Documentation System
+
+This package contains Rdoc and SimpleMarkup. Rdoc is an application
+that produces documentation for one or more Ruby source files. We work
+similarly to JavaDoc, parsing the source, and extracting the
+definition for classes, modules, and methods (along with includes and
+requires).  We associate with these optional documentation contained
+in the immediately preceding comment block, and then render the result
+using a pluggable output formatter. (Currently, HTML is the only
+supported format. Markup is a library that converts plain text into
+various output formats. The Markup library is used to interpret the
+comment blocks that Rdoc uses to document methods, classes, and so on.
+
+
+== Installation
+
+This distribution contains two packages, rdoc itself and a text markup
+library, 'markup'. You can install them both using the single command
+
+  % ruby install.rb
+
+in this directory. If you just want to install 'markup', change to the
+markup directory and run the install.rb script there.
+
+
+== Roadmap
+
+* If you want to use Rdoc to create documentation for your Ruby source
+  files, read on.
+* If you want to include extensions written in C, see rdoc/parsers/parse_c.rb.
+* For information on the various markups available in comment
+  blocks, see markup/simple_markup.rb.
+* If you want to drive Rdoc programatically, see RDoc::RDoc.
+* If you want to use the library to format text blocks into HTML,
+  have a look at SM::SimpleMarkup.
+* If you want to try writing your own HTML output template, see
+  RDoc::Page.
+
+== Summary
+
+Once installed, you can create documentation using the 'rdoc' command
+(the command is 'rdoc.rb' under Windows)
+
+  % rdoc [options]  [names...]
+
+Type "rdoc --help" for an up-to-date option summary.
+
+A typical use might be to generate documentation for a package of Ruby
+source (such as rdoc itself). 
+
+  % rdoc
+
+This command generates documentation for all the Ruby and C source
+files in and below the current directory. These will be stored in a
+documentation tree starting in the subdirectory 'doc'.
+
+You can make this slightly more useful for your readers by having the
+index page contain the documentation for the primary file. In our
+case, we could type
+
+  % rdoc --main rdoc/rdoc.rb
+
+You'll find information on the various formatting tricks you can use
+in comment blocks in the documentation this generates.
+
+RDoc uses file extensions to determine how to process each file. File
+names ending <tt>.rb</tt> and <tt>.rbw</tt> are assumed to be Ruby
+source. Files ending <tt>.c</tt> are parsed as C files. All other
+files are assumed to contain just SimpleMarkup-style markup (with or
+without leading '#' comment markers). If directory names are passed to
+RDoc, they are scanned recursively for C and Ruby source files only.
+
+== Credits
+
+* The Ruby parser in rdoc/parse.rb is based heavily on the outstanding
+  work of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby
+  parser for irb and the rtags package.
+
+* Code to diagram classes and modules was written by Sergey A Yanovitsky
+  (Jah) of Enticla. 
+
+* Charset patch from MoonWolf.
+
+* Rich Kilmer wrote the kilmer.rb output template.
+
+* Dan Brickley led the design of the RDF format.
+
+== License
+
+RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers.  It
+is free software, and may be redistributed under the terms specified
+in the README file of the Ruby distribution.
+
+
+== Support
+
+The Rdoc homepage is http://rdoc.sourceforge.net. There you'll find
+links for downloading the Rdoc package, and instructions on how to get
+the still-quivering sources from CVS. I'm also using Sourceforge to
+track bugs and manage feature requests. If you submit patches, it
+would help if they were inline (not attachments) and generated using
+"diff -u".  I don't have access to a wide variety of browsers, so
+reports that output looks funny under Browser XYZ aren't too helpful:
+far better are suggested changes to the generated HTML that fix the
+problem.
+
+For other information, feel free to ask on the ruby-talk mailing list
+(which is mirrored to comp.lang.ruby) or contact
+mailto:dave@pragmaticprogrammer.com.
+
+----
+
+= Usage
+
+RDoc is invoked from the command line using:
+
+   % rdoc <options> [name...]
+
+Files are parsed, and the information they contain collected, before
+any output is produced. This allows cross references between all files
+to be resolved. If a name is a directory, it is traversed. If no
+names are specified, all Ruby files in the current directory (and
+subdirectories) are processed.
+
+Options are:
+
+[<tt>--all</tt>]
+    include protected and private methods in the output (by default
+    only public methods are included)
+
+[<tt>--main</tt> _name_]
+    set the class, module, or file to appear on the index page
+
+[<tt>--exclude</tt> <i>pattern</i>]
+    exclude files and directories matching this pattern from processing
+
+[<tt>--quiet</tt>]
+    do not display progress messages
+
+[<tt>--one-file</tt>]
+    place all the output into a single file
+
+[<tt>--op</tt> _dir_]
+    set the output directory to _dir_ (the default is the directory
+    "doc")
+
+[<tt>--opname</tt> _name_]
+    set the output name (has no effect for HTML).
+
+[<tt>--charset</tt> _charset_]
+    Set the character set for the generated HTML.
+
+[<tt>--fmt</tt> _fmt_]
+    generate output in a particular format.
+
+[<tt>--include</tt> <i>dir,...</i>]
+    specify one or more directories to be searched when satifying
+    :include: directives. Multiple <tt>--include</tt> options may be
+    given. The directory containing the file currently being processed
+    is always searched.
+
+[<tt>--inline-source</tt>]
+    By default, the source code of methods is shown in a popup. With
+    this option, it's displayed inline.
+
+[<tt>--show-hash</tt>]
+    A name of the form #name in a comment is a possible hyperlink to
+    an instance method name. When displayed, the '#' is removed unless
+    this option is specified
+
+[<tt>--template</tt> <i>name</i>]
+    specify an alternate template to use when generating output (the
+    default is 'standard'). This template should be in a directory
+    accessible via $: as rdoc/generators/xxxx_template, where 'xxxx'
+    depends on the output formatter.
+
+[<tt>--diagram</tt>]
+    include diagrams showing modules and classes.  This is currently
+    an experimental feature, and may not be supported by all output
+    templates. You need dot V1.8.6 or later to use the --diagram
+    option correctly (http://www.research.att.com/sw/tools/graphviz/).
+
+= Example
+
+A typical small Ruby program commented using RDoc might be as follows. You
+can see the formatted result in EXAMPLE.rb and Anagram.
+
+      :include: EXAMPLE.rb
+
+= Markup
+
+Comment blocks can be written fairly naturally. 
+
+Paragraphs are lines that share the left margin. Text indented past
+this margin are formatted verbatim.
+
+1. Lists are typed as indented paragraphs with:
+   * a '*' or '-' (for bullet lists)
+   * a digit followed by a period for 
+     numbered lists
+
+   For example, the input that produced the above paragraph looked like
+       1. Lists are typed as indented 
+          paragraphs with:
+          * a '*' or '-' (for bullet lists)
+          * a digit followed by a period for 
+            numbered lists
+
+2. Labeled lists (sometimes called description
+   lists) are typed using square brackets for the label.
+      [cat]   small domestic animal
+      [+cat+] command to copy standard input
+
+3. Labeled lists may also be produced by putting a double colon
+   after the label. This sets the result in tabular form, so the
+   descriptions all line up. This was used to create the 'author'
+   block at the bottom of this description.
+      cat::   small domestic animal
+      +cat+:: command to copy standard input
+
+   For both kinds of labeled lists, if the body text starts on the same
+   line as the label, then the start of that text determines the block
+   indent for the rest of the body. The text may also start on the line
+   following the label, indented from the start of the label. This is
+   often preferable if the label is long. Both the following are
+   valid labeled list entries:
+
+      <tt>--output</tt> <i>name [, name]</i>::
+          specify the name of one or more output files. If multiple
+          files are present, the first is used as the index.
+
+      <tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
+                          index areas, or bit ratios of units as
+                          they are processed.
+
+4. Headings are entered using equals signs
+
+      = Level One Heading
+      == Level Two Heading
+   and so on
+
+5. Rules (horizontal lines) are entered using three or
+   more hyphens.
+
+6. Non-verbatim text can be marked up:
+
+   _italic_::     \_word_ or \<em>text</em>
+   *bold*::       \*word* or \<b>text</b>
+   +typewriter+:: \+word+ or \<tt>text</tt>
+
+   The first form only works around 'words', where a word is a
+   sequence of upper and lower case letters and underscores. Putting a
+   backslash before inline markup stops it being interpreted, which is
+   how I created the table above:
+
+     _italic_::     \_word_ or \<em>text</em>
+     *bold*::       \*word* or \<b>text</b>
+     +typewriter+:: \+word+ or \<tt>text</tt>
+
+7. Names of classes, source files, and any method names
+   containing an underscore or preceded by a hash
+   character are automatically hyperlinked from
+   comment text to their description. 
+
+8. Hyperlinks to the web starting http:, mailto:, ftp:, or www. are
+   recognized. An HTTP url that references an external image file is
+   converted into an inline <IMG..>.  Hyperlinks starting 'link:' are
+   assumed to refer to local files whose path is relative to the --op
+   directory.
+
+   Hyperlinks can also be of the form <tt>label</tt>[url], in which
+   case the label is used in the displayed text, and <tt>url</tt> is
+   used as the target.
+       
+9. Method parameter lists are extracted and displayed with
+   the method description. If a method calls +yield+, then
+   the parameters passed to yield will also be displayed:
+
+      def fred
+        ...
+        yield line, address
+
+   This will get documented as
+
+      fred() { |line, address| ... }
+
+   You can override this using a comment containing 
+   ':yields: ...' immediately after the method definition
+
+      def fred      # :yields: index, position
+        ...
+        yield line, address
+
+   which will get documented as
+
+       fred() { |index, position| ... }
+
+
+10. ':yields:' is an example of a documentation modifier. These appear
+    immediately after the start of the document element they are modifying.
+    Other modifiers include
+
+    [<tt>:nodoc:</tt><i>[all]</i>]
+         don't include this element in the documentation.  For classes
+         and modules, the methods, aliases, and attributes directly
+         within the affected class or module will also be omitted.  By
+         default, though, modules and classes within that class of
+         module _will_ be documented. This is turned off by adding the
+         +all+ modifier.
+
+              module SM  #:nodoc:
+                class Input
+                end
+              end
+              module Markup #:nodoc: all
+                class Output
+                end
+              end
+
+         In the above code, only class <tt>SM::Input</tt> will be
+         documented.
+
+    [<tt>:doc:</tt>]
+         force a method or attribute to be documented even if it
+         wouldn't otherwise be. Useful is, for example, you want to
+         include documentation of a particular private method.
+
+    [<tt>:notnew:</tt>]
+         only applicable to the +initialize+ instance method. Normally
+         RDoc assumes that the documentation and parameters for
+         #initialize are actually for the ::new method, and so fakes
+         out a ::new for the class. THe :notnew: modifier stops
+         this. Remember that #initialize is protected, so you won't
+         see the documentation unless you use the -a command line
+         option.
+
+
+11. RDoc stops processing comments if it finds a comment
+    line containing '<tt>#--</tt>'. This can be used to 
+    separate external from internal comments, or 
+    to stop a comment being associated with a method, 
+    class, or module. Commenting can be turned back on with
+    a line that starts '<tt>#++</tt>'.
+
+        # Extract the age and calculate the
+        # date-of-birth.
+        #--
+        # FIXME: fails if the birthday falls on
+        # February 29th
+        #++
+        # The DOB is returned as a Time object.
+
+        def get_dob(person)
+           ...
+
+12. Comment blocks can contain other directives:
+
+    [<tt>:include:</tt><i>filename</i>] 
+         include the contents of the named file at this point. The
+         file will be searched for in the directories listed by
+         the <tt>--include</tt> option, or in the current
+         directory by default.  The contents of the file will be
+         shifted to have the same indentation as the ':' at the
+         start of the :include: directive.
+
+    [<tt>:title:</tt><i>text</i>]
+         Sets the title for the document. Equivalent to the --title command
+         line parameter. (The command line parameter overrides any :title:
+         directive in the source).
+
+    [<tt>:main:</tt><i>name</i>]
+         Equivalent to the --main command line parameter.
+
+---
+
+See also markup/simple_markup.rb.
+
+= Other stuff
+
+Author::   Dave Thomas <dave@pragmaticprogrammer.com>
+Requires:: Ruby 1.6.5 or later
+License::  Copyright (c) 2001-2003 Dave Thomas.
+           Released under the same license as Ruby.
+
+== Warranty
+
+This software is provided "as is" and without any express or
+implied warranties, including, without limitation, the implied
+warranties of merchantibility and fitness for a particular
+purpose.

data/tools/rdoc/ToDo

@@ -0,0 +1,6 @@
+- the current HTML output is not particularly portable. I need someone 
+  who knows browsers to come up with some HTML that works everywhere.
+
+- add XML export (to drive UML generation tools among other things)
+
+- tidy parse.rb

data/tools/rdoc/contrib/Index

@@ -0,0 +1,6 @@
+Contributions to RDoc:
+
+xslfo/    Support for Formatting Objects, allowing RDoc to generate
+          output in PDF, PostScript, etc
+
+

data/tools/rdoc/contrib/xslfo/ChangeLog

@@ -0,0 +1,181 @@
+2002-03-20 18:42  wobblini
+
+	* convert.xsl, fcm.xsl, files.xsl, labeled-lists.xsl, modules.xsl,
+	rdoc.xsl, source.xsl: 
+	More tweaking of two-layered XSLT processing.
+
+2002-03-20 18:41  wobblini
+
+	* TODO: 
+	TODO file started
+
+2002-03-18 19:57  wobblini
+
+	* convert.xsl, fcm.xsl, files.xsl, modules.xsl, rdoc.xsl,
+	source.xsl, styles.xsl: 
+	Further changes in connection with doing two XSL transformations
+
+2002-03-17 21:38  wobblini
+
+	* lists.xsl: 
+	added CVS header
+
+2002-03-17 21:36  wobblini
+
+	* lists.xsl: 
+	should have been added before
+
+2002-03-17 21:28  wobblini
+
+	* ChangeLog: 
+	minor changes
+
+2002-03-17 21:28  wobblini
+
+	* demo/rdocfo: 
+	typo
+
+2002-03-17 21:26  wobblini
+
+	* demo/rdocfo: 
+	typo correction
+
+2002-03-17 21:24  wobblini
+
+	* demo/: README, rdocfo: 
+	rdocfo -- script to (semi-)automate XSL-FO production with Saxon.
+
+2002-03-17 17:01  wobblini
+
+	* README: 
+	minor changes
+
+2002-03-17 16:33  wobblini
+
+	* README, fcm.xsl, files.xsl, labeled-lists.xsl, modules.xsl,
+	rdoc.xsl, source.xsl, styles.xsl: 
+	Now using two transformations (see convert.xsl).  Handling of IDs
+	and cross-refs more nicely parameterized.
+
+2002-03-17 16:32  wobblini
+
+	* convert.xsl: 
+	Converts from default XML output to intermediate XML for input to
+	stylesheets.
+
+2002-03-12 11:57  wobblini
+
+	* files.xsl, labeled-lists.xsl, modules.xsl, rdoc.xsl, source.xsl: 
+	some further fine-tuning to get links working (most are)
+
+2002-03-11 17:12  wobblini
+
+	* ChangeLog, fcm.xsl, files.xsl, labeled-lists.xsl, modules.xsl,
+	rdoc.xsl, source.xsl, styles.xsl, tables.xsl: 
+	more minor changes.  normalized font sizes to "pt" values.
+
+2002-03-10 17:45  wobblini
+
+	* labeled-lists.xsl: 
+	New file with some old templates (refactoring file-wise).
+
+2002-03-10 16:58  wobblini
+
+	* fcm.xsl, files.xsl, modules.xsl, rdoc.xsl, source.xsl,
+	styles.xsl, tables.xsl: 
+	Continued work on start-indent and margin-left problems, especially
+	with tables and lists.	Beginnings of PDF links (working for master
+	file list, not for anything else).
+
+2002-03-06 16:11  wobblini
+
+	* README: 
+	Additional info on what you get in your XSL-FO file
+
+2002-03-06 16:06  wobblini
+
+	* ChangeLog: 
+	update
+
+2002-03-06 16:05  wobblini
+
+	* source.xsl: 
+	Handle source-code-listing elements in Class and Module elements
+
+2002-03-06 16:04  wobblini
+
+	* files.xsl, modules.xsl, rdoc.xsl, styles.xsl: 
+	Some refactoring, file-wise.  Also continued tinkering with
+	start-indent vs.  left-margin.
+
+2002-03-06 16:03  wobblini
+
+	* fcm.xsl: 
+	common template for file, class, module
+
+2002-03-03 19:27  wobblini
+
+	* README: 
+	Typo corrections
+
+2002-03-03 18:02  pragdave
+
+	* README: Convert to Simple Markup
+
+2002-03-03 08:40  wobblini
+
+	* ChangeLog: 
+	Now producing automated ChangeLog with cvs2cl.pl.
+
+2002-03-03 08:36  wobblini
+
+	* ChangeLog: [no log message]
+
+2002-03-03 08:31  wobblini
+
+	* tables.xsl: 
+	Added missing <fo:table-body> elements.
+
+2002-03-03 08:30  wobblini
+
+	* README: [no log message]
+
+2002-03-03 08:20  wobblini
+
+	* modules.xsl: 
+	Changed attribute-name to @name, as per change in the DTD.
+
+2002-03-02 23:33  wobblini
+
+	* ChangeLog: [no log message]
+
+2002-03-02 23:30  wobblini
+
+	* ChangeLog, files.xsl, modules.xsl, rdoc.xsl, tables.xsl: 
+	Added XSL tables to handle <table> and <dl> elements.
+
+2002-03-02 22:20  wobblini
+
+	* modules.xsl, styles.xsl: 
+	Getting the initial CVS commit right
+
+2002-03-02 22:19  wobblini
+
+	* files.xsl: 
+	Minor changes
+
+2002-03-02 17:20  wobblini
+
+	* rdoc.xsl, styles.xsl, modules.xsl: 
+	part of XSL-FO stylesheet suite
+
+2002-03-02 17:20  wobblini
+
+	* files.xsl: 
+	part of XSL-FO suite
+
+2002-03-02 17:18  wobblini
+
+	* README: 
+	Adding XSL-FO files to contrib/xslfo subdirectory.
+

data/tools/rdoc/contrib/xslfo/README

@@ -0,0 +1,106 @@
+= XSL-FO (Formatting Object) stylesheets for RDoc
+
+
+== WHAT
+
+This package provides XSL-FO transformation stylesheets to transform
+RDoc XML output into XSL formatting object (XSL-FO) files.  These
+files, in turn, can be processed to produce PDF, DVI, PostScript, and
+other types of output suitable for printing or viewing.
+
+The output you'll get (the XSL-FO file) is organized like this:
+
+     Title page
+     Files:
+       - list of files
+       - entry for each file with info and description
+     Classes:
+       - list of classes
+       - entry for each class
+     Modules:
+       - list of modules
+       - entry for each module
+     Source code for classes (sorted by class/method)
+     Source code for modules (sorted by module/method)
+
+
+== WHY
+
+XSL-FO is mainly for producing nicely formatted printed output.  The
+goal of these stylesheets is to enable people to do exactly that, with
+RDoc output.  You can also create a PDF version of RDoc output.  The
+PDF version includes internal links among files, classes, methods, and
+source code.
+
+
+== HOW
+
+To use these stylesheets, you need an XSLT processor, such as Michael
+Kay's Saxon (http://saxon.sourceforge.net).  You also need a
+post-processor for the XSL-FO files.  I've developed the stylesheets
+using PassiveTeX by Sebastian Rahtz.  PassiveTeX produces DVI files
+from XSL files; it also works in tandem with pdflatex to produce PDF
+output from XSL-FO input.
+
+Once you have the necessary tools in place, here's (an example of)
+what to do.
+
+1. Create an RDoc XML file:
+
+      rdoc --fmt xml > myfile.xml
+
+2. Run Saxon twice: first, on the existing XML file (which produces a
+   new XML file, which is needed by the XSL-FO stylesheets); second,
+   on the new XML file:
+
+      java com.icl.saxon.StyleSheet myfile.xml /path/to/convert.xsl > second.xml
+      java com.icl.saxon.StyleSheet second.xml /path/to/rdoc.xsl > myfile.fo
+
+    (Replace "/path/to/" with whatever's appropriate, of course.)
+
+    Now you have a file full of XSL-FO objects, in "myfile.fo".
+
+4. Run your postprocessing software on your .fo file.  For example, to
+   use PassiveTeX you would put this in a file (myfile.tex, say):
+
+      \def\xmlfile{myfile.fo}
+      \input xmltex.tex
+      \end{document}
+
+   and run LaTeX on it.  That will produce a DVI file (myfile.dvi).
+
+5. To get PDF output:
+
+      pdflatex "&pdfxmltex" myfile.fo
+
+   which will produce myfile.pdf.  You can also use the above myfile.tex
+   file and run:
+
+      pdflatex myfile
+
+6. You can also run your .fo file through FOP, Apache's XSL-FO
+   processor (http://xml.apache.org/fop) or any other XSL-FO
+   processor.  Note that FOP and PassiveTeX produce somewhat
+   different results.
+
+7. In the demo subdirectory, there's also a script called rdocfo,
+   which semi-automates the processing.  Run "rdocfo -h" to see
+   some options.
+
+
+== WHO
+
+ The RDoc XSL stylesheets are written and maintained by David Alan Black
+ (dblack@candle.superlink.net).  Feedback is welcome.
+
+
+== STILL TO COME
+
+See TODO.
+
+
+==== CVS info
+
+ $Id: README,v 1.1 2003/10/10 08:00:05 wconrad Exp $
+ $Author: wconrad $
+

data/tools/rdoc/contrib/xslfo/TODO

@@ -0,0 +1,10 @@
+XSL-FO stylesheets for RDoc
+David Alan Black
+
+$Id: TODO,v 1.1 2003/10/10 08:00:05 wconrad Exp $
+$Author: wconrad $
+
+
+* Method descriptions aren't being handled (oversight).
+* Source code annoying doesn't do line breaks on consecutive keywords
+