New options brief documentation, complete views example using DBCP.

I still have to add a chapter on relationshipo inference.

doc/cd-opt.xml

@@ -70,17 +70,32 @@ in this case it will hide everything (useful in the context of views
 to selectively unhide some portions of the graph, see the view chapter for
 further details).
 </dd>
-<dt>-hideall</dt><dd>Hide all entities from the graph.
-Used with views to show only a specific
-subset of classes in each class diagram.
-</dd>
 <dt>-d</dt><dd>Destination folder for .dot files generated from views.
 </dd>
-<dt>-view</dt><dd>Specify the fully qualified name of a class that contains a view definition.
-Only the class diagram specified by this view will be generated.
+<dt>-view</dt><dd>Specify the fully qualified name of a class that contains
+a view definition. Only the class diagram specified by this view will be generated. 
+<br/>See the views chapter for more details.
 </dd>
 <dt>-views</dt><dd>Generate a class diagram for every view found in the source path.
 </dd>
+<dt>-inferrel</dt><dd>Try to automatically infer relationships between classes by inspecting
+field values. See the class diagram inference chapter for further details. Disabled by default.
+</dd>
+<dt>-inferreltype</dt><dd>The type of relationship inferred when -inferrel is activated. 
+Defaults to "navassoc" (see the class modelling chapter for a list of relationship types).
+</dd>
+<dt>-inferdep</dt><dd>Try to automatically infer dependencies between classes by inspecting
+methods and fields. See the class diagram inference chapter for more details. Disabled by default.
+</dd>
+<dt>-useimports</dt><dd>Will also use imports to infer dependencies. 
+Disabled by default, since it does not work properly if there are multiple
+classes in the same source file (will add dependencies to every class in
+the source file).
+</dd>
+<dt>-collpackages</dt><dd>Specify the classes that will be treated as
+containers for one to many relationships when inference is enabled. 
+Matching is done using a non-anchored regular match. Empty by default.
+</dd>
 <dt>-apidocroot</dt><dd>Specify the URL that should be used as the "root" for local classes.
 This URL will be used as a prefix, to which the page name for the local class or
 package will be appended (following the JavaDoc convention).
@@ -113,7 +128,8 @@ a tripple specifying hue-saturation-brightness as values 0-1
 or a tripple specifying red-green-blue values as hexadecimal
 digits prefixed by a # (e.g. "#ff8020").
 The symbolic color names are derived from the X Windows System;
-you can find a complete list in the Graphviz documentation.
+you can find a complete list in the 
+<a href="http://www.graphviz.org/doc/info/colors.html">Graphviz documentation</a>
 <p />
 Font names are passed directly to the dot graph generation back-end.
 In general the Postcript standard names Times, Helvetica, Courier, and

doc/ceg-mvi.xml

@@ -6,14 +6,15 @@ each to show a specific and limited portion of the system.
 Each diagram is usually composed of few classes, possibily using a different detail level.<p/>
 The <code>@view</code> tag, marks a special class used to describe a single class diagram.
 Similarly to UMLOptions, the view can define its own general options,
-but what makes it interesting is the ability to specify package based 
-<em>overrides</em> that allow to adopt different options based on the package the classes are in.
+but allows to define <em>overrides</em> that allow to adopt different options 
+for different classes based on regular expressions matching.
 The general syntax for defining a view is:
 <fmtcode ext="java">
 /**
  * @view
  * @opt [!]viewOption1
  * @opt [!]viewOption2
+ * ...
  * @match regularExpression1
  * @opt [!]option1.1 [argument]
  * @opt [!]option1.2 [argument]
@@ -37,6 +38,15 @@ class documentation for details on a proper regular expression specification.
 <p/>Each view will generate a .dot file whose name is the name of the view,
 unless the "output" option is specified to override it.
 
+<h2>View inheritance</h2>
+
+View classes can inherit from other view classes, allowing views to
+share a set of common matches. The standard java inheritance mechanism
+is used to specify inheritance.<br/>
+Abstract view classes won't be used to generate diagrams, the common
+idiom is to declare a base abstract view to share common options and
+overrides, and have concrete view classes that extend for diagram generation.
+
 <h2>Example: views at different detail of specification</h2>
 
 The previous multiple view example can be generated by using internal
@@ -127,11 +137,106 @@ dot -Tpng -o root.png DetailedView.dot
 
 Views are especially interesting in big projects, since they allow to
 generate package specific diagrams and overview diagrams in a quick and
-consistent way. Add ant/make automation and the project class diagram will
-always be up to date.
+consistent way. <br/>
 
-<em>Postponed until I have finished the association/dependency inference
-   so that I don't have to modify source files to generate class diagrams
-</em>
+As an example we include a few class diagrams that have been generated
+from the <a href="http://jakarta.apache.org/commons/dbcp">DBCP connection pool</a>, 
+without altering the sources and using association and dependency inference 
+instead.<br/>
+
+The base view defines commons options, in particular the use of inference,
+common class coloring and class visibility (in particular, we hide the
+java runtime classes, with the exclusion of a few java.sql classes).
+To avoid visual clutter, we have first shown the java.sql package contents, and
+then hid selected classes.
+The <code>Overview</code> view provides a full view of the DBCP package,
+generating quite a big diagram (click on the diagram to show a full size version).<br/>
+
+<fmtcode ext="java">
+package org.apache.commons;
+
+/**
+ * @view
+ * @opt inferassoc
+ * @opt inferdep
+ * @opt useimports
+ * 
+ * @match .*
+ * @opt nodefillcolor LightGray
+ * 
+ * @match org.apache.commons.*
+ * @opt nodefillcolor PaleGreen
+ * 
+ * @match org.apache.commons.dbcp.*
+ * @opt nodefillcolor LemonChiffon
+ * 
+ * @match java.*|org.xml.*
+ * @opt hide
+ * 
+ * @match java.sql.*
+ * @opt !hide
+ * 
+ * @match java.sql\.(Ref|Time|Timestamp|Array|Date|Time|Clob|Blob|SQLException|.*MetaData.*|SQLWarning)
+ * @opt hide
+ */
+public abstract class BaseView {
+}
+
+/**
+ * @view
+ */
+public class Overview extends BaseView {
+}
+</fmtcode>
+
+<a href="dcbp-overview-full.png"><img src="dbcp-overview-small.png" alt="Overview"/></a>
+
+<p/>The <code>CommonsDbcp</code> view concentrates on the content of org.apache.commons.dbcp
+package, hiding other packages and subpackages available in the sources
+(click on the diagram to show a full size version).<br/>
+
+<fmtcode ext="java">
+package org.apache.commons;
+
+/**
+ * @view
+ * 
+ * @match org.apache.commons.*
+ * @opt hide
+ * 
+ * @match org.apache.commons.dbcp..*
+ * @opt !hide
+ * 
+ * @match org.apache.commons.dbcp..*\..*
+ * @opt hide
+ */
+public class CommonsDbcp extends BaseView {}
+</fmtcode>
+
+<a href="dcbp-full.png"><img src="dbcp-small.png" alt="Overview"/></a>
+
+<p/>Finally, the <code>Statement</code> view shows only the Statement related
+classes and their dependencies.
+
+<fmtcode ext="java">
+package org.apache.commons;
+
+/**
+ * @view
+ * 
+ * @match org.apache.commons.*
+ * @opt hide
+ * 
+ * @match org.apache.commons.dbcp\..*Statement.*
+ * @opt !hide
+ * 
+ * @match org.apache.commons.dbcp..*\..*
+ * @opt hide
+ */
+public class Statement extends BaseView {
+}
+</fmtcode>
+
+<img src="dbcp-statement.png" alt="Statement"/>
 
 </notes>