JCX = JCreole Extensions.  Implemented as Creole <<...>> plugin/extensions.


Creole authors use extensions (aka plugins) by coding <<...>> elements in their Creole text.  

This file does not document all JCreole features beyond those of Creole 1.0.
It only documents those that are controlled with the Extension/Plugin mechamnism
of <<X>> directives.
See the file "additions.txt" for JCreole features that do not depend on Plugin
directives.

I call the individual <<X>> commands that are available "Plugin Directives".
(I don't call them "elements" in order to eliminate ambiguity because of the resemblance to XML Elements).


DESIGN

    JCreole's syntax is normally <<directiveName>> (notice camelBack) or
    <<directiveName options...>>, with exceptions for the following exceptional
    elements:
        <<~...>>  <<[>>  <<]>>  <<{>>  <<}>>   <<#... >>  <<!... >>
    The justification is that the [,],{,} directives need to block code, in
    pairs, and that purpose will be easier to recognize without other
    intervening and distracting text;
    The purpose of the other exceptions here is to defeat markup parsing, so
    as they are special beasts, it is intuitive for them to appear special.

    All security-impacting extensions are enabled/disabled at the Scanner
    instance level.  This can be used, for example, to prevent "comment"
    authors from altering style, or to only allow authorized users to code
    raw HTML.

    Still under consideration, but though I "could" allow for setting element
    IDs and HTML tag attributes, I think that purposefully not supporting
    operations targeted to single HTML elements will encourage general and
    re-usable layout management.
    
    As things are currently implemented, the user is forced to assign CSS
    classes.  If the user intends to use the class for just one element-- no
    harm done and it will work-- but the user may just find it useful that they
    can re-use that same class elsewhere in the page.  The <<@ element further
    encourages generalization further to use custom class names across
    multiple pages and even multiple web sites.


Plugin Directives by category
-----------------------------

In every case, white space (including newlines) is permitted between the opening
"<<" and the first non-whitespace character.

RAW HTML

    <<~...>> Direct HTML content.

    Justification of ~ character:  In Creole, ~ generally means "escape Wiki
    markup formatting".

    Even Nowiki does not let you enter HTML into a web page, because of the
    real danger of either unintentionally or intentionally invoking dynamic
    content, breaking HTML DOM structure, etc.  For example, if double-quotes
    are not escaped, there are many different ways that you could accidentally
    unbalance the quotes, easily effecting otherwise unrelated JavaScript (and
    depending on server-side technology integration, even server-side
    scripting).

    BEWARE that inside of <<~...>>, you are responsible for the consquences of
    missing the very strict requirements of CSS, HTML, JavaScript, or whatever
    you code in there.


CREATE ELEMENTS

    <<[>>  Open a new JCX DIV element with '<div class="jcx">'.
    <<]>>  Close the previously opened JCX DIV with '</div>.
    <<{>>  Open a new JCX SPAN element with '<span class="jcx">'.
    <<}>>  Close the previously opened JCX SPAN with '</span>.

    You should obviously always pair <<[>> with <<]>>,and pair <<{>> with <<}>>.

    N.b. unlike JCreole paragraphs, lists, and tables, neither jcxBlocks nor
    jcxSpans auto-close.  You must always explicitly close with <<]>> or <<}>>.
    This is required to disambiguate cases of recursive nestings which basic
    Creole deals with by just prohibiting it.

    JCX Span directives are placed exactly the same as Creole inline elements.
    I.e., you can add "<<{>>" wherever you can add, for example, "//"; and
    between "<<{>>" and "<<}>>" you can insert anything that you can insert
    between two "//"s.

    As Creole page authors are responsible for balancing and not tangling __
    and ** directives, JCreole page authors are responsible for balancing and
    not tangling __, **, and <<{>>/<<}>> directives.
    Unlike Creole ** and __ directives, however, jcxSpans are self-nestable.
    __ and ** will continue to auto-close where necessary, but jcxSpans and
    (and jcxBlocks) will not.

    JCX Div directives may be placed at the top/root document level (i.e. where
    you could put a "=" element), plus anyplace where you can put inline
    elements (like //), with the following special cases.
    HTML paragraphs may not contain block elements.  Therefore, just as
    Creole paragraphs may not contain a tables or lists, they may also not
    contain JCX Divs.  JCX Divs may reside inside of another JCX Div.
    Perhaps the most useful consequence of this is that table cells or list
    items may contain JCX Divs.
    A JCX Div may contain inline elements and other JCX Divs.  I.e. they
    support recursion.  But they can not contain paragraphs, tables, or lists
    (if at some point I can get the parser to allow these, I'll make it so).

    A general consequence of the previous rules is that with plain 1.0 Creole,
    the Creole line-beginning statements like *, =, {{{ will work anywhere,
    because tables and lists auto-close when any non-table/non-list line
    follows and paras auto-close when the *, =, {{{, etc. are encountered.
    These line-beginning statements are not honored inside of jcxBlocks,
    however, because jcxBlocks do not auto-close (i.e. jcxBlocks do auto-close
    other elements, but jcxBlocks themselves to not get auto-closed).


STYLERS == "addClass" plugin directives:  Assign a CSS class to an HTML element

    <<addClass =block className>>
        Add CSS class to the immediate containing non-JCX block element.
    <<addClass =inline className>>
        Add CSS class to the immediate containing non-JCX inline element.
    <<addClass =jcxSpan className>>
        Add CSS class to the immediate containing JCX SPAN element.
    <<addClass =jcxBlock className>>
        Add CSS class to the immediate containing JCX BLOCK element.

    To simplify and shorten these descriptions, I'm specifying only one class,
    but you can give any number of class names.

    Next is same as above, but with "-" instead of "=".  Target the preceding
    closed element instead of the immediate containing element:

    <<addClass -block className>>
        Add CSS class to the preceding closed non-JCX block element.
    <<addClass -inline className>>
        Add CSS class to the preceding closed non-JCX inline element.
    <<addClass -jcxSpan className>>
        Add CSS class to the preceding closed JCX SPAN element.
    <<addClass -jcxBlock className>>
        Add CSS class to the preceding closed JCX BLOCK element.

    Next is same as above, but with "+".  Target the next
    element instead of the immediate containing element:

    <<addClass +block className>>
        Add CSS class to the next non-JCX block element.
    <<addClass +inline className>>
        Add CSS class to the next non-JCX inline element.
    <<addClass +jcxSpan className>>
        Add CSS class to the next JCX SPAN element.
    <<addClass +jcxBlock className>>
        Add CSS class to the next JCX BLOCK element.

    Note that "<<... -..." means the last previous element CLOSED, not the last
    element opened.  So, with nested "em" and "strong" elements, if we have
        //emphasized **strong** closing// <<addClass -inline aName>>
    the name applies to the last inline CLOSED, which here is <em> for the //.

(CONVENIENCE:  <<{>> and <<[>> also take optional class names, in which case
the directive is equivalent to the corresponding open directive + addClass
directives.  E.g.:
    "<<{class1 class2}>>"
    ==
    "<<{>><<addClass =jcxSpan class1>><<addClass =jcxSpan class2>>
    ==
    "<<{>><<addClass =jcxSpan class1 class2>>
)


DEFINE CSS STYLES

    (Deferred until HTML 5:
        <<$ style line definitions...  >>  The aggregate of all <<$...>> element
        contents will be inserted inside one
            <style type="text/css" scoped="scoped">...</style>
        element (preserving sequence) before the generated HTML content.)

    <<styleSheet CSS/file.path  >>  A CSS file link will be added to the HTML
    page header.  If multiple <<styleSheet...>> directives are given, then
    multiple links will be added, matching the sequence of the directives.
    Each link tag will be of the form
        <link rel="stylesheet" type="text/css" href="..." />
    Note that the integrator must call the method
     CreoleParser.getHeaderInsertion() to get the HTML that should be inserted
     into the HTML page's head.  If you use JCreole.generateHtmlPage, then
     you just need to have the string "${headers}" in the head of the
     boilerplate.

    CONSIDER  Allowing CSS style coding directly in a <<?...>> tag, which we
    would insert into a <link> element in the page head.
    I am thinking that it would encourage consistency more to force the user to
    upload a separate .css file and just reference that.


COMMENTS

    <<# author comments... >>
    Your comment text may not include the string ">>".
    These contents will be entirely stripped.  I.e. they will not be visible as
    HTML comments, or in any other way, in the generated HTML.

    <<! HTML comments... >>
    Your comment text may not include the strings "--" or ">>".
    These will not be visible as HTML comments in the generated HTML.


SECTION ENUMERATION
    
    <<sectionEnumSymbols A1a1_x>

    By default, sections enumerations are not shown in the page body headings
    nor in TOCs.  Use the directive above or the
    CreoleParser.setEnumerationFormats() method to enable display of
    header/section enumeration labels.

    <<sectionEnumReset  A>>   only inside Headings

    This command resets sequencing for the heading level of the current
    (containing) Heading.  The single character serves the same purpose as the
    6 characters of the enumerationFormats string, but for just the current
    heading level (the character values are described in the next paragraph).
    (See example below).

    The characters of the 6-char enumerationFormats String indicate whether to
    enumerate that heading level and with what kind of enumeration.
    As of today, the options are 'a', 'A', '0', '1', '_', and 'x'.
    '_' and 'x' are equivalent (they are differentiated only so that you can
    use the same string as a TOC levelInclusions string as described in the
    next section).  The other characters indicate what the enumeration label
    will be for the first items at that level.
    (TODO:  Add I and i for upper-case and lower-case Roman numerals).

    Example:
        <<sectionEnumSymbols _1a1ax>>
        == First section
        ...  Your main document body, including may sections
        == <<sectionEnumReset  A>> First Appendix
    In this example, the main body will have section enumeration like
    "2.c.4.b" (author does not want to use h1).  But when the Appendix starts,
    enumeration will be reset and the enumeration format changed so that the
    first appendix will be labeled like a fancy version of "A  First Appendix".


ORDERED-LIST ENUMERATION

    <<listEnumSymbols 1iaA__>

    ##A# Explicit symbol for this list

    The document rule listEnumSymbols works very similarly to sectionEnumSymbols.
    The specifier string uses the same format.
    But listEnumSymbols are location specific and you can use more than one in a single doc.


TABLE OF CONTENTS

    Insert a TOC list, with hyperlinks to all headings.

    <<toc>>  or <<toc ___xxx>>

    Where the 6-character "levelInclusion" string ("___xxx" in the sample)
    specifies which header levels to include (and which to skip) in the TOC.

    Entries in the table with display section enumerations according to the
    section enumeration settings described in the previous section.
    The generated HTML is designed to facilitate external styling via CSS.

    Each character of the levelInclusion string is either 'x' to skip entries
    for that level, or '_' (or 'a', 'A', '0', or '1' equivalently if you will
    also use the string as an enumerationFormats String).


Coming Maybe.  UNDER CONSIDERATION

    <<:IntraWikiLink>>
    Because plain IntraWikiLink is too susceptible to false positives.
    Maybe better is just to interpret link destinations beginning with ":"
    as intra-wiki links.  Sounds good to me...
