Package eu.bandm.tools.dtm

Class HtmlRenderer

java.lang.Object
eu.bandm.tools.rdparser.TunableParser<XMLDocumentIdentifier>
eu.bandm.tools.rdparser.TunableParserForXml<XMLDocumentIdentifier>
eu.bandm.tools.dtd.TunedDTDParser
eu.bandm.tools.dtm.HtmlRenderer
public class HtmlRenderer extends TunedDTDParser
Collects some references and creates an interactive HTML documentation.

Implementation stratgy: There is a complete parsed DTD (given to the constructor by the argrument "dtd") and there is the source text. The source is parsed a second time and copied to the output, after being wrapped into HTML elements according to the parameters and the cross-reference info in the Dtd object.

ATTENTION this class inherits from "TunedDTDParser", but is used for incomplete functionality, so that many field values are under-defined and can be irritating, esp. when in "PARSED-dtd" they have the same name (e.g. "this.entityUsage" is totally undefined, and "parsedDtd.entityUsage" is meant!)

After the instance has been created, printHtml(OutputStream,String,String,File,ToolOptions,String) must be called.
The current implementation renders a primitive html document which (modulo color) CAN LOOK EXACTLY like the dtd source.

Indeed, color, links and tool-tips are added for easy orientation: All colors are defined by css classes for <span>, <a>, <p> elements, etc.
Anchors are given to (the start of)

  • each element definition,
  • each entity declaration,
  • each attlist

The backward-compatible "@name" attribute is no longer supported; only "@id" is generated, which is appropriate for all currently existing browsers.

Links are put accordingly,

  • from element references in content models, to element declarations,
  • from entity references in content models, to entity declarations,
  • from entity references in attlists, to entity declarations,
  • from entity references in entity values, to entity declarations,
  • from element references in entity values, iff the entity is used in a content model anywhere,
  • between the heads of attlists and content declarations for the same tag.
PENDING element references, entity references and attlists are marked specially.

TOOLTIPS are given

  • with element references, showing content model and attribute names
  • with entity references, showing definition or replacement text.
Currently there is one single switch --expandTooltips for switching all tooltips between definition text and expanded(=effective) text.

Attlists stand a little bit aside and are reachable by links in a cyclic way:

  • from element definition header to the sequence of attlists,
  • and from the last attlist back to the element.

When the NAME in a definition (content model or attlist) is given by a parameter entity, than the switch --expandDefNames decides what to show. The cyclic links through elements and attlists are the same as above, but additionally the tooltip is prepended with the other variant, and, iff shown, the character "%" is a link to the definition place.

Preparing all this syntactic information requires expansion, but the goal for verbatim visual presentation forbids. Therefore the method of choice is a two(2)-phase approach: The successfully parsed dtd model and the unparsed text are both parameters to this process.
The original layout shall be kept verbatim. The parsing process from TunedDTDParser is partly overridden, most analysis is skipped and reduced to mere verbatim character copying. The required syntax information is taken from the dtd model.
Nearly all generated output is contained in one top-level "&lt;pre>" element, which is the most-light-weight way of making browsers respect whitespace and line-breaks.

Switching visibility goes by java-script. It operates on PAIRS OF SIBLINGS:

  • a FIRST "&lt;span>" element carries the "onclick" code for expanding its successor and collapsing itself. It is additionally marked by the dedicated class "dtd_meta_switch".
  • the FIRST CHILD of the SECOND SIBLING "&lt;span>" carries the "onclick" code for expanding the predecessor of its parent and collapsing its parent.
  • the code for "expand all"/"collaps all" searches for the switch-on spans and identifies their flavour by a certain "indicator class", which can appear with the first or second child of the second span. 
   pre
    |
    |  (<=== ON/OFF PAIR ====>)                            (
    +-----------------------+------------------------(-------
    |                       |                        (
   span                    span 
   style="display:none;"   style="display:block;"
   class=dtd_meta_switch    |                                (
   onclick=switchon()       +------------------+-------------(-+----
    |                       |                  |             ( |
    |                   span(/div/?)        span          (span   
        div(/i/?)               onclick=switchoff() |             (
         |                                          class="dtd_attlist_decl"
         |  --> arbitrary nesting                  (=indicator class!)
         |                                            
   #PCDATA
    "switchOnText"
Seen from the standpoint of the following code, there is the additional level of "content" packing: 
   pre
    |
    +-------------------------+-------------------------------
    |                         |
   pre.Content               pre.Content
   span class=meta_switch    span class=PI/Comment/Eldef etc
   switchOnText               |
   onclick=switchon()         +----------------+-------------(-+----
                              |                |             ( |
                             span.Content     span.Content   (span.Content 
                          span             span           (span         
                                  onclick=switchoff()

=============================================================
Attention : The base classes have a different wording w.r.t errors: they use "MessageGenerator" and provide "error()", "warning()" etc. "msg" is not known there.
=============================================================

  • Field Details

  • Constructor Details

  • Method Details

    • isDynamic

      protected boolean isDynamic(ToolOptions.visibility m)

    • firstPart

      protected ToolOptions.visibility firstPart(ToolOptions.visibility m)

    • entityGraphFileName

      public static String entityGraphFileName(String resultFileName)

    • elementGraphFileName

      public static String elementGraphFileName(String resultFileName)

    • anchorEntityName

      public static final String anchorEntityName(String name, boolean parameter)
      For anchors in generated html.

    • anchorName

      public static final String anchorName(DTD.Element e)

    • anchorName

      public static final String anchorName(DTD.Attlist a, int count)

    • codekey2anchorname

      public static final String codekey2anchorname(String s)

    • prepareTooltips

      public void prepareTooltips(boolean expand)
      Collect tool-tip text for element references.
      FIXME with [(text)+] toFormat() omits parentheses !?!?!

    • peRef2deftext

      protected String peRef2deftext(String entname)
      A pe REF can be dangling! ONLY in this case null is returned.

    • containsPERefs

      protected boolean containsPERefs(String s)
      ATTENTION GERefs will also be signalled !?!?! ATTENTION external PERefs will also be signalled !?!?! With "conventional" usage both facts should not be confusing.

    • expandedText

      protected String expandedText(DTD.Element e)
      ATTENION "mode=1" ??? FIXME WAS SOLL DAS BEDEUTEN ?? append the content model behind each "DTD.Abbrev"

    • expandedText

      protected String expandedText(DTD.Attlist a)

    • expandedText

      protected String expandedText(DTD.Entity e)
      ATTENTION intended only for INTERNAL PARAMETER entities!

    • append

      protected void append(Element_a a)
      Append to top-level list (either in spanLists or the lsit preItems).

    • append

      protected void append(Element_span a)
      Append to top-level list (either in spanLists or the lsit preItems).

    • open_span_region

      protected void open_span_region()
      push a new (intially empty) list of span.content, for later reducing it to a single content element.

    • throwAwaySpanRegion

      protected void throwAwaySpanRegion()

    • _close

      protected void _close(String switchOnText, ToolOptions.visibility visible, String switch_on_class)
      Take the currently top-level (currently growing) list "Ln" of span elements. Pop this list off the stack and pack its contents according to the mode switch. If off, then discard, if on, then append it to the next higher list "L(n-1)" Otherwise create the on-switch and append this and Ln to the L(n-1). (Assume off-switch already contained at the beginning of Ln!)

    • close_region_and_prepend_switch

      protected void close_region_and_prepend_switch(String switchtext, ToolOptions.visibility visible)
      Special values for text and css class, but operation as in _close(String, ToolOptions.visibility,String)}.

    • close_region_and_prepend_switch_external_entity_content

      protected void close_region_and_prepend_switch_external_entity_content(String switchtext, ToolOptions.visibility visible)
      Special values for text and css class, but operation as in _close(String, ToolOptions.visibility,String)}.

    • consume

      protected void consume()
      CALL-BACK function, influencing the parsing functionality of the super-class to store all character data in the buffer consumed.
      Overrides:
      consume in class TunableParser<XMLDocumentIdentifier>

    • throwAwayConsumed

      protected void throwAwayConsumed()

    • checkCssClass

      protected void checkCssClass(String cssClass)

    • spanC

      protected Element_span spanC(String contents)

    • spanCC

      protected Element_span spanCC(String contents, String cssClass)

    • anchorCH

      protected Element_a anchorCH(String contents, String href)

    • reduce_a

      protected Element_a reduce_a(String cssClass, String ownAnchor, @Opt @Opt String foreignAnchor, String tooltip)
      Append an xhtml "anchor" object to the currently growing list. (No further effects on the list stack!) Assume name of target element has just been consumed, but not yet reduced. The generated text field is also a "link" = "jump START", iff foreignAnchor != null.
      Returns:
      the visibible part to which a tooltip can be attached.

    • reduce_span

      protected Element_span reduce_span(String cssClass)
      Append an xhtml "span" object containing ALL characters accumulated in the buffer consumed, with the given (non-null, non-empty!) css class. Flush that buffer. (No further effects on the list stack!)

    • reduce_span

      protected Element_span reduce_span()
      Substitute the "css class for the rest, which has no own class"

    • reduce_switchOff

      protected void reduce_switchOff(String cssClass, ToolOptions.visibility currentmode)
      Do the same as reduce_span(String), but additionally set the onclick-action, iff ToolOptions.visibility is dynamic.

    • insert_switchOff

      protected void insert_switchOff(String text, String cssClass, ToolOptions.visibility currentmode)
      Do the same as reduce_switchOff(String, ToolOptions.visibility), but not with accumulated source text, but with synthetic, explicit text (probably in a Dtd "comment" syntax !-)
      Is required for insertion of external parameter entities and additional print-outs like graphics and analyses!

    • reduce_element_reference

      protected void reduce_element_reference()
      Output either a link to the definition, as calculated by the global "object to anchor" mechanisms, or a span, iff the reference is void/dangling!
      INCLUDES PARSING, ie. everything before the name has been flushed from the consumed buffer, and no component of the name has been parsed/consumed.

    • reduce_entity_reference

      protected DTD.Entity reduce_entity_reference(boolean parameter)
      Output either a link to the definition, as calculated by the global "object to anchor" mechanisms, or a span, iff the reference is void/dangling!
      INCLUDES PARSING, ie. everything before the lead-in character has been flushed from the consumed buffer, and the lead-in character has just been recognized, but not consumed.

    • scanForReferences_contentModel

      protected void scanForReferences_contentModel()
      Parses an element definition's content model and outputs all sub-segments correctly wrapped to the html element list. IGNORES all syntactic structure, except explicit parameter entity references, plain identifiers and the special identifier for content models. (All other character data is copies transparently into the current output buffer and reduced at the end of this method into on span element one level above!) Assume "#EMPTY" already intercepted one level above.

    • scanForReferences_attOrEnt

      protected void scanForReferences_attOrEnt(boolean inSingleQuotes, boolean inDoubleQuotes, boolean possiblyElementRefs)
      Parses the definition string of a entity defintion, or a whole sequence of attribute definition entries. IGNORES all syntactic structure, except explicit entity references, and quoted string constants. Is called for top-level of attribute list and for the defining text of an entity declaration, both after the name(). So even the top-level quotes are not yet recognized when entering. Can be called recursively at most three times (due to quote variants).

    • s

      protected void s()
      Parsing function for non-optional whitespace, at those places where expansion pf PEs is allowed. MUST only be called from TOP-LEVEL dtd parser. The PEs referred to must expand to "files" (=external pe), and syntactically to a sequnence of zero or more COMPLETE top-level mark-up declarations. (MUST NOT be called INSIDE of attlist or element decl, for these situations there are DEDICATED parsing routines!)
      Overrides:
      s in class TunedDTDParser

    • xmlDecl

      protected DTD.XmlDecl xmlDecl()
      Description copied from class: TunedDTDParser
      Parsing function.
      Overrides:
      xmlDecl in class TunedDTDParser

    • includeTrailingWs

      protected void includeTrailingWs()
      Consume whitespace before the "close span region()" is called, so that the whitespace will be part of collapsing/exploding/skipping.

    • pi

      protected DTD.PI pi()
      Description copied from class: TunedDTDParser
      Parsing function.
      Overrides:
      pi in class TunedDTDParser

    • comment

      protected DTD.Comment comment()
      Description copied from class: TunedDTDParser
      Parsing function.
      Overrides:
      comment in class TunedDTDParser

    • elementDecl

      protected DTD.Element elementDecl()
      Parsing AND rendering function, EXTENDED COPY of super():
      Overrides:
      elementDecl in class TunedDTDParser

    • content_match

      protected void content_match(String keyword)

    • conditionalSection

      protected void conditionalSection(DTD.Dtd dtd)
      Parsing function.
      Overrides:
      conditionalSection in class TunedDTDParser

    • entityDecl

      protected DTD.Entity entityDecl()
      Parsing AND rendering function, EXTENDED COPY of super():
      Overrides:
      entityDecl in class TunedDTDParser

    • skip_entityDef

      protected void skip_entityDef()

    • collectAttlistSource

      protected void collectAttlistSource(String name)

    • attlistDecl

      protected DTD.Attlist attlistDecl()
      Parsing AND rendering function, DEEPLY CHANGED COPY of super(): Entities can appear anywhere and cover more than one "column". Relies on ">" not appearing outside of (single/double) quotes.
      Overrides:
      attlistDecl in class TunedDTDParser

    • initModes

      protected void initModes(ToolOptions options)
      Sets the global boolean flags etc. according to the supplied options. Non-trivial interdependencies are calculated. Output differences accumulates the diagnosis whether and why the pure text differs from the original.

    • intern

      protected ToolOptions.visibility intern(ToolOptions options, ToolOptions.visibility optionMode)
      Option still does not use enumerations. Go from int via string array to interal enumeration value! FIXME

    • readMode

      protected ToolOptions.visibility readMode(boolean present, boolean isFileInsert, boolean isAdditional, String name, ToolOptions.visibility code, ToolOptions options)
      Processes on/off/onOff/offOn-switches. (1) whether feasible, otherwise trunc them, (2) collect whether result is dynamic, (3) add diagnosis which category in initial doc state differs from original.

    • makeHeadline_dtd_coords

      protected void makeHeadline_dtd_coords(String alternative, boolean dynamic, String cmdline, String date, String userText)

    • makeMassSwitches

      protected void makeMassSwitches(boolean withInstructions)
      assume only called if "htmlIsDynamic==true"

    • checkMassSwitch

      protected void checkMassSwitch(ToolOptions.visibility visible, boolean present, String text, String cssClass, List<Element_span.Content> ons, List<Element_span.Content> offs)

    • makeFooter

      protected Element_p makeFooter(String basicFileName, String url_htmlRenderer_docu)

    • makeSvg

      protected void makeSvg(File outputfile, String title, Multimap<String,String> relation, String altText, String switchText, String mapIdentifier, ToolOptions.visibility visibility)
      DOCME

    • append_list_all_references

      protected void append_list_all_references(Set<String> c, int maxColumn, Function<String,String> getClass)

    • append_list_all_references

      protected void append_list_all_references(Set<String> c, int maxColumn, Function<String,String> getClass, Function<String,String> getHref)

    • insertAlphaindex

      protected void insertAlphaindex(ToolOptions options)

    • insertAnalyses

      protected void insertAnalyses(ToolOptions options)

    • printHtml

      public void printHtml(OutputStream os, String dtdFileName, String outfilename, @Opt @Opt File outputdir, ToolOptions options, String cmdLineText)
      Main (currently: the only) entry method after constructor call. Writes an html rendering to the output. ATTENTION mode xhtml_stand_alone CURRENTLY WRITES NOTHING ?? FIXME
      Called from dtm.Tool.main and from tdom.TDOM_Main.
      ATTENTION renderedDtd.js COUNTS pre-elements and ASSUMES nr 2 contains all expandable items FIXME !!
      Parameters:
      os - where to send the generated HTML text. Assert that it has UTF_8 encoding.
      dtdFileName - DOCME
      outfilename - local name of the written html text. Used only to derive the names of the svg files, if any, and for one single warning, if it ends not with "html")
      outputdir - directory of the written html text, there the svg files will be placed. When null, svg generation is suppressed.
      options - needed for all the fine-tuning switches. Can come from a command line, or can be constructed explicitly when html rendering is initiated programmatically. (Therefore the options already decoded into the other method parameters are ignored.)
      cmdLineText - DOCME