package DTDDoc;
   
   import java.io.*;
   import java.net.URI;
   import java.net.URISyntaxException;
   import java.text.Collator;
   import java.text.DateFormat;
   import java.util.*;
   
  import com.wutka.dtd.*;
  
  /** Main class to the DTDDoc program, everything happen here.
   *  @author Stefan Champailler */
  
  /*
  
  Given a set of DTD's we want to know in which one a given element is defined.
  We can restate the problem as:
  
  given a set of element, and a set of DTD's where these elements are defined,
  determine in which set each element is defined.
  
  Problem is that for a DTD we can enumerate all elements that are defined
  in it *AND* in its  children *without* distinction. Therefore, we can
  only know iff an element is defined in a DTD (and not its children) if and
  only if this DTD has no children.
  
  As DTD have children, they form a tree.
  
  Solution is follwoing:
  
  1. If the tree t has children:
         ce = set of all element defined in the children of t.
         The elements defined in t are the set of all elements
         defined in t and its children (we know that) minus ce
         (we have computed)
  
  2. if t has no child
         the elements defined in t are easy to guess.
  
  
  */
  
  public class DTDCommenter {
  
      private Logger log;
      private boolean getAroundNetBeanComments;
      private boolean showHiddenTags;
      private boolean showFixmeTags;
  
  
      /** Version of DTDDoc running */
      public final static String VERSION;
      static {
          Package pkg = DTDCommenter.class.getPackage();
          VERSION = (pkg == null) ? "(unknown version)" : pkg.getImplementationVersion();
      }
  
      /**
       * @deprecated maintained for binary backward compatibility: uses SystemLogger as
       * default logging system.
       */
      public DTDCommenter() {
          this( new SystemLogger());
      }
  
      public DTDCommenter( Logger log) {
          this.log = log;
      }
  
      /** Where we'll get the original DTD files. */
      private File sourceDir = null;
  
      /** Where we'll put all the generated documentation. */
      private File destDir = null;
  
      /** Remove the source dir part of a File. The result of this function
       *  is intended to be used as a relative path to a destination
       *  directory.
       *
       *  @param origin a file located in the source directory
       *  @return the path of the file relative to the source directory */
  
      private String getRelativePath( File origin) throws IOException {
  
          String srcDir = sourceDir.getCanonicalPath();
          String fullPath = origin.getCanonicalPath();
  
          if (fullPath.startsWith(srcDir))
              // +1 for the File.separator char
              return fullPath.substring(srcDir.length() + 1);
          else
              return fullPath;
      }
  
  
      /** Transform a source directory based path into
       *  a destination directory based one. Then we create the directory
       *  if it doesn't exist ('cos we know that if we wan to put
      *  something in that directory, we certainly want it to exist).
      *
      *  @param srcFile The source path */
 
     private void mkdestdirsRelativePath( File srcFile) throws IOException {
 
         // Basically, we transform a source directory based path into
         // a destination directory based one. Then we create the directory
         // if it doesn't exist.
 
         String fullRelativePath = getRelativePath( srcFile);
         int lastSeparator = fullRelativePath.lastIndexOf( File.separatorChar);
         if( lastSeparator >= 0) {
             String relativePath = fullRelativePath.substring(0, lastSeparator);
             File dirToMake = new File( destDir, relativePath);
             dirToMake.mkdirs();
         }
     }
 
 
     /** Check if a node is flat, that is, if it has no children.
      *  @param node the node to check.
      *  @return true if the node is flat, false else. If node is null,
      *               the function returns false as well. */
 
     private static boolean isFlat(DTDItem node) {
 
         if (node instanceof DTDContainer) {
             Iterator items = ((DTDContainer) node).getItemsVec().iterator();
 
             while (items.hasNext()) {
                 DTDItem item = (DTDItem) items.next();
                 if (item instanceof DTDChoice)
                     return true;
             }
         }
 
         return false;
     }
 
     /** Builds a coma separated list of HREF to the parents of a given element.
      *  Most of the time there will be only one parent, but there can be
      *  several.
      *
      *  @param dtd The dtd to which the element belongs.
      *  @param e The element. This element <em>must</em> have a parent.
      *  @return A string representing the HREF to the parents of the element. */
 
     private String getHREFToParents(ExtendedDTD dtd, DTDElement e) {
         Iterator i = dtd.getParents(e.getName()).iterator();
 
         StringBuffer buffer = new StringBuffer();
         while (i.hasNext()) {
             DTDElement p = (DTDElement) i.next();
             buffer.append(getInternalHREF( dtd, p));
             if (i.hasNext())
                 buffer.append(", ");
         }
 
         return buffer.toString();
     }
 
 
 
     /** Builds a HTML internal reference to an element inside the documentation
      *  of a DTD (<code>#element_id</code>).
      *
      *  @param dtd the target DTD  (current, since it is an internal reference).
      *  @param element The element to reference.
      *  @return A string containing the HTML code of the reference:
      *  <code>&lt;a href='#element_id'&gt;element name&lt;/a&gt; */
 
     public String getInternalHREF( ExtendedDTD dtd, DTDElement element) {
         if( element != null)
             return "<a href='#" + ExtendedDTD.getUniqueId( element) + "'>" +
                 element.getName() + "</a>";
         else {
             // FIXME This should throw an exception. But before doing so
             // we must make sure that this won't break backward compatibility.
             log.error("Can't build a HREF to a null element");
             return "";
         }
     }
 
 
     /** Builds a HTML external reference to an element from the documentation
      *  of a DTD (<code>filename#element_id</code>).
      *
      *  @param dtd the target DTD.
      *  @param element The element to reference.
      *  @param text text that will appear in the reference.
      *  @return A string containing the HTML code of the reference:
      *  <code>&lt;a href='<i>dtd_reference</i>#element_id'&gt;text&lt;/a&gt; */
 
     public String getExternalHREF( ExtendedDTD dtd, DTDElement element,
             String text) throws IOException {
         return "<a href='" + newURITo( dtd, element).toString() + "'>"
                 + text + "</a>";
     }
 
     public String getExternalHREF( ExtendedDTD dtd, String elementName,
             String text) throws IOException {
         return getExternalHREF( dtd, dtd.getElementByName( elementName),
                 text);
     }
 
     public String getDTDBaseURI( ExtendedDTD dtd) {
 
         try {
             return (getRelativePath( dtd.getSystemPath()) + ".html").
                     replace( File.separatorChar, '/'); // FIXME There should a constant for that slash.
         } catch( IOException ex) {
             log.error( "Unable to make a relative path to DTD: "
                     + dtd.getSystemPath(), ex);
             return null;
         }
     }
 
     private URI toURI( String uri) {
         try {
             return new URI( uri.replace( File.separatorChar, '/'));
         } catch( URISyntaxException ex) {
             log.error("Unable to create a URI out of the string '" +
                     uri + "'.",ex);
             return null;
         }
     }
 
     public URI newURITo( ExtendedDTD dtd) {
         return toURI( getDTDBaseURI( dtd));
     }
 
     public URI newURITo( ExtendedDTD dtd, DTDElement element) {
 
         return toURI( getDTDBaseURI( dtd) + '#' +
                 ExtendedDTD.getUniqueId( element) );
     }
 
     public URI newURITo( ExtendedDTD dtd, DTDAttlist list,
             DTDAttribute attribute) {
 
         return toURI( getDTDBaseURI( dtd) + '#' +
                     ExtendedDTD.getUniqueId( list, attribute));
     }
 
     public URI newURITo( ExtendedDTD dtd, DTDElement element,
             DTDAttribute attribute) {
 
         return toURI( getDTDBaseURI( dtd) + '#' +
                 ExtendedDTD.getUniqueId( element, attribute));
     }
 
 
 
 
     /** <p>This class encapsulates the context related to a
      *  DTDName. In this particular case, the DTDName is expected to
      *  represent a child of an element in the element model.</p>
      *
      *  <p>A context describes the cardinality modifiers that are
      *  applying to the name. For example if an element model
      *  is (alpha | beta)* then the context is described by
      *  <i>both</i> the star and the vertical bar. The star
      *  states that the cardinality is "zero or many" and the
      *  vertical bar states that alpha or beta might appear, therefore
      *  the cardinalities of alpha and beta are the same, that
      *  is "one at most".</p>
      */
 
     class NameInfo implements Comparable {
         public final DTDName name;
         public final Set contexts = new HashSet();
 
 
         public NameInfo( DTDName name, String context) {
             this.name = name;
             contexts.add( context);
         }
 
         public String getName() {
             return name.getValue();
         }
 
         public void addContext( String context) {
             contexts.add( context);
         }
 
 
         /** <p>This method establishes the overall cardinality of a child
          *  of an element. The necessary information is taken from the
          *  context field.</p>
          *
          *  <p>The basic principle is to "reduce" the context element by
          *  element, starting at the end of the context. After each
          *  reduction we have the overall cardinality of the child
          *  in respect to the part of context that was processed so far.</p>
          *
          *  <p>The reduction opeartion consists in comparing the current
          *  cardinality with the "current" one in the context. Those
          *  two cardinalities are used as selector in a two dimensional
          *  table that will give the new overall cardinality for the
          *  context explored so far (thus the previous one extended by the
          *  "current" cardinality). The table is like this:</p>
          *
          * 	<table border="1" align="center">
          * 	  <tr>
          *      <td></td><td><b>1</b></td><td><b>?</b></td><td><b>+</b></td><td><b>*</b></td><td><b>|</b></td><td><b>,</b></td>
          * 	  </tr>
          * 	  <tr>
          *      <td><b>1</b></td><td>1</td><td>?</td><td>+</td><td>*</td><td>?</td><td>1</td>
          * 	  </tr>
           * 	  <tr>
          *      <td><b>?</b></td><td>?</td><td>?</td><td>*</td><td>*</td><td>?</td><td>?</td>
          * 	  </tr>
          * 	  <tr>
          *      <td><b>+</b></td><td>+</td><td>*</td><td>+</td><td>*</td><td>*</td><td>+</td>
          * 	  </tr>
          * 	  <tr>
          *      <td><b>*</b></td><td>*</td><td>*</td><td>*</td><td>*</td><td>*</td><td>*</td>
          * 	  </tr>
          * 	  <tr>
          *      <td><b>|</b></td><td>?</td><td>?</td><td>*</td><td>*</td><td>|</td><td>|</td>
          * 	  </tr>
          * 	  <tr>
          *      <td><b>,</b></td><td>1</td><td>?</td><td>+</td><td>*</td><td>|</td><td>,</td>
          * 	  </tr>
          * </table>
          *
          * <p>Some side notes here:
          * <ul>
          *     <li>Surprinsigly, this table is symetric !</li>
          *     <li>"*" leads to "*", so one could stop the processing early.</li>
          *     <li>"," is transparent.</li>
          * </ul>
          * </p>
          *
          *  <p>This method for finding cardinality
          *  gives good results in most cases and gives correct
          *  but hardly usable results for complicated cases (those where a
          *  children is deeply nested in cardinality modifiers).</p>
          *
          * @return A string stating the cardinality, ready to be displayed.
          */
 
         public String getCardinality() {
 
             /*
              *     ! 1 ? + *   |   is covered by:
              *   --+------------
              *   1 ! 1 ? + *   ?
              *   ? ! ? ? * *   ?
              *   + ! + * + *   *
              *   * ! * * * *   *
              *     !
              *   | ! ? ? * *   |
              *
              *  - When we fall on *, we stop there.
              *  - "," leaves things untouched (it's "transparent").
              *  - Strangely, the array is symetric.
              */
 
             final String indexBase = "1?+*|,";
 
             final String xform[] = {
                 "1?+*?1",
                 "??**??",
                 "+*+**+",
                 "******",
                 "??**||",
                 "1?+*|,"   };
 
             int overallCardinal = -1;
 
 
             for( Iterator ic = contexts.iterator(); ic.hasNext(); ) {
 
                 String context = (String) ic.next();
 
                 // Now we proceed to the reduction of the context to
                 // a simple "cardinal".
 
                 int i = context.length() - 1;
                 int currentCardinal = indexBase.indexOf( context.charAt( i));
 
                 while(i > 0) {
 
                     // find the number of the cardinality symbol (i.e. index in
                     // indexBase) preceeding the i-th one
                     i = i - 1;
                     int previous = indexBase.indexOf( context.charAt( i));
 
                     // Based on that previous cardinality symbol, we compute
                     // the next current cardinality
                     currentCardinal = indexBase.indexOf( xform[previous].charAt( currentCardinal));
                 }
 
                 if( overallCardinal == -1)
                     overallCardinal = currentCardinal;
                 else if( overallCardinal != currentCardinal)
                     // That's our heuristic to sya: our definition of
                     // cardinality is too complex to make sense. And if it's
                     // too complex, we'd better redirect the user to the real
                     // element's definition / model.
                     return "See model";
             }
 
 
             // Finally we convert the cardinality into something
             // usable.
 
             switch( overallCardinal) {
                 case 0: return "Only one";
                 case 1: return "One or none";
                 case 2: return "At least one";
                 case 3: return "Any number";
                 default:
                     log.error("Something wrong happened while establishing cardinality");
                     return null;
             }
         }
 
         public int compareTo( Object o) {
             Collator collator = Collator.getInstance();
 
             String oName = ((NameInfo) o).getName();
 
             return collator.compare( getName(), oName);
         }
 
     }
 
     public char cardinalToChar( DTDCardinal cardinal) {
 
         if( cardinal == DTDCardinal.NONE)
             return '1';
         else if( cardinal == DTDCardinal.OPTIONAL)
             return '?';
         else if( cardinal == DTDCardinal.ZEROMANY)
             return '*';
         else if( cardinal == DTDCardinal.ONEMANY)
             return '+';
         else {
             log.error("Unrecognized cardinality! "+cardinal);
             return 'x';
         }
     }
 
     // FIXME Decouple the children guess from the cardinality guess
 
     private SortedSet collectChildrenNames(DTDItem child, String context, ExtendedDTD dtd)
         throws IOException {
 
         if (child instanceof DTDContainer) {
 
             // We flatten the father's structure.
             // By doing so, we unfortunately loose track of the cardinality of
             // the children.
             // To remind this cardinality, we can store it along with the item.
             // But if the item appears several times in the model, like
             // ( (alpha, beta+, gamma) | (teta, beta?) ) then what does the cardinality
             // of beta mean if it has to be expressed on one line in the children
             // table ? Indeed we should have two lines, one saying that
             // beta can appear 0 or more times and another line saying
             // that beta can appear at least one time. In that kind of
             // situation, displaying the content model look the best way to
             // go. Unfortunately, it's very difficult to understand for
             // non-IT people.
 
             Iterator items = ((DTDContainer) child).getItemsVec().iterator();
 
             context = context + cardinalToChar(((DTDContainer) child).getCardinal());
 
             if( child instanceof DTDChoice)
                 context = context + '|';
             else if( child instanceof DTDSequence)
                 context = context + ',';
             else if( child instanceof DTDMixed)
                 context = context + '|';
 
             SortedSet names = null;
 
             while (items.hasNext()) {
                 DTDItem item = (DTDItem) items.next();
 
                 SortedSet s = collectChildrenNames(item, context, dtd);
                 if (names != null && s != null)
                     names.addAll(s);
                 else
                     names = s;
             }
 
             return names;
 
         } else if (child instanceof DTDName) {
 
             NameInfo ni = new NameInfo(
                 (DTDName) child,
                 context + cardinalToChar(((DTDName) child).getCardinal()));
 
             //log.debug("Adding "+ c.getValue());
             SortedSet singleName = new TreeSet();
 
             singleName.add( ni);
             //log.debug("Done Adding "+c.getValue());
             return singleName;
 
         } else if (!(child instanceof DTDPCData)) {
             log.error(
                 "showChildrenHelper(): Unsupported child "
                     + child.getClass().getName());
             return null;
         } else
             return null;
     }
 
     private void showChildrenHelper_print( NameInfo elementName,
             PrintWriter out, ExtendedDTD dtd) {
         DTDElement element =
                 (DTDElement) dtd.getElementByName( elementName.getName());
 
             out.print("<tr>");
             out.print("<td>");
 
             if (element == null) {
 
                 // Since element is null, we have to figure out another way to
                 // get its name...
 
                 log.warn( "'" + elementName.getName() + "' element is " +
                             "undefined in "+dtd.getSystemPath());
 
                 out.print(elementName.getName());
 
             } else
                 out.print( getInternalHREF( dtd, element));
 
             out.print("</td>");
 
             if( element != null) {
                 // The cardinality is something quite special here. Indeed,
                 // because we are presenting a list of the children elements
                 // of a given element in a separate list, then the cardinality
                 // looses some of its meaning. It's because cardinality is
                 // locally defined (for example: alpha*, alpha can appear several times) and/or contextually
                 // interpreted (for example (x | alpha | y)+ alpha can appear several times as well).
                 // The cardinality is not defined clearly in the XML specification
                 // therefore there's some room for us.
                 //   I'll try this definition: cardinality is the number of times
                 //   a given child element may appear under its father element.
                 // Does this definition make any practical sense ?
 
                 // First of all, we know we display a list of children out of the
                 // element model. We do this because it helps the readability. That
                 // is, someone may want to know quickly if an element appears under
                 // a given element. Displaying a table of the element can solve that
                 // question.
 
                 // However it doesn't solve two questions:
                 //   - where the element may appear
                 //   - how many times
 
                 // The first answer can only be stated clearly by presenting the
                 // element definition to the user.
 
                 // The second answer can depend on the first one. That
                 // is, given the use of an element, the number of times it can appear
                 // may change. For example ( (b,a,c) | (e,a+,d) ).
 
                 // Finding the cardinality out of the element model is
                 // answering the second question without explicitely refering
                 // to the first answer.
 
                 // In my exdperience, the case described in the second answer
                 // doesn't appear very often. I usually encounter simpler
                 // structure where the need for context is very limited.
                 // example: figure (height,width,name) (height appears once)
                 //           paragraph (text | bold | italic | figure)*   (figure can appear several times)
 
                 // As a consequence, we're left with a pretty subjective
                 // notion of the usefulness of our cardinality definition.
                 // In a tremendous shortcut, I'll state that sometimes
                 // providing our cardinality makes sense, sometimes it doesn't.
                 // The good times are when the element definition is quite
                 // simple. So if it's simple (we still have to define that :)),
                 // then why do we need to copy that information from the
                 // (shown) element definition into the separate children table.
                 // Answer is: not everyone understand "*", "?", and so on.
                 // So the separate table gives us an opportunity to simplify
                 // the presentation some more.
 
                 // *,|,+ :  - + => +
                 //          - |,+ => *
                 //          - * => end
 
                 // |,1 :  - 1 => 1
                 //        - |,1 => ? => end
 
                 // +,+,+ :  - + => +
                 //          - +,+ => +
                 //          - +,+,+ => + and end
 
                 /*
                  *     ! 1 ? + *   |   is covered by :
                  *   --+------------
                  *   1 ! 1 ? + *   ?
                  *   ? ! ? ? * *   ?
                  *   + ! + * + *   *
                  *   * ! * * * *   *
                  *     !
                  *   | ! ? ? * *   |
                  *
                  *  - When we fall on *, we stop there.
                  *  - "," leaves things untouched (it's "transparent").
                  *  - Strangely, the array is symetric.
                  */
 
                 out.print("<td>");
                 out.print( elementName.getCardinality());
                 out.print("</td>");
                 out.println("</tr>");
             }
     }
 
     /** Writes a HTML formatted table describing all the children of a given
      *  element. To ease the presentation, the children tree is
      *  flattened.
      *  This brings a problem: ELEMENT e (a,(b|(c*,d))). This element e
      *  will have d described as a mandatory child. However, it is mandatory
      *  only in the context of (c*,d) but not in the context of b|(c*,d).
      *  The question is therefore, what should we show about it or,
      *  is it a good idea to flatten the children struture ?
      *
      *  @param father The element to display for which the children must be
      *      described.
      *  @param out Stream where to write the formatted children description.
      *  @param DTD The DTD in which the element is defined. */
 
 
     /** Show all the children of a given DTD element. That's where all
      *  the formatting is done. The actual job of gathering children's
      *  information is actually done by the showChildrenHelper() function.
      *
      *  @param element of which the children will be displayed.
      *  @param out the stream where all will be written.
      *  @param dtd The DTD from which the element comes from. */
 
     private void showChildren(
         DTDElement element,
         PrintWriter out,
         ExtendedDTD dtd)
         throws IOException {
 
         String summary = "&lt;" + element.getName() + "&gt;'s children";
 
         out.println("<table summary=\"" + summary + "\">");
 
         out.println("<thead>");
         out.println("<tr><th class='title' colspan='2'>" + summary + "</th></tr>");
         out.println("<tr><th colspan='2' height='1' class='ruler'></th></tr>");
         out.print("<tr>");
         out.print("<th class='subtitle'>Name</th>");
         out.print("<th class='subtitle'>Cardinality</th>");
         out.println("</tr>");
         out.println("<tr><th colspan='2' height='1' class='ruler'></th></tr>");
         out.println("</thead>");
 
         // showChildrenHelper(element.getContent(), out, dtd);
         out.print("<tbody>");
         SortedSet names = collectChildrenNames(element.getContent(), "", dtd);
         for( Iterator i = names.iterator(); i.hasNext(); )
             showChildrenHelper_print( (NameInfo) i.next(), out, dtd);
         out.print("</tbody>");
 
         out.print("</table>");
     }
 
     /** Gives the values of of an attribute as a coma separated list.
      *
      *  @param attr The attribute to get the value from.
      *  @return a coma separated list of all the values appearing in
      *          attr. null if anything goes wrong. */
 
     private static String getAttributeValues(DTDAttribute attr) {
         if (attr.getType() instanceof DTDNotationList) {
             DTDNotationList e = (DTDNotationList) attr.getType();
             return Tools.join(e.getItems(), ", ");
 
         } else if (attr.getType() instanceof DTDEnumeration) {
             DTDEnumeration e = (DTDEnumeration) attr.getType();
             return Tools.join(e.getItems(), ", ");
 
         } else if (attr.getType() instanceof String) {
             return "<i>Match the " + attr.getType() + " rules.</i>";
         }
 
         return "unknown attribute type " + attr.getType();
     }
 
     private static boolean isCDATA(DTDAttribute attr) {
         return "CDATA".equals(attr.getType()); // FIXME There should be a
                                                // constant for that CDATA
                                                // string.
     }
 
 
     /** Show all the attributes of a given DTD element. That's where all
      *  the formatting is done. The display done here is assumed to be
      *  a short form that comes along the element's full explanation.
      *
      *  @param element of which the attributes will be displayed.
      *  @param out the stream where all will be written.
      *  @param dtd The DTD from which the element comes from.*/
 
     private void showAttributes(
         DTDElement element,
         PrintWriter out,
         ExtendedDTD dtd) {
 
         String summary = "&lt;" + element.getName() + "&gt;'s attributes";
 
         out.print("<table  summary=\"" + summary + "\">");
 
         out.println("<tr>");
         out.println("<th class='title' colspan='3'>" + summary + "</th>");
         out.println("</tr>");
         out.println("<tr><th colspan='3' height='1' class='ruler'></th></tr>");
         out.println("<tr>");
         out.print("<th class='subtitle'>Name</th>");
         out.print("<th class='subtitle'>Values</th>");
         out.print("<th class='subtitle'>Default</th>");
         out.println("</tr>");
         out.println("<tr><th colspan='3' height='1' class='ruler'></th></tr>");
 
         List attributes = Tools.enumerationToList( element.attributes.keys());
         Collections.sort( attributes, Collator.getInstance());
 
         Iterator iter = attributes.iterator();
         while(iter.hasNext()) {
             String name = (String) iter.next();
 
             DTDAttribute attr = (DTDAttribute) element.attributes.get(name);
 
             out.print("<tr>");
             out.print("<td>");
             out.print(
                 "<a href='#"
                     + ExtendedDTD.getUniqueId(dtd.locateAttributesList(attr), attr)
                     + "'>");
             out.print(name + "</a></td>");
 
             out.print("<td>");
             if( !isCDATA( attr))
                 out.print(getAttributeValues(attr));
             out.print("</td>");
 
             out.print("<td>");
 
             if (attr.defaultValue != null)
                 out.print( attr.defaultValue);
 
             out.print("</td>");
             out.print("</tr>");
         }
 
         out.print("</table>");
     }
 
     /** Show an HTML title head for a DTD's element.
      * @see #showTitle
      */
 
     private static void showElementTitle( String left, String right,
             PrintWriter out, String titleSummary) {
         showTitle( false, left, right, out, titleSummary);
     }
 
     /** Show an HTML title head for a DTD's attribute.
      * @see #showTitle
      */
 
     private static void showAttributeTitle( String left, String right,
             PrintWriter out, String titleSummary) {
         showTitle( true, left, right, out, titleSummary);
     }
 
     /** <p>This is used mostly for the presentation of a title of an an element
      *  or an attribute. The title text is made of a right part and a left part.
      *  See an example to get a proper idea of what's going on here because
      *  it's very graphical.</p>
      *
      * <p>One shouldn't use this function as it is very generic. Use the
      * specialisations instead. For example {@link #showElementTitle} or
      * {@link #showAttributeTitle}.</p>
      *
      *  @param forAttribute Displays a title for an attribute. If
      *      <code>true</code> "attribute" CSS classes are used instead of
      *      "element" ones.
      *  @param left Text to display on the left of the title (can be any
      *      HTML text). Ignored if null.
      *  @param right Text to display on the right of the title (can be any
      *      HTML text). Ignored if null.
      *  @param out where the title will be displayed.
      *  @param titleSummary The summary used for the title. We need that
      *     because the title is shown as a table. This parameter will be
      *     used as the summary of that table. It's been added to have a
      *     nice HTML table code. As such, this string must be pure text.*/
 
     private static void showTitle(
         boolean forAttribute,
         String left,
         String right,
         PrintWriter out, String titleSummary) {
         out.print("<br />");
         out.println(
             "<table class='"
         + (forAttribute ? "attributeTitle" : "elementTitle")
         + "' summary=\""
                 + titleSummary
                 + "\"><tr><td class='"
         + (forAttribute ? "leftAttributeTitle" : "leftElementTitle")
         + "'>");
         out.print(left);
         out.println("</td><td class='"
         + (forAttribute ? "rightAttributeTitle" : "rightElementTitle")
         + "'>");
         if (right != null)
             out.println(right);
         out.println("</td></tr></table>");
     }
 
     /** Formats and renders into a stream a list of attribute. The format is
      *  a table, it's coded in HTML.
      *
      *  @param dtdAttList the attributes list.
      *  @param out the stream where to render the attributes.
      *  @param dtd The DTD in which the attributes list is defined. */
 
     private void showAttributesList(
         DTDAttlist dtdAttList,
         PrintWriter out,
         ExtendedDTD dtd) {
 
         // Attributes must be written to doc only if they are
         // defined in the current DTD file.
 
         // It is assumed that the attributes are _always_ shown on the same
         // page (therefore in the same file) as the element they charaterize.
 
         //out.println("<a name=\"" + dtd.makeAttListId(dtdAttList) + "\"></a>");
 
         StringBuffer buffer = new StringBuffer();
 
         buffer.append(dtdAttList.getAttribute(0).getName());
         for (int i = 1; i < dtdAttList.getAttribute().length; i++) {
             buffer.append(", ");
             buffer.append(dtdAttList.getAttribute(i).getName());
         }
         String s = buffer.toString();
 
         String a = "Attribute";
         if (dtdAttList.getAttribute().length > 1)
             a += "s";
 
         a += " of " +
             getInternalHREF( dtd, dtd.getElementByName( dtdAttList.getName()));
 
         showAttributeTitle( s, a, out, s);
     }
 
     /** This function parses a set of DTD files.
      *  @param filePaths A set containing all the paths to the DTD files
      *         (relative to the context of execution.
      *  @return A list with all the parsed DTD (ExtendedDTD). */
 
     private Set parseDTDFiles(Set filePaths) throws IOException {
 
         Set dtds = new HashSet();
 
         Iterator it = filePaths.iterator();
         while (it.hasNext()) {
             File f = (File) it.next();
             log.info("Parsing '" + f +"'...");
             dtds.add( new ExtendedDTD(f, log, getAroundNetBeanComments));
         }
 
         return dtds;
     }
 
     /** Character used to begin a tag. Usually @. */
     public static final char BEGIN_TAG = '@';
 
     /** Tag starting a comment (@comment) */
     public static final String COMMENT_TAG = BEGIN_TAG + "comment";
 
     /** Tag starting an attribute comment (@attr attributeName comment) */
     public static final String ATTR_COMMENT_TAG = BEGIN_TAG + "attr";
 
     /** Tag starting a "fix me" comment (@fixme) */
     public static final String FIXME_TAG = BEGIN_TAG + "fixme";
 
     /** Tag starting an "example" comment (@example) */
     public static final String EXAMPLE_TAG = BEGIN_TAG + "example";
 
     /** Tag starting a "hidden" comment (@hidden) */
     public static final String HIDDEN_TAG = BEGIN_TAG + "hidden";
 
     /** Tag starting a root element defintion (@root) */
     public static final String ROOT_TAG = BEGIN_TAG + "root";
 
     /** Tag starting a DTD title defintion (@title) */
     public static final String TITLE_TAG = BEGIN_TAG + "title";
 
     /** Tag starting a DTD doctype defintion (@doctype) */
     public static final String DOCTYPE_TAG = BEGIN_TAG + "doctype";
 
     /** This function will create a table of content for the parsed DTDs
      * documentation, and copy necessary images (<code>img</code> sub-directory) and
      * JavaScript library.
      * <p>The TOC will be created in a separate HTML file (<code>toc.html</code>) so that it
      * can be used in a frame-structured page.</p>
      *
      * @param docTitle the title to put at the top of the table.
      * @param dtds the DTD's to make the table of content for. */
 
     public void makeTOC(Set dtds, String docTitle) throws IOException {
 
         File tocPath = new File(destDir, "toc.html");
         log.info("Making the table of content in '" + tocPath.getName() + "'...");
 
         OutputStreamWriter htmlFile =
             new OutputStreamWriter(new FileOutputStream(tocPath));
 
         PrintWriter out = new PrintWriter(htmlFile);
 
         // Make sure we stick to the locale for the date format
         // SC 28/8/2006 Don't forget to properly escape if the locale and
         // encoding happen to differ
 
         DateFormat dateFormatter =
             DateFormat.getDateInstance( DateFormat.MEDIUM);
         String today = Tools.escapeHTMLUnicode( dateFormatter.format(
             new Date()), false);
 
         out.println(
             "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">");
         out.println("<html><head>");
         out.println("<meta http-equiv='CONTENT-TYPE' content='text/html' />");
         out.println("<link rel='StyleSheet' href='"+CSS_FILENAME+"' type='text/css' media='screen' />");
         out.println("<link rel='StyleSheet' href='"+DTREE_CSS_FILENAME+"' type='text/css' media='screen' />");
         ElementTreeBuilder.generateJavascriptSetup(out);
         out.println("<title>" + docTitle + ", " + today + "</title>");
         out.println("</head><body>");
         out.println("<h1 class='TOCTitle'>" + docTitle + "</h1>");
         out.println("<h2 class='TOCTitle'>" + today + "</h2>");
 
         out.println("<a href='elementsIndex.html' target='detail'>Elements' index</a><hr />");
 
         ElementTreeBuilder builder = new ElementTreeBuilder( out, this, dtds, log);
         builder.generateTree();
 
         out.println("</body></html>");
         out.close();
 
         // Copy the images for the tree into the output directory:
         String[] imageNames = { "empty.gif", "join.gif", "joinbottom.gif",
                 "line.gif", "minus.gif", "minusbottom.gif", "plus.gif",
                 "plusbottom.gif" };
 
         File imgPath = new File(destDir,"img");
         imgPath.mkdirs();
 
         for (int i=0;i<imageNames.length;i++)
             Tools.copyFromResource( "/resources/img/"+ imageNames[i],
                     new File(imgPath,imageNames[i]));
 
         Tools.copyFromResource( "/resources/cctree.js",
                 new File(destDir,"cctree.js"));
 
     }
 
     /** Character used to mark the beginning and the end of a part of
      *  code fragment. This one (&#167;) is deprecated because it is not an
      *  ASCII one (it's ISO-8859-1). Therefore it's not compatible
      *  between different charsets (only the first 128 are). It was a
      *  mistake...
      */
 
     public final static char CODE_SEPARATOR_DEPRECATED = '\u00a7';
 
     /** Character used to mark the beginning and the end of a part of
      *  a code fragment. This one is ASCII and is to be preferred.
      */
 
     public final static char CODE_SEPARATOR = '%';
 
     /** Tests if a given character is a code fragment separator.
      *  A deprecation message is displayed if the old code fragment separator
      *  is used.
      *
      * @param c the character to check.
      * @return true if the character is a code fragment separator. False else.
      */
 
     private boolean isCodeFragmentSeparator(char c) {
 
         if (c == CODE_SEPARATOR_DEPRECATED) {
             log.warn(
                 "Warning ! Usage of '"
                     + CODE_SEPARATOR_DEPRECATED
                     + "' as the code fragment delimiter is deprecated."
                     + " Please use '" + CODE_SEPARATOR + "' instead.");
             return true;
         } else
             return c == CODE_SEPARATOR;
     }
 
     /**
      * Tests if the given string contains an preformated block
      * (<code>&lt;PRE</code>) beginning at the given index.
      *
      * @param str the string to check
      * @param ndx index to start checking at
      * @return true if this is the start of an &lt;PRE&gt;-block. Exactly if
      *    <code>str.charAt(ndx)</code> is the '&lt;' of &lt;PRE
      *    (case insensitive). False else.
      */
 
     private static boolean isPre(String str, int ndx) {
         if ('<' != str.charAt(ndx) || ndx + "<PRE".length() >= str.length()) {
             return false;
         }
         String pre = str.substring(ndx, ndx + "<PRE".length());
         return pre.equalsIgnoreCase("<PRE");
     }
 
     /** Tests if the given string contains a preformated block
      * (<code>&lt;PRE&gt;</code>) ending at the given index.
      *
      * @param str the string to check
      * @param ndx index to start checking at
      * @return true if this is the end of an &lt;PRE&gt;-block. Exactly if
      *    <code>str.charAt(ndx)</code> is the '&lt;' of &lt;/PRE
      *    (case insensitive). False else.
      */
 
     private static boolean isPreEnd(String str, int ndx) {
         int end = ndx + "</PRE>".length();
         if ( end <= str.length()) {
             String pre = str.substring(ndx, end);
             return pre.equalsIgnoreCase("</PRE>");
         }
         return false;
     }
 
     /** Encodes a given character so that basic entities are used when
      *  necessary. For example, "<" will be encoded as "&lt;". No other
      *  form of encoding (such as character set encoding) is done here.
      *
      * @param c character to encode.
      * @return An HTML string representing the character.
      */
 
     private static String guardHtmlCharacter(char c) {
         if (c == '<')
             return "&lt;";
         else if (c == '>')
             return "&gt;";
         else
             return String.valueOf(c);
     }
 
     private boolean isCharEscaped( String p, int ndx) {
 
         return p.charAt( ndx) == '\\' && ndx+1 < p.length()
             && isCodeFragmentSeparator(p.charAt(ndx+1));
     }
 
     /** Formats and writes some text in a HTML output stream.
      *
      *  <p>First the text is divided into paragraph. The separation between two
      *  paragraphs is marked by a blank line.
      *  Paragraph enclosed between the XML paragraph separator (?) are
      *  written "quoted". The other are written as HTML paragraph,
      *  surrounded by the usual P tags.</p>
      *
      *  <p>Usage of a special
      *  character allows for easy XML code integration.
      *  This will alleviate the work of the documentation author and shield
      *  him from portability issues.</p>
      *
      *  @param p the paragraph
      *  @param titleCode HTML code to be put at the beginning of the
      *     paragraph. This might be helpful for some presentation
      *     issues. This code will be included inside the &lt;p>/&lt;/p>
      *     pair.
      *  @param out the output stream where to write the paragraph. */
 
     private void forcePrintParagraph(
         String p,
         PrintWriter out,
         String titleCode) {
 
         if (!p.startsWith("<p>"))
             out.print("<p>");
 
         if (titleCode != null)
             out.print("<span class='inTextTitle'>"+titleCode+"</span> ");
 
         int ndx = 0;
         while (ndx < p.length()) {
 
             // We split the paragraph on spaces.
             // In fact, we skip the space, but we also "summarise" it (a space
             // is a sequence/string of one or more space characters):
 
             // Number of "white spaces" in the space
             int spaces = 0;
 
             // Number of linefeeds in the space.
             int linefeeds = 0;
 
             while (ndx < p.length() && Character.isWhitespace(p.charAt(ndx))) {
                 spaces++;
                 if (p.charAt(ndx) == 0x000A)
                     linefeeds++;
                 ndx++;
             }
 
             // Depending on the nature of the splitting spaces, we decide
             // to replace them by a shorter, equivalent form.
 
             if (linefeeds >= 2)
                 // Two or more consecutives line feeds count for a paragraph
                 // break.
                 out.print("</p><p>");
             else if (linefeeds == 1)
                 // Only one count for nothing. However, we put one linefeed
                 // in the HTML to make it more readable.
                 out.println();
             else if (spaces > 0)
                 // Spaces are collapsed into a single space.
                 out.print(' ');
 
             // Now we've skipped a chunk of spaces, we analyse the following
             // chunk of text.
 
             if (ndx < p.length()) {
 
                 // Here we handle the <pre> tag.
 
                 if (isPre(p, ndx)) {
                     // Preformated HTML-Text we don't change anything - not even
                     // whitespace skipping - until we've seen the </PRE>-end.
                     out.print("</p><pre");
                     ndx += 4;
 
                     // Content of the <pre>-Section
                     while (ndx < p.length()
                             && !isPreEnd(p, ndx)) {
                         out.print(p.charAt(ndx));
                         ndx++;
                     }
 
                     // We make sure that we have actually encountered </pre> to
                     // issue the HTML code.
 
                     if (ndx < p.length()) {
                         out.print("</pre><p>");
                         ndx += 6;
                     }
 
                 } else if( isCharEscaped( p, ndx)) {
                     // So we print the escaped char...
                     out.print( p.charAt(ndx+1));
                     // and skip the escape char as well as the escaped
                     // char
                     ndx += 2;
 
                 } else if (isCodeFragmentSeparator(p.charAt(ndx))) {
                     // Skip code fragment beginning separator
                     out.print("</p><pre>");
                     ndx++;
 
                     // Content of the code fragment.
                     while (ndx < p.length()) {
                         if( isCharEscaped(p,ndx)) {
                             out.print( p.charAt(ndx+1));
                             ndx += 2;
                         } else if( !isCodeFragmentSeparator(p.charAt(ndx))) {
                             out.print(guardHtmlCharacter(p.charAt(ndx)));
                             ndx++;
                         } else
                             break;
                     }
 
                     // Skip code fragment end separator
                     out.print("</pre><p>");
                     ndx++;
 
                 } else if (('<' == p.charAt(ndx)) && ! Tools.startsWithHtmlTag(p.substring(ndx))) {
                     out.print("&lt;");
                     ndx++;
 
                 } else {
                     // Please note that we don't transform characters like
                     // > and < to entities. This is done like that to ensure
                     // that the commenter has full freedom for writing HTML
                     // stuff.
 
                     out.print(p.charAt(ndx));
                     ndx++;
                 }
             } // if ndx < p.length()
         } // while ndx < p.length()
 
         if (!p.endsWith("</p>"))
             out.print("</p>");
     }
 
 
     /** Displays the basic comment as parsed by a CommentParser.
      *
      *  @param out Where to write the comments.
      *  @param cp The comment parser holding the comment to write.
      *  @param headComment True if we're writing the topmost comment (that is, on the
      *                     documentation sheet).
      *  @return true if anything was written out. */
 
     private boolean printBaseCommentTags( PrintWriter out, CommentParser cp, boolean headComment) {
 
         if( cp == null)
             return false;
 
         boolean commentShown = false;
 
         if (headComment) {
             String doctype = cp.getUniqueTagValue( DOCTYPE_TAG);
             if (doctype != null) {
                 out.println("<p><span class='inTextTitle'>Usage</span>: <code>&lt;!DOCTYPE " + doctype + "&gt;</code></p>");
                 commentShown = true;
             }
         }
 
         String comment = cp.getUniqueTagValue( COMMENT_TAG);
         if (comment != null) {
             forcePrintParagraph(comment, out, null);
             commentShown = true;
         }
 
         String hidden = cp.getUniqueTagValue( HIDDEN_TAG);
         if (hidden != null && showHiddenTags) {
             forcePrintParagraph(hidden, out, null);
             commentShown = true;
         }
 
         String fixme = cp.getUniqueTagValue(FIXME_TAG);
         if (fixme != null && showFixmeTags) {
             forcePrintParagraph(fixme, out, "To fix:");
             commentShown = true;
         }
 
         String example = cp.getUniqueTagValue(EXAMPLE_TAG);
         if (example != null) {
             forcePrintParagraph(example, out, "Example:");
             commentShown = true;
         }
 
         return commentShown;
     }
 
     /** Format and displays a full comment on a HTML stream. The format
      *  is defined following the usage of several tags. Some part of the
      *  comment may be emphasized, hidden, etc.
      *
      *  @param pComment the comment
      *  @param out the stream to write the formatted comment to.
      *  @param headComment this comment is at the header of the DTD documentation */
 
     private void printComment( DTDComment pComment, PrintWriter out, boolean headComment) {
 
         if (pComment != null) {
             CommentParser cp = new CommentParser( pComment, log,
                 getAroundNetBeanComments);
 
             if( printBaseCommentTags( out, cp, headComment))
                 return;
         }
 
         out.print("<p>Sorry, no documentation.</p>");
     }
 
     /**
      * Copy style sheets (D-tree and DTDDoc) to destination directory.
      * @param styleSheet <code>null</code> to use default DTDDoc style sheet
      * @throws FileNotFoundException
      * @throws IOException
      */
     private void copyStyleSheets( File styleSheet) throws FileNotFoundException, IOException {
 
         Tools.copyFromResource( "/resources/"+DTREE_CSS_FILENAME,
                 new File( destDir, DTREE_CSS_FILENAME));
 
         if( styleSheet == null) {
             Tools.copyFromResource( "/resources/"+CSS_FILENAME,
                     new File( destDir, CSS_FILENAME));
         } else {
             Tools.copy( styleSheet, new File( destDir, CSS_FILENAME));
         }
     }
 
     private static final String CSS_FILENAME ="DTDDocStyle.css";
     private static final String DTREE_CSS_FILENAME ="dtreeStyle.css";
 
     private String getRelativePathTo( ExtendedDTD fromDtd, String to) throws IOException {
         if (fromDtd == null) {
             return to;
         }
 
         StringBuffer path = new StringBuffer();
         String relPath = getRelativePath( fromDtd.getSystemPath());
         for( int i=0; i<relPath.length(); i++)
             if( relPath.charAt(i) == File.separatorChar)
                 path.append("../");
         path.append(to);
         return path.toString();
     }
 
     /** Send the html code to link to the stylesheet used in to format the
      * documentation.
      *
      * @param dtd The dtd being documented (we need this info to build the path
      *        to the stylesheet (i.e. the number of /.. to use).
      * @param out Where to send the HTML colde. */
 
     private void linkToStyleSheet( ExtendedDTD dtd, PrintWriter out)
         throws IOException {
 
         String cssPath = getRelativePathTo(dtd, CSS_FILENAME);
         out.println("<link rel='StyleSheet' href='" + cssPath
             + "' type='text/css' media='screen' />");
     }
 
 
     /** Builds the HTML code that shows information about a DTD at the top of
      * its documentation.
      *
      * @param dtd The documented DTD.
      * @param out Where to write the code. */
 
     private void showPageStart(
         ExtendedDTD dtd,
         PrintWriter out, String currentFilename) throws IOException {
 
         out.print( "<p class='DTDSource'>");
 
         if (dtd == null) {
             out.print("Elements - Entities - Source");
         } else {
             String filename = dtd.getSystemPath().getName();
             out.print("<b><code>" + filename + "</code></b>: ");
 
             out.print( "<a href='" + filename + ".html'>Elements</a> - ");
 
             if( dtd.getEntities().size() > 0) {
                 out.print( "<a href='" + filename + ".entities.html'>Entities</a>");
             } else {
                 out.print("Entities");
             }
 
             out.print(" - <a href='" + filename + ".org.html'>Source</a>");
         }
 
         out.print(" | <a href='" + getRelativePathTo(dtd, "intro.html") + "'>Intro</a>");
         out.print(" - <a href='" + getRelativePathTo(dtd, "elementsIndex.html") + "'>Index</a>");
 
         out.print("<br /><a href='" + getRelativePathTo(dtd, "index.html") + "' target='_top'>FRAMES</a>");
         out.print("&nbsp;/&nbsp;<a href='" + currentFilename + "' target='_top'>NO FRAMES</a>");
 
         out.print("</p>");
 
     }
 
     /** Formats and displays the introduction text and HTML header to
      *  the documentation of a DTD.
      *
      *  @param dtd The DTD for which the introduction must be created.
      *  @param out Where the introduction HTML will be written. */
 
     private void showIntroduction(
         ExtendedDTD dtd,
         PrintWriter out) throws IOException {
 
         out.println(
             "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">");
         out.println("<html><head>");
 
         out.println(
             "<meta http-equiv='CONTENT-TYPE' " +
             "content='text/html; charset="	+ dtd.getEffectiveEncoding() + "' />");
 
         linkToStyleSheet( dtd, out);
 
         if (dtd.getTitle() != null) {
             out.print("<title>");
             out.print(dtd.getTitle());
             out.println("</title>");
         }
 
         out.println("</head><body>");
 
         showPageStart(dtd, out, dtd.getSystemPath().getName() + ".html");
 
         if (dtd.getTitle() != null) {
             out.print("<h1>");
             out.print(dtd.getTitle());
             out.println("</h1>");
         }
 
         // Removed, not suitable anymore because we can now guess the root
         // FIXME SC: how's that ?
 
         /* if (dtd.getRootElement() == null) {
             out.print("<p><EM>Warning !</EM> ");
             out.println("This DTD doesn't have a root tag ! Therefore " +
                 "it is used as a repository for tags");
             out.println("to be used in other DTDs</p>");
         }*/
     }
 
     private void showAttributeUsage( DTDAttribute attr, PrintWriter out) {
         String possibleValues = null;
         if (getAttributeValues(attr) != null
             && !isCDATA(attr))
             possibleValues =
                 "<span class='inTextTitle'>Possible values</span>: "
                     + getAttributeValues(attr);
 
         String usage = null;
 
         if (attr.decl == DTDDecl.REQUIRED)
             usage = "<span class='inTextTitle'>Required</span>";
         else if (attr.decl == DTDDecl.FIXED)
             usage = "<span class='inTextTitle'>Fixed value:</span> " + attr.defaultValue;
         else if (
             attr.defaultValue != null
                 && attr.defaultValue.length() > 0)
             usage = "<span class='inTextTitle'>Default value</span>: " + attr.defaultValue;
 
         if (possibleValues != null || usage != null) {
             out.print("<p>");
             if (possibleValues != null)
                 out.print(possibleValues);
             if (possibleValues != null && usage != null)
                 out.print(" - ");
             if (usage != null)
                 out.print(usage);
             out.print("</p>");
         }
     }
 
     private void documentAttributesList( ExtendedDTD dtd, DTDAttlist list, PrintWriter out, DTDComment comment) {
 
         /* If the attribute list has only one memeber
          *    @attr tag is useless, use simple, anonymous comment and example
          * If the attribute list has more than one memeber
          *    @attr tags are mandatory
          *    @example tag must be named like @attr tags.
          */
 
         //log.debug("documentAttributesList-1");
 
         if( list == null || out == null) {
             String err = "documentAttributesList: wrong argument: ";
             if( list == null) err += "list ";
             if( out == null) err += "out ";
             throw new IllegalArgumentException( err);
         }
 
         CommentParser cp = null;
         Map attrComments = null;
 
         if( comment != null) {
             cp = new CommentParser( comment, log, getAroundNetBeanComments);
 
             if( list.getAttribute().length > 1) {
                 if( cp.getUniqueTagValue( COMMENT_TAG) != null)
                     log.warn("When commenting a list of" +
                         " attributes, use @attr instead of a regular comment.");
             }
 
             // if there is only one attribute, one can use @attr
             // _or_ a regular comment.
             attrComments = cp.getMultipleTagValue( ATTR_COMMENT_TAG);
         }
 
 
         for (int i = 0; i < list.getAttribute().length; i++) {
             String a = "Attribute of "
                 + getInternalHREF( dtd, dtd.getElementByName( list.getName()));
 
             DTDAttribute attr = list.getAttribute(i);
             out.println("<a name='" + ExtendedDTD.getUniqueId( list, attr) + "'></a>");
             showAttributeTitle( "@"+attr.getName(), a, out, attr.getName());
 
             String attrComment = null;
             if( (attrComments != null) && ((attrComment = (String) attrComments.get( attr.getName())) != null)) {
                 forcePrintParagraph( attrComment, out, null);
 
             } else if( !printBaseCommentTags( out, cp, false)) {
                 // heuristics: id and xmlns are so classical that it is never documented
                 // Therefore, we provide some documentation for them.
 
                 if ( "id".equals(attr.getName())) {
                     out.print("<p>Element identifier.</p>");
                 } else if ( "xmlns".equals(attr.getName())) {
                     out.print("<p>XML namespace of the element.</p>");
                 } else {
                     out.print("<p>Sorry, no documentation.</p>");
                     log.warn( "UNDOCUMENTED attribute '" +
                             attr.getName() + "' in element '" + list.getName()
                             + "'");
                 }
             }
 
             showAttributeUsage( attr, out);
         }
 
         //log.debug("documentAttributesList-2");
     }
 
     void showContainerModel( ExtendedDTD dtd, PrintWriter out, DTDContainer container,
             String sep) {
 
         out.print('(');
 
         Iterator i = container.getItemsVec().iterator();
 
         boolean printSep = false;
         while( i.hasNext()) {
             if( printSep)
                 out.print( sep);
             else
                 printSep = true;
 
             showElementModel( dtd, out, (DTDItem) i.next());
         }
         out.print(')');
     }
 
 
      void showElementModel( ExtendedDTD dtd, PrintWriter out, DTDItem item) {
         if( item instanceof DTDAny )
             out.print("ANY");
         else if( item instanceof DTDEmpty )
             out.print("EMPTY");
         else if( item instanceof DTDPCData )
             out.print("#PCDATA");
         else {
             if( item instanceof DTDName) {
                 out.print( getInternalHREF( dtd,
                         dtd.getElementByName((DTDName) item)));
             } else if( item instanceof DTDChoice)
                 showContainerModel( dtd, out, (DTDContainer) item, " | ");
             else if( item instanceof DTDSequence)
                 showContainerModel( dtd, out, (DTDContainer) item, ", ");
             else if( item instanceof DTDMixed)
                 showContainerModel( dtd, out, (DTDContainer) item, " | ");
 
             if( item.getCardinal() == DTDCardinal.OPTIONAL)
                 out.print('?');
             else if( item.getCardinal() == DTDCardinal.ZEROMANY)
                 out.print('*');
             else if( item.getCardinal() == DTDCardinal.ONEMANY)
                 out.print('+');
         }
     }
 
     /**
      * Creates a PrintWriter to a file in destDir corresponding to the DTD, with a suffix
      * added to the file name. If the DTD declares an encoding, it is taken into account,
      * else default encoding UTF-8 is used.
      * @param dtd the source DTD
      * @param suffix the suffix that will be added in the destination file
      * @return a PrintWriter with appropriate encoding
      * @throws IOException
      */
     private PrintWriter newPrintWriter( ExtendedDTD dtd, String suffix)
         throws IOException {
 
         File outputName = new File(	destDir,
                 getRelativePath(dtd.getSystemPath()) + suffix);
 
         Tools.makeFileDir( outputName);
 
         FileOutputStream outFile = new FileOutputStream( outputName);
 
         Writer out =  new OutputStreamWriter( outFile, dtd.getEffectiveEncoding());
 
         return new PrintWriter(new BufferedWriter(out));
     }
 
 
     /** Main function for building a Extended DTD documentation. Basically,
      *  this function will run over all the items of a DTD (in their natural
      *  order) and build the related pieces of documentation.
      *  @param dtd The DTD to document*/
 
     private void makeDocumentation(ExtendedDTD dtd) throws IOException {
         log.info(
                 "Making doc for '" + getRelativePath(dtd.getSystemPath())
                     + "' [" + dtd.getEffectiveEncoding() + "]");
 
         PrintWriter out = newPrintWriter( dtd, ".html");
 
         showIntroduction(dtd, out);
 
         DTDComment currentComment = null;
         boolean firstCommentImpossible = false;
 
         for (int i = 0; i < dtd.getItems().size(); i++) {
 
             Object e = dtd.getItems().get(i);
 
             if (e instanceof DTDComment) {
 
                 currentComment = (DTDComment) e;
 
                 if (i + 1 < dtd.getItems().size()
                     && dtd.getItems().get(i + 1) instanceof DTDComment
                     && !firstCommentImpossible) {
                     //log.debug("Writing first comment !"+currentComment);
                     printComment(currentComment, out, true);
                     out.println("<br />");
                 }
 
                 firstCommentImpossible = true;
 
             } else if (e instanceof DTDAttlist) {
 
                 documentAttributesList( dtd, (DTDAttlist) e, out, currentComment);
                 firstCommentImpossible = true;
                 currentComment = null;
 
             } else if (e instanceof DTDElement) {
 
                 firstCommentImpossible = true;
                 DTDElement dtdElement = (DTDElement) e;
 
                 // add the element to elementsIndex
                 Set declaredInDtds = (Set)elementsIndex.get(dtdElement.getName());
                 if (declaredInDtds == null) {
                     declaredInDtds = new HashSet();
                     elementsIndex.put(dtdElement.getName(), declaredInDtds);
                 }
                 declaredInDtds.add(dtd);
 
                 if (currentComment == null) {
                     log.warn("UNDOCUMENTED element: " + dtdElement.getName());
                 }
 
                 out.println("<a name='" + ExtendedDTD.getUniqueId( dtdElement) + "'></a>");
 
                 String linkToParent = null;
                 if (dtd.getParents(dtdElement.getName()) != null) {
                     if (dtdElement == dtd.getRootElement()) {
                         linkToParent = "Root element, " +
                             "child of " + getHREFToParents(dtd, dtdElement);
                     } else {
                         linkToParent =
                             "Child of " + getHREFToParents(dtd, dtdElement);
                     }
                 } else
                     linkToParent = "Root element";
 
                 DTDItem item = dtdElement.getContent();
 
                 String elementPresentation = "&lt;" + dtdElement.getName();
 
                 if (item instanceof DTDEmpty)
                     elementPresentation += '/';
 
                 elementPresentation += "&gt;";
 
                 if (linkToParent == null)
                     showElementTitle( elementPresentation, null, out,
                             dtdElement.getName());
                 else
                     showElementTitle( elementPresentation, linkToParent,
                         out, dtdElement.getName());
 
                 printComment(currentComment, out, false);
 
                 if (item instanceof DTDContainer) {
 
                     boolean attributesToShow =
                         dtdElement.attributes != null
                             && dtdElement.attributes.size() > 0;
 
                     boolean childrenToShow =
                         !(((DTDContainer) item).getItem(0) instanceof DTDPCData
                             && ((DTDContainer) item).getItems().length == 1);
 
                     if (childrenToShow || attributesToShow) {
                         out.println(
                             "<blockquote><table summary='element info'><tr>");
                     }
 
                     // If the element is "just" a PCDATA, it is better to not
                     // display its children !
 
                     if (childrenToShow) {
                         out.print("<td class='construct'>");
                         showChildren(dtdElement, out, dtd);
                         out.print("</td>");
                     }
 
                     if (attributesToShow) {
                         out.print("<td class='construct'>");
                         showAttributes(dtdElement, out, dtd);
                         out.print("</td>");
                     }
 
                     if (childrenToShow || attributesToShow) {
                         out.println("</tr></table></blockquote>");
                     }
 
                     if (childrenToShow) {
                         out.print("<span class='inTextTitle'>Element's model:</span>");
                         out.print("<p class='model'>");
                         //item.write(out);
                         showElementModel( dtd, out, item);
                         out.print("</p>");
                     }
 
                 } else if (item instanceof DTDEmpty) {
 
                     firstCommentImpossible = true;
 
                     boolean attributesToShow =
                         dtdElement.attributes != null
                             && dtdElement.attributes.size() > 0;
 
                     if (attributesToShow) {
                         out.println("<blockquote>");
                         showAttributes(dtdElement, out, dtd);
                         out.println("</blockquote>");
                     }
 
                     out.print("<p class='emptyTagNote'>This element is always empty.</p>");
 
                 } else if (item instanceof DTDAny) {
 
                     firstCommentImpossible = true;
 
                     boolean attributesToShow =
                         dtdElement.attributes != null
                             && dtdElement.attributes.size() > 0;
 
                     if (attributesToShow) {
                         out.println("<blockquote>");
                         showAttributes(dtdElement, out, dtd);
                         out.println("</blockquote>");
                     }
 
                     out.print("<p class='emptyTagNote'>This element accepts any declared element as its children.</p>");
 
                 } else
                     out.println(
                         "type= "
                             + item.getClass().getName()
                             + " is unsupported !");
 
                 currentComment = null;
 
             } else if (e instanceof DTDNotation) {
                 DTDNotation notation = (DTDNotation)e;
                 log.warn("NOTATION declaration is still not supported: ignoring <!NOTATION " + notation.getName() + " ...>");
 
             } else if (
                 !(e instanceof DTDEntity)
                     && !(e instanceof DTDElement)
                     && !(e instanceof DTDProcessingInstruction))
                 log.error(
                     "makeHTMLDoc(): "
                         + e.getClass().getName()
                         + " not supported");
         }
 
         out.println("</body></html>");
         out.close();
 
         if( dtd.getEntities().size() > 0)
             makeEntitiesPage( dtd);
         makeDTDtoHtml(dtd);
     }
 
     /** Build the complete HTML documentation for a set of DTDs.
      *  @param dtds a set containing all the (Extended) DTD's to parse. */
 
     private void makeDocumentation(Set dtds) throws IOException {
 
         if( dtds == null) {
             log.warn("No DTD to make documentation for");
             return;
         }
 
         for (Iterator iter = dtds.iterator(); iter.hasNext(); ) {
             ExtendedDTD dtd = (ExtendedDTD) iter.next();
             mkdestdirsRelativePath( dtd.getSystemPath());
             makeDocumentation(dtd);
         }
     }
 
     /** Transforms a DTD file into an HTML file. There's no syntax highlighting
      * nor any eye-candy.
      *
      * @param dtd The extended DTD that represents the DTD file (in particular,
      * its "getSystemPath()" property. */
 
     private void makeDTDtoHtml( ExtendedDTD dtd)
         throws IOException {
 
         PrintWriter pw = newPrintWriter( dtd, ".org.html");
 
         pw.println(
             "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">");
         pw.println("<html> <head>");
         pw.println(
             "<meta http-equiv='CONTENT-TYPE' content='text/html; charset="
                 + dtd.getEffectiveEncoding() + "' />");
 
         linkToStyleSheet( dtd, pw);
 
         pw.println("<title>" + dtd.getTitle() + "</title>");
         pw.println("</head><body>");
 
         showPageStart(dtd, pw, dtd.getSystemPath().getName() + ".org.html");
 
         DtdXhtmlRenderer renderer = new DtdXhtmlRenderer();
         pw.print("<pre id='dtd_source'>");
         renderer.highlight(new InputStreamReader(new FileInputStream(dtd.getSystemPath()), dtd.getEffectiveEncoding()), pw);
         pw.println("</pre>");
 
         pw.println("</body></html>");
 
         pw.close();
     }
 
     private void showIntro( Set dtds, String docTitle, PrintWriter out) throws IOException {
         showPageStart(null, out, "intro.html");
         out.println("<h1>" + docTitle + "</h1>");
 
         SortedMap sortedDtds = new TreeMap(Collator.getInstance());
         for (Iterator iter = dtds.iterator(); iter.hasNext(); ) {
             ExtendedDTD dtd = (ExtendedDTD) iter.next();
             sortedDtds.put(dtd.getSystemPath().getName(), dtd);
         }
         Set keys = sortedDtds.keySet();
 
         out.println("<table border='1' cellspacing='0'>");
         Iterator iter = keys.iterator();
         while (iter.hasNext()) {
             String filename = (String)iter.next();
             ExtendedDTD dtd = (ExtendedDTD)sortedDtds.get(filename);
             String title = dtd.getTitle();
             out.print("<tr><td><code><a href='" + getRelativePath(dtd.getSystemPath())+ ".html'>" + filename + "</a></code></td>");
             out.print("<td>");
             boolean empty = true;
             if (! filename.equals(title)) {
                 out.print(Tools.escapeHTMLUnicode(title, false));
                 empty = false;
             }
             if (dtd.getDoctype() != null) {
                 if (! empty) {
                     out.print("<br />");
                 }
                 out.print("<code>&lt;!DOCTYPE " + dtd.getDoctype() + "&gt;</code>");
                 empty = false;
             }
             if (empty) {
                 out.print("&nbsp;");
             }
             out.print("</td>");
             out.println("</tr>");
         }
         out.println("</table>");
 
         out.println(
             "<p>This documentation was generated by <a href='http://dtddoc.sourceforge.net'>DTDDoc</a> " +
             VERSION + " !</p>");
     }
 
     /** Builds the introduction page to the documentation.
      *  A small advertisement message for DTDDoc is
      *  displayed as well ("? la guerre comme ? la guerre" :)). */
 
     private void makeIntroPageHtml( Set dtds, String docTitle) throws IOException {
 
         File introPath = new File(destDir, "intro.html");
         log.info("Making the introduction page in '"+introPath.getName()+"'...");
         Writer htmlFile = new OutputStreamWriter( new FileOutputStream( introPath), "US-ASCII");
         PrintWriter out = new PrintWriter( new BufferedWriter( htmlFile));
 
         out.println("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">");
         out.println("<html><head><title>DTDDoc for " + docTitle + "</title>");
         out.println("<link rel='StyleSheet' href='"+CSS_FILENAME+"' type='text/css' media='screen' />");
         out.println("</head><body>");
 
         showIntro(dtds, docTitle, out);
 
         out.println("<p>Use the left menu to navigate through the DTDs !</p>");
         out.println("</body></html>");
 
         out.close();
     }
 
     /** Make the index.jhtml, that is the main entry point into the
      *  documentation. Basically it's some frames. */
 
     private void makeIndexHtml( Set dtds, String docTitle) throws IOException {
 
         File indexPath = new File(destDir, "index.html");
         log.info("Making '"+indexPath.getName()+"'...");
         Writer htmlFile = new OutputStreamWriter( new FileOutputStream( indexPath), "US-ASCII");
         PrintWriter out = new PrintWriter( new BufferedWriter( htmlFile));
 
         out.println(
             "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Frameset//EN\" " +
             "\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd\">\n" +
             "<html><head>\n" +
             "<title>DTDDoc for " + docTitle + "</title>\n"+
             "<link rel='StyleSheet' href='"+CSS_FILENAME+"' type='text/css' media='screen' />" +
             "</head>\n" +
             "<frameset cols='20%, 80%'>\n" +
             "   <frame src='toc.html' />\n" +
             "   <frame src='intro.html' name='detail' />\n" +
             "   <noframes><body>");
 
         showIntro(dtds, docTitle, out);
 
         out.println("</body></noframes>\n" +
             "</frameset>" +
             "</html>");
 
         out.close();
     }
 
     /**
      * A map of every element name, with declaring DTDs.
      * <ul>
      * <li>key = String: element name</li>
      * <li>value = Set&lt;ExtendedDTDT&gt;: the DTDs containing an element with this name</li>
      * </ul>
      */
     private SortedMap elementsIndex = new TreeMap(Collator.getInstance());
 
     /** Make an HTML file containing an index to all the elements
       * 	that are in the parsed DTDs.
       *
      *  Please note that it is a little more difficult to make
      *  an index for attributes. That is, a single attribute is often
      *  used in several elements of a DTD. For the index to be helpful,
      *  we have to make a direct link to each instances of that
      *  attribute. This may clutter the index. Therefore, I
      *  decide to not put them right now.
      *
        * @throws IOException As usual.
        */
 
     private void makeElementsIndex() throws IOException {
 
         File elIndex = new File(destDir, "elementsIndex.html");
         log.info("Making the elements' index '" + elIndex.getName() + "'...");
 
         Writer htmlFile = new OutputStreamWriter( new FileOutputStream(elIndex), "US-ASCII");
         PrintWriter out = new PrintWriter( new BufferedWriter( htmlFile));
 
         out.println("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">");
         out.println("<html><head><title>elements' index</title>");
         out.println("<meta http-equiv='CONTENT-TYPE' content='text/html' />");
         out.println("<link rel='StyleSheet' href='"+CSS_FILENAME+"' type='text/css' media='screen' />");
         out.println("</head><body>");
 
         showPageStart(null, out, elIndex.getName());
 
         // generate the index of the first letter used
         char lastLetter = ' ';
         for (Iterator iter = elementsIndex.keySet().iterator(); iter.hasNext(); ) {
             String name = (String)iter.next();
             char newLetter = Character.toUpperCase( name.charAt(0));
             if( newLetter != lastLetter) {
                 lastLetter = newLetter;
                 out.print("<a href='#"+lastLetter+"'>" +lastLetter+ "</a> ");
             }
         }
 
         out.println( "<br />");
 
         lastLetter = ' ';
 
         for (Iterator iter = elementsIndex.entrySet().iterator(); iter.hasNext(); ) {
             Map.Entry entry = (Map.Entry)iter.next();
             String name = (String) entry.getKey();
             Set dtds = (Set) entry.getValue();
 
             char newLetter = Character.toUpperCase( name.charAt(0));
             if( newLetter != lastLetter) {
                 lastLetter = newLetter;
                 out.println("<a name='"+lastLetter+"'></a>");
                 out.println("<h2>"+lastLetter+"</h2>");
             }
 
             out.print( name + " - ");
 
             // print DTDs list for this element
             SortedMap sortedDtds = new TreeMap(Collator.getInstance());
             for (Iterator dtdIter = dtds.iterator(); dtdIter.hasNext(); ) {
                 ExtendedDTD dtd = (ExtendedDTD)dtdIter.next();
                 sortedDtds.put(dtd.getTitle(), dtd);
             }
             for (Iterator sortedDtdIter = sortedDtds.entrySet().iterator(); sortedDtdIter.hasNext(); ) {
                 Map.Entry dtdEntry = (Map.Entry)sortedDtdIter.next();
                 ExtendedDTD dtd = (ExtendedDTD)dtdEntry.getValue();
 
                 String url = getExternalHREF( dtd, name,
                         Tools.escapeHTMLUnicode( dtd.getTitle(), false));
                 out.print(url);
                 if (sortedDtdIter.hasNext()) {
                     out.print(", ");
                 }
             }
 
             if (iter.hasNext()) {
                 out.println("<br />");
             }
         }
 
         out.println("</body></html>");
         out.close();
     }
 
     private void makeEntitiesPage( ExtendedDTD dtd) throws IOException {
 
         log.info("Making the entities page for " + dtd.getSystemPath().getName() + "...");
 
         PrintWriter out = newPrintWriter( dtd, ".entities.html");
 
         out.println("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">");
         out.println("<html><head><title>" + dtd.getSystemPath().getName() + "'s entities</title>");
         out.println("<meta http-equiv='CONTENT-TYPE' content='text/html; charset="
                     + dtd.getEffectiveEncoding() + "' />");
         linkToStyleSheet( dtd, out);
         out.println("</head><body>");
 
         showPageStart(dtd, out, dtd.getSystemPath().getName() + ".entities.html");
 
         out.println("<h1>Entities for "+dtd.getTitle()+"</h1>");
         out.println("<table summary='Entities'>");
         out.println("<thead><tr><th>Name</th><th>Value</th></tr></thead>");
 
         out.println("<tbody>");
         out.println("<tr><th colspan='2' height='1' class='ruler'></th></tr>");
 
         Iterator i = dtd.getEntities().values().iterator();
         while( i.hasNext()) {
 
             out.println("<tr>");
 
             DTDEntity entity = (DTDEntity) i.next();
 
             out.println("<td>"+entity.name+"</td>");
 
             out.println("<td>");
 
             if( entity.value != null)
                 out.println( entity.value);
 
             if( entity.ndata != null)
                 out.println( entity.ndata);
 
             if( entity.externalID != null)
                 out.println( entity.externalID.system+" <i>(system)</i>" );
 
             out.println("</td>");
 
             out.println("</tr>");
         }
 
         out.println("</tbody>");
         out.println("</table>");
         out.println("</body></html>");
         out.close();
     }
 
     /**
      * @deprecated signature maintained for binary backward compatibility with versions <= 0.0.11, but
      * equivalent to the other more generic commentDTDs() method
      */
     public void commentDTDs(
             HashSet scan,
             File sourceDir,
             File destDir,
             boolean showHiddenTags,
             boolean showFixmeTags,
             String docTitle,
             File styleSheet)
             throws IOException, Exception {
         commentDTDs((Set)scan, sourceDir, destDir, showHiddenTags, showFixmeTags,
             true, docTitle, styleSheet);
     }
 
     /**
      * This is the main method. It chains the following tasks: <ol>
      * <li>parse the DTDs</li>
      * <li>make the documentation for each one</li>
      * <li>make the index page (the main frameset, or main page if frames are not supported)</li>
      * <li>make the introduction page (in the frame on the right)</li>
      * <li>make the TOC (frame on the left)</li>
      * <li>copy the stylesheet and other resources (images and JavaScript)</li>
      * <li>make the element index</li>
      * </ol>
      * @param scan the DTD files to analyze
      * @param sourceDir the base directory for relative path computations
      * @param destDir the destination directory to store the generated documentation
      * @param showHiddenTags tells if the content of the <code>@hidden</code> tags must be part of the documentation
      * @param showFixmeTags tells if the content of the <code>@fixme</code> tags must be part of the documentation
      * @param getAroundNetBeanComments in case you have comments that start with three hyphens, this option will
      *  tell DTDDoc to interpret them as regular double hyphens. This was introduced to support NetBeans comments.
      * @param docTitle name of the documentation: it will appear at the top of the index.
      * @param styleSheet the stylesheet to use to render the documentation: it will be copied into the documentation.
      *  If <code>null</code>, a default stylesheet is used.
      * @throws IOException in case of an error while reading the DTDs or writing the documentation
      */
     public void commentDTDs(
         Set scan,
         File sourceDir,
         File destDir,
         boolean showHiddenTags,
         boolean showFixmeTags,
         boolean getAroundNetBeanComments,
         String docTitle,
         File styleSheet)
         throws IOException {
 
         this.sourceDir = sourceDir;
         this.destDir = destDir;
         this.showHiddenTags = showHiddenTags;
         this.showFixmeTags = showFixmeTags;
         this.getAroundNetBeanComments = getAroundNetBeanComments;
 
         if (scan == null || scan.isEmpty()) {
             log.error( "No files to process ! Please note that you" +
                 " have to specify which files to include with the <include>" +
                 " tags. There's no" +
                 " automatic selection of all DTD's anymore (as of 0.0.7).");
         } else {
             destDir.mkdir();
 
             // FIXME: architecturally, this realllllly sux. Load all the
             // DTD's at once in memory... pfff... a shame :)
 
             Set parsedDTDs = parseDTDFiles( scan);
 
             makeDocumentation( parsedDTDs);
             makeIndexHtml( parsedDTDs, docTitle);
             makeIntroPageHtml( parsedDTDs, docTitle);
             makeTOC( parsedDTDs, docTitle);
             copyStyleSheets(styleSheet);
             makeElementsIndex();
         }
     }
 }