Package eu.bandm.tools.dtm

Class HtmlRenderer

  • public class HtmlRenderer
extends TunedDTDParser
    Collects some references and creates an interactive HTML documentation.

    Principle: There is a complete parsed DTD (given to the constructor by param "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 object has been created, #printHtml(Writer,String,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

    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 definiton (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 Detail

      • path_to_stylesheet

        public static final java.lang.String path_to_stylesheet
        See Also:
        Constant Field Values

      • path_to_javascript

        public static final java.lang.String path_to_javascript
        See Also:
        Constant Field Values

      • href_bandm_online_docu

        public static final java.lang.String href_bandm_online_docu
        See Also:
        Constant Field Values

      • infotext_bandm_online_docu

        public static final java.lang.String infotext_bandm_online_docu
        See Also:
        Constant Field Values

      • class_meta_switch

        public static final java.lang.String class_meta_switch
        See Also:
        Constant Field Values

      • class_meta_generated

        public static final java.lang.String class_meta_generated
        See Also:
        Constant Field Values

      • class_copyright_comment

        public static final java.lang.String class_copyright_comment
        See Also:
        Constant Field Values

      • class_ent_include

        public static final java.lang.String class_ent_include
        See Also:
        Constant Field Values

      • class_ent_ignore

        public static final java.lang.String class_ent_ignore
        See Also:
        Constant Field Values

      • class_ent_p_ref_UNDEF

        public static final java.lang.String class_ent_p_ref_UNDEF
        See Also:
        Constant Field Values

      • class_ent_p_ext_ref

        public static final java.lang.String class_ent_p_ext_ref
        See Also:
        Constant Field Values

      • class_ent_p_ext_content_frame

        public static final java.lang.String class_ent_p_ext_content_frame
        See Also:
        Constant Field Values

      • class_ent_p_ext_content

        public static final java.lang.String class_ent_p_ext_content
        See Also:
        Constant Field Values

      • class_ent_p_ext_nonshow

        public static final java.lang.String class_ent_p_ext_nonshow
        See Also:
        Constant Field Values

      • class_ent_g_ref_UNDEF

        public static final java.lang.String class_ent_g_ref_UNDEF
        See Also:
        Constant Field Values

      • class_el_ref_UNDEF

        public static final java.lang.String class_el_ref_UNDEF
        See Also:
        Constant Field Values

      • class_att_def_DANGLING

        public static final java.lang.String class_att_def_DANGLING
        See Also:
        Constant Field Values

      • class_att_ref_UNDEF

        public static final java.lang.String class_att_ref_UNDEF
        See Also:
        Constant Field Values

      • expandTooltips

        protected boolean expandTooltips

      • expandEntities

        protected boolean expandEntities

      • expandContents

        protected boolean expandContents

      • expandAttlists

        protected boolean expandAttlists

      • expandDefNames

        protected boolean expandDefNames

      • separator_content_attlist

        protected java.lang.String separator_content_attlist

      • eatWs

        protected boolean eatWs

      • output_linewidth

        protected int output_linewidth

      • content_linewidth

        protected int content_linewidth
        The width after the first two columns.

      • max_tooltip_width

        protected int max_tooltip_width

      • DISTANCE_TOOLTIP_OVERALL_WIDTH

        public static final int DISTANCE_TOOLTIP_OVERALL_WIDTH
        See Also:
        Constant Field Values

      • DISTANCE_CONTENTS_OVERALL_WIDTH

        public static final int DISTANCE_CONTENTS_OVERALL_WIDTH
        See Also:
        Constant Field Values

      • htmlIsDynamic

        protected boolean htmlIsDynamic

      • outputFormatIsDynamic

        protected boolean outputFormatIsDynamic

      • hasPEs

        protected boolean hasPEs

      • outputDifferences

        protected java.lang.String outputDifferences

      • el2tooltip

        protected final java.util.Map<DTD.Element,​java.lang.String> el2tooltip
        Map of elements to Strings with content-plus-attributenames

      • ent2tooltip

        protected final java.util.Map<DTD.Entity,​java.lang.String> ent2tooltip

      • parsedDtd

        protected final DTD.Dtd parsedDtd

      • statistics

        protected final Statistics statistics

      • preItems

        protected java.util.List<Element_pre.Content> preItems
        Output storage of constructed html elements, top-level, i.e. contents of the top-level xhtml [pre] element.

      • spanLists

        protected java.util.Stack<java.util.List<Element_span.Content>> spanLists
        Stack of layers BEYOND the preItems, i.e. levels of nesting of [span] xhtml elements.

      • last_appended_span

        protected Element_span last_appended_span
        Memo for a-posteriori modification (FIXME besser raus)

      • consumed

        protected java.lang.StringBuilder consumed
        Temporary storage of consumed input characters, fed by overriden "consume()" below.

      • fileInsertionNumber

        protected int fileInsertionNumber

      • dummy_PI

        protected final DTD.PI dummy_PI

      • dummy_comment

        protected static final DTD.Comment dummy_comment

      • dummy_element

        protected static final DTD.Element dummy_element

      • attlistCount

        protected final java.util.Map<java.lang.String,​java.lang.Integer> attlistCount

      • lastAttlist

        protected final java.util.Map<java.lang.String,​Element_a> lastAttlist

      • attributeSourceText

        protected final java.util.Map<java.lang.String,​java.lang.String> attributeSourceText

      • attributeSourceToolTip

        protected final Multimap<java.lang.String,​Element_a> attributeSourceToolTip

      • shortname2graphanchor

        public static java.util.function.Function<java.lang.String,​java.lang.String> shortname2graphanchor
        ATTENTION must be in synch with renderedDtd.js, because there the back-calculation to text anchors takes place !?

      • shortname2usertext

        public static java.util.function.Function<java.lang.String,​java.lang.String> shortname2usertext

      • span_ref_list_spacer

        public static final Element_span span_ref_list_spacer

      • peDefCheck

        final java.util.function.Function<java.lang.String,​java.lang.String> peDefCheck

      • geDefCheck

        final java.util.function.Function<java.lang.String,​java.lang.String> geDefCheck

      • gePeCheck

        final java.util.function.Function<java.lang.String,​java.lang.String> gePeCheck

      • const_ent_p_ref

        final java.util.function.Function<java.lang.String,​java.lang.String> const_ent_p_ref

      • const_el_ref

        final java.util.function.Function<java.lang.String,​java.lang.String> const_el_ref

      • const_el_ref_UNDEF

        final java.util.function.Function<java.lang.String,​java.lang.String> const_el_ref_UNDEF

    • Method Detail

      • entityGraphFileName

        public static java.lang.String entityGraphFileName​(java.lang.String resultFileName)

      • elementGraphFileName

        public static java.lang.String elementGraphFileName​(java.lang.String resultFileName)

      • anchorEntityName

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

      • anchorName

        public static final java.lang.String anchorName​(DTD.Element e)

      • anchorName

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

      • codekey2anchorname

        public static final java.lang.String codekey2anchorname​(java.lang.String s)

      • prepareTooltips

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

      • peRef2deftext

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

      • containsPERefs

        protected boolean containsPERefs​(java.lang.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 java.lang.String expandedText​(DTD.Element e)
        ATTENION "mode=1" ??? FIXME WAS SOLL DAS BEDEUTEN ?? append the content model behind each "DTD.Abbrev"

      • expandedText

        protected java.lang.String expandedText​(DTD.Attlist a)

      • expandedText

        protected java.lang.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​(java.lang.String switchOnText,
                      ToolOptions.visibility visible,
                      java.lang.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!)

      • 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​(java.lang.String cssClass)

      • spanC

        protected Element_span spanC​(java.lang.String contents)

      • spanCC

        protected Element_span spanCC​(java.lang.String contents,
                              java.lang.String cssClass)

      • anchorCH

        protected Element_a anchorCH​(java.lang.String contents,
                             java.lang.String href)

      • reduce_a

        protected Element_a reduce_a​(java.lang.String cssClass,
                             java.lang.String ownAnchor,
                             java.lang.String foreignAnchor,
                             java.lang.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 reduceed.

      • reduce_span

        protected Element_span reduce_span​(java.lang.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​(java.lang.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​(java.lang.String text,
                                java.lang.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

      • includeTrailingWs

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

      • content_match

        protected void content_match​(java.lang.String keyword)

      • skip_entityDef

        protected void skip_entityDef()

      • collectAttlistSource

        protected void collectAttlistSource​(java.lang.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.

      • readMode

        protected ToolOptions.visibility readMode​(boolean present,
                                          boolean isFileInsert,
                                          boolean isAdditional,
                                          java.lang.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​(java.lang.String alternative,
                                       boolean dynamic,
                                       java.lang.String cmdline,
                                       java.lang.String date,
                                       java.lang.String userText)

      • makeMassSwitches

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

      • makeFooter

        protected Element_p makeFooter​(java.lang.String basicFileName,
                               java.lang.String url_htmlRenderer_docu)

      • makeSvg

        protected void makeSvg​(java.io.File outputfile,
                       java.lang.String title,
                       Multimap<java.lang.String,​java.lang.String> relation,
                       java.lang.String altText,
                       java.lang.String switchText,
                       java.lang.String mapIdentifier,
                       ToolOptions.visibility visibility)
        DOCME
        Parameters:
        filename - the relative or absolute path where to put the result file ?? FIXME

      • append_list_all_references

        protected void append_list_all_references​(java.util.Set<java.lang.String> c,
                                          int maxColumn,
                                          java.util.function.Function<java.lang.String,​java.lang.String> getClass)

      • insertAlphaindex

        protected void insertAlphaindex​(ToolOptions options)

      • insertAnalyses

        protected void insertAnalyses​(ToolOptions options)

      • printHtml

        public void printHtml​(java.io.Writer output,
                      java.lang.String dtdFileName,
                      java.lang.String outfilename,
                      @Opt
                      @Opt java.io.File outputdir,
                      ToolOptions options,
                      java.lang.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:
        output - the Writer to create the html file.
        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
        dtdTitle - ??????? FIXME used as the html title (to appear in browser head lines, etc)