All Downloads are FREE. Search and download functionalities are using the official Maven repository.

ole.1.3.0.source-code.jcreole-ref.creole Maven / Gradle / Ivy

<>

<>

= JCreole Author Reference

<>

== Base Creole

All features listed in this section are available to all page authors.

See the [[&http://wiki.wikicreole.org/Creole%201.0|Creole 1.0 Spec]] for more
details about basic Creole directives and behavior.

=== Tips

==== Creole Authoring Tip
There are many cases where Creole directives are triggered by
non-alpha-numeric characters as the first character on a line.
Therefore, if you do not intend to write a directive, you should either avoid
or escape non-alpha-numeric characters as the first non-whitespace character
on lines.
There are several easy ways to accommodate this.
* It's generally not a problem if a new sentence begins at the start of a new
line, since sentences almost always begin with an alpha-numeric character.
* If you use your text editor in a mode where long lines wrap just visually
without adding any line delimiters, then your real Creole lines will always
begin with new sentences.
* Otherwise, one manual tactic is to manually break lines before regular words.
* Another tactic is to escape the leading non-alpha-numeric character by
prefixing it with the character "##~~##".

==== Paragraph Authoring Tip
One very general tip about nesting document elements with document authoring
systems.
Paragraphs can not nest other block elements.
This makes sense if you understand the English meaning of the word "paragraph".
//Paragraph// means a group of regular sentences, and if some text contains a
list or a sample code block or anything else, it can not be a paragraph.
Therefore, you should use a mechanism like sectioning to signify if other
blocks are dependent upon a paragraph.
Some document authoring systems (including plain HMTL) leave the author with
the incorrect impression that their instructions to nest block elements under
paragraphs are being honored, but really silently convert the elements to be
peers.
JCreole purposefully prohibits specifying blocks as children of paragraphs so
that the .creole text always accurately reflects the structure of the (eventual)
output document.


=== Plain text
Plain text is grouped into (HTML) paragraphs.
Separate paragraphs with blank lines in the wikitext.
Paragraphs will automatically end without a blank like if you trigger a
list, paragraph, or heading as described below (though it won't hurt anything
if you add a blank line also).

=== Strong text
====== ~**Like this~**
**See?**

=== Emphasized text
======~//Like this~//
//See?//

=== Table rows
======|col1 content|col2 content|col3 content
Row lines must begin with the ##|## character.
Use | to separate each cell.
Add a ##=## immediately after the | to mark the cell as a heading cell
(as opposed to a data cell).
Note that These tables are not suitable for formatting purposes (as HTML tables
are), but only for displaying tabular data.

Without coding anything special, all content for a table row must be specified
on a single wikitext line--- as you may imagine, that can be quite inconvenient.
To split a single table into multiple rows, you can end a row line with the tilde character ##~~##, or use a [[#jcsect_JcxblockCreateCustomStylableBlockElement|jcxBlock]].
|=Looks|=Like|=this
|and|like|this
|and|like|this

=== Numbered list items
======#Like this
On lines beginning with one or more ##{{{#}}}## characters, where the number of #'s indicates the list level.
There is a constraint on the list item levels allowed.
The level (number of #'s) of a row line must be less than, equal to, or one level higher than the level of the row on the previous line.
Consequently, you must //start// numbered lists with a line starting with just one #.
#Looks like this
##And
##Like this

See the [[#jcsect_HeadedListItems]] and [[#jcsect_ListEnumerationSymbols]] sections below about Jcreole enhancements.

=== Unordered list items
======*Like this
Same as Numbered lists, but use ##*## characters instead of the # characters to
identify the rows and indicate levels.
*Looks like this
**And
**Like this

See the [[#jcsect_HeadedListItems]] section below about a Jcreole list enhancement.


=== Section Headings
====== =Like this
Begin the line with from one to six ##=## characters.
One ##=## sign means a top-level ("h1" in HTML) heading, and ##======## means a lowest-level heading.\\
(The line above that says "Headings" serves as an example).

See the [[#jcsect_SectionEnumeration]] and [[#jcsect_AutomaticIdSToUseAsHyperlinkTargets]] sections below about Jcreole enhancements.

=== Bare URLs
======~http://wiki.wikicreole.org/Creole%201.0
Automatically made into hyperlinks with a label matching the URL.\\
~http://wiki.wikicreole.org/Creole%201.0

To prevent link-generation, add a tilde (##~~##) right before an URL, like
{{{~http://wiki.wikicreole.org/Creole%201.0}}} .

=== Explicit hyperlinks
======{{{[[http://wiki.wikicreole.org/Creole%201.0]]}}}
To show a label as something other than the URL, add a pipe character and the
label text right after the URL,
{{{[[http://wiki.wikicreole.org/Creole%201.0|like this]]}}}.\\
Looks [[http://wiki.wikicreole.org/Creole%201.0|like this]].

Also see the Jcreole-specific [[#jcsect_PopupLinks]] and
[[#jcsect_WindowTargetedLinks]] enhancements to explicit hyperlinks.

Inter- and intra- wiki links with colons are supported by JCreole, but require
application integration.
If your application has provided JCreole with a mapping function from wiki-link
to URL, these links will work.
You can end your Inter- and Intra- wiki references with query strings or #
anchors and the suffixes be preserved and honored.

=== Horizontal rules
======**{{{----}}}      but on a line all by itself.
Looks like...
----

=== Inline images
======~{{this.png~}}
You can add alternate text for non-graphical page viewers\\
like **##~{{this.png|alternate text~}}##**\\
You embed the ##~{{...~}}## inside of a ##~[[link...]]## to have the image hot
linked with a target URL,\\
Like **##{{{[[http://wiki.wikicreole.org/Creole%201.0|{{http://upload.wikimedia.org/wikipedia/commons/a/af/Tux.png}}]]}}}##**\\
Looks like\\
[[http://wiki.wikicreole.org/Creole%201.0|{{http://upload.wikimedia.org/wikipedia/commons/a/af/Tux.png|Alternate text}}]]

=== Preventing markup interpretation
...by prefixing the special character(s) with ~~, or by enclosing the text with
##~{{{## and ##~}}}##.
(Variable references like \${this} are not escaped with ~~.  See below about this.)
These tactics are called //escaping//, and the latter method is called //Nowiki//.
Nowiki where ##~{{{## and ##~}}}## are on separate lines with no blank space also
cause the enclosed, escaped text to be wrapped in a HTML //pre// element.\\
======{{{Works like this with <<>> __ \\ Special characters}}}.

~~ normally escapes just the special markup character following it.
The exceptions where ~~ escapes more than one following character are
(1) immediately before an URL will prevent bare-URL linking; and
(2) immediately before "##~{{{##" will escape the entire "##~{{{##".

It makes no sense to escape inside of ##~<>## (including the comment
plugins), or ##~{{{...}}}## literals, because those spans of text are already
escaped.
It is not possible to escape the closing markers for these elements because, as
I said, ~~ is not allowed in these situations.
Therefore, ~>> in a plugin tag will //always// close the current plugin, and ~}}}
will always close the current Nowki.

See the [[#jcsect_EmDash]] section about escaping hyphens.

Note that these methods escape Wikitext language interpretation, but do not
prevent changing your input to be //HTML safe// (such as translating "##>##" to
"##&gt;##", etc.).
To avoid this level of translation you would need to use the [[#jcsect_RawHtml]]
directive.

Creole variables like $[this], assuming they are enabled for your application,
can be escaped with tilde or with backslash.
Variables like \${this} can be escaped with backslash.
~{{{...}}} will escape either.
But if you know that your application does not define the referenced
variable, then you don't need to do anything, because unless you prefix your
variable name with ! or -, undefined variable references are left exactly as-is.
======With tildes like {{{$~[this].}}}
======With backslashes like {{{\}}}$~{this} and \$[this].

=== Preformatting
======~{{{\\...\\~}}}
Preformatting is extreme escaping.
Whereas escaping will prevent the special meaning for the creole text, with preformatting your white-space and formatting will be preserved and JCreole won't attempt to format it.
This is specified with a Creole-specified special case for the ~{{{...~}}} operator described in the previous item.
When the ~{{{ and ~}}} are alone on their respective lines, the interceding
text is displayed with the author-typed formatting (via HTML ##pre## tag).
Since ##pre## is usually styled with a monospaced font, it works great for
code sample blocks.
{{{
class Voila {
public:
  // Voila
  static const string VOILA = "Voila";

  // will not interfere with embedded tags.
}
}}}
You could definitely user Stylers to indent or decorate the code block however
you wish to, but most authors will want their code pretty-printed,
so see the [[#jcsect_PrettyPrintedCode]] section.

=== Hard linebreaks
======~\\
Can use multiple to create blank lines.\\\\Looks like that.


== JCreole Additions

All features listed in this section are available to all page authors.

=== Automatic id's to use as Hyperlink Targets
Take a look at the generated code and you will see id attributes written to all
of your heading elements.
You can use these as targets from ~[[...]] links on the same page, as targets
from external pages, to use in CSS selectors, or for any other purpose.
(They are also used for the TOC feature described elsewhere).

=== Automatic Link Labels
======{{{[[#jcsect_PlainText]]}}}
If you don't supply a label, then labels are created automatically when you
write links to headings/sections in the same page (these will begin with #).
(And also for inter-wiki links if your application supports that).
Note that we prefix the heading link names that we create with ##jcsect_##,
to prevent naming collisions with your own content or third party products.\\
An auto-labeled link to the Plain text section looks like this:
[[#jcsect_PlainText]].

=== Character entities
======&quot;
Just add named (not numerical) character entities and they will be preserved.\\
"see?".

=== Hard spaces
======~~      (That is a tilde followed by a space character).
This is equivalent to writing ##&nbsp;##.\\
Four such spaces looks like ~ ~ ~ ~ this.

=== Monospace fonts
======~##Like this~##
Since the HTML element "u" is deprecated, JCreole depends on the application
(or page author by using the [[#jcsect_StyleSheet]] directive) to make a CSS
class assignment like this:
{{{
  span.jcreole_underline { text-decoration: underline; }
}}}
Can you ##see?##

=== Superscript
======~^^Like this~^^
Regular ^^Super^^

=== Subscript
======~,,Like this~,,
Regular ,,Sub,,

=== Underline
======~__Like this~__
See the section below about [[#jcsect_Styling]].\\
__See?__

=== Overstrike
======~--Like this~--
See the section below about [[#jcsect_Styling]].\\
--See?--

=== EM Dash
======Like {{{---}}}
An //EM Dash// is a single long hyphen.
If you write ~--, that would not generate two hyphens, but would trigger
overstrike, due to the [[#jcsect_Overstrike]] directive.
You can avoid the Overstrike directive by writing {{{~-}}}, but I recommend the
fancier EM Dash, {{{---}}}, which looks like...\\
This---

=== Headed List Items
======#=Like|this
or
======*=Like|this
//This feature is JCreole-specific, but it is designed so as to degrade gracefully
if using another Creole engine.

This feature is a generalization paralleling table's "##|=##" option.
By suffixing the * or # list directive characters with "##=##",
 like "##{{{***}}}=##", you
 instruct JCreole to divide the list item into a heading segment and a data
 (non-heading) segment.
 The first pipe character, "##|##", in your content specifies where the heading
 ends and the data starts, in the same way as | delimits table cells.

CSS styling can be used to easily display headed list items consistently and
meaningfully, for example by displaying the data intended on a separate line.
The JCreole-supplied sample styles just bold and monospace the heading and
separate it from the data with white space.

If you submit this to a Creole engine other than JCreole, it will not know
about the special usage of ##=## and ##|## here, so that another Creole engine
would display an input line of "##{{{#=Like|this}}} as a list item with content
"##=Like|this##", but JCreole will make it look...
#=Like|this

=== List Enumeration Symbols
To change ordered list symbols from normal digits, you set a general rule for what symbols to use for ordered list items at each nesting level and/or add an enumeration symbol specifier to the first list item of the list.
Specifiers in lists override the document-level setting.

==== Document List Enumeration Symbol Rules
======{{{<>}}}
By default, ordered lists will be enumerated with the default ordered list symbol set of the presentation layer (usually HTML).
The command above says to enumerate top-level ({{{#}}}) list items like "1", "2',
"3",... to enumerate second-level ({{{##}}}) list items like "i", "ii"..., etc.

To make it clear that the ##listEnumSymbols## directive sets a state and is in no way a //part// of
any other element, it must be placed on a line by itself, separated from other content.
You can use multuple ##listEnumSymbol##s in a document, each one effecting list items from it's location down to the next ##listEnumSymbol##.

==== List-specific Enumeration Symbols
The specifier is one of 1 (default), a, A, i, I, followed immediatley by #.
The specifier immediately follows the # character(s) at the beginning of the line.
(If also specifying = to make this same item a headed list item too, then this enumeration specifier must immediately follow the = instead).

======#I# Start your list like this

#I# A roman numeral-enumerated
#   List
#   Looks like this.

=== Tabs
======#]Like|this
//This feature is JCreole-specific, but it is designed so as to degrade gracefully
if using another Creole engine.

This requires application integration,
 and the page author needs a specific privilege.

You write the tab label and the content for that tab just very similar to a
headed list item.
Start the line with ##*## followed with the label then ##|## then the content.
Write one line for each tab that you want.

If you submit this to a Creole engine other than JCreole, it will interpet
the ##*]...## lines as a regular 1-level list, with the ##]## and ##|##
characters displayed in the list item contents.

If this reference guide was built without tab support, the following will be
displayed as a regular list.
*]first tab|Contents
like this
*]second tab|Looks like this

=== Definition List
======;Definiendum like this:And definiens like this

The first colon separates the definiendum from the definiens.
Definition Lists are similar to numbered and un-numbered lists in several points
# "##;##" must be the first thing on a line to indicate the start of a
 Definition List item
# You define multiple Definition List items one after the other and they are
 automatically displayed in a single Definition List.
# Each Definition List item specification may span multiple lines (with the
 first line necessarily beginning with "##;##").
# The current Definition List item, and the aggregate Definition List will
 terminate upon a blank Creole line or block type directive (such as a
 numbered or un-numbered list, horizontal line, table row).

Definition Lists are not as powerful as lists though (and are even less powerful
 than the HTML DL+DT+DD elements that render them, due to the rather limp
 Creole specification for this directive).
 Each list item may have no more than one definiendum
 and one definiens; and the lists and items may not nest at all.

;A Definition list item
:Looks like this
;And:like this

=== Popup Links

======~[["Like"|this]]
Pops up a message.

This requires simple application integration (at least a one-line JavaScript
 function definition), and the page author needs a specific privilege.
This is exactly the same as [[#jcsect_ExplicitHyperlinks]] with double-quoted
URL and specified label.

[["The
message"|Click to see]]


=== Window-targeted Links

======~[[&~http://wiki.wikicreole.org/Creole%201.0]]
or\\
======~[[&~http://wiki.wikicreole.org/Creole%201.0|Label here]]
Same as a regular link, with or without explicit label, but targets the page
display to a new browser window (or tab, depending on your web browser and
settings).
I.e. the new web page will open elsewhere and not replace the current page.

Usage of this feature requires a specific page author privilege.

[[&http://wiki.wikicreole.org/Creole%201.0|Click to see]]


=== Variable References

======\${htmlVariableName}, $[creoleVariableName]
Variable references are coded as above.
What variables are available for expansion is entirely dependent upon how your
application has integrated JCreole.
The command-line JCreole application (which is invoked most simply by using
##java... -jar## commands) makes all Java system properties available in this
way.
Since what variables are available is application-specific, be aware that
.creole files that contain $ variable references are therefore
application-specific.
For example, if you use ##java... -jar## with a .creole file and then use
that same .creole file with some web or other application, the same variables
may not be available for expansion.

$[...] variables are only available to you if your application has enabled them.
They are dereferenced very early, and the variable values are
Creole which will be translated to HTML.
Some applications allow end-users to use $[...] references to use
application-predefined Creole macros.
Some applications may allow privileged users to write their own Creole
variable definitions (and therefore their own Creole macros).

\${...} variables are dereferenced late, and the variable values are HTML.
Most applications provide some of these variables for you to use, and some
applications let you define your own.

$(...) variables are for use in boilerplates (non-Creole template text that wraps and formats your output), and are not strictly a Creole
construct, so they are not described here.

If you will use variable references, you should be aware of the rules for their
usage.
* Variable names may contain only letters (case sensitive), numbers, dots, and
underscores.
* If the supplied variable names contain names (keys) with other characters,
those other characters are converted to underscores.
* What variables are available to your Creole page is applications-specific.
The command-line JCreole application makes Java system properties available
with prefix "sys|" so you can use Java system property ##user.name## in your
command-line .creole documents by coding ##\${sys|user.name}##.
* If the variable name is unset, then the text will remain unchanged and
\${...} or $[...] will appear in your HTML output.
* To change the behavior of the previous item to omit the reference if the
referenced variable is unset, just prefix the variable name with -.
For example, instead of writing ##\${sys|user.name}##, you would
write ##\${-sys|user.name}##.
The - has an effect only if the variable is not set.
* To change the behavior described above to cause the translation to fail if the
referenced variable is unset, just prefix the variable name with !.
For example, instead of writing ##\${sys|user.name}##, you would
write ##\${!sys|user.name}##.
The ! has an effect only if the variable is not set.
* If the JCreole output needs to contain text of the format \${this} or
$[this], for example to display EL or Javascript expressions, then
prefix the $ with backslash like {{{\}}}${this}.
(The square bracket type may also be escaped with tilde like $~~[this]).
(If you are sure that the referenced variables are not defined to JCreole,
then you don't need to do anything other than to not use the - or ! options).

== JCreole Extensions via ~<<...>> Plugin Directives

** Use of Plugin Directives is restricted.**
If you do not have the privilege needed to use a specific directive, you will
be given a precise message to that effect when you submit the wikitext.
Applications may also activate some plugin features without page author
involvement
(specifically, enumerating sections by default, and automatic generation and
display of table-of-contents).

=== Pretty-printed Code
======{{{<>}}}\\~{{{\\...\\~}}}
The ##{{{<>}}}## directive is an optional enhancement for //nowiki//
##~{{{...~}}}## preformatted blocks as described in the [[#jcsect_Preformatting]] section.
** The ##{{{<>}}}## directive may only be used on the line before a Preformatting opening ##~{{{##. **

Since nowiki ##~{{{## must always be the only thing on a line, your code to be
pretty-printed must be preceded by "##{{{<>}}}##" and then a line
containing only "##{{{{{{}}}##".
(Except that you may add CSS class specifiers right after ##prettyPrint##.
See below about that).

{{{<>}}} is not allowed inside paragraphs.
If you start a line with it after a paragraph has begun, it will end the paragraph.
{{{<>}}} is allowed inside of lists.

Sample creole:
{{{
<>
{{{
class Voila {
public:
    // Voila
    static const string VOILA = "Voila";

    public String toString() { return "me"; }
}
}}}
}}}

Generates:

<>
{{{
class Voila {
public:
    // Voila
    static const string VOILA = "Voila";

    public String toString() { return "me"; }
}
}}}

This feature does require simple http support.
If the code above is not pretty-printed, then you are viewing the standalone
mode reference doc.

JCreole uses the [[&http://google-code-prettify.googlecode.com/svn/trunk/README.html|google-code-prettify library]] to perform pretty-printing.

As shown in the example above, the word ##prettyPrint## may be followed by
CSS classes to control optional prettify behaviors, as shown in our example.
JCreole (actually google-code-prettify) can usually detect what the code
language is, but for ambiguous cases like little code snippets, you can
specify the language by CSS class like this:  ##{{{prettyPrint lang-java}}}##.
The language must be specified with one of the supported ##lang-x## class names
exactly as specified in the
[[&http://google-code-prettify.googlecode.com/svn/trunk/README.html|google-code-prettify documentation]].
The same documentation describes the ##linenums## CSS class to display line
numbers (as shown in the example above) and other features.
JCreole does not yet support prettify's //nocode// class for illustrative code
comments.

=== Raw HTML
======{{{<<~Like this>>}}}
Code HTML right into your wikitext page.
This directive is usually restricted to users with a special authorization.

=== jcxBlock: Create custom-stylable Block element
======{{{<<[>>Like this<<]>>}}}
or\\
======{{{<<[cssClassName1 cssClassName2>>Like this<<]>>}}}
You can assign CSS classes to your custom elements as shown by the second
sample here, or by using Styler directives as shown below.

Due to HTML syntax rules, you can not create a jcxBlock (or any HTML block
element) inside of a HTML paragraph.

<<[yellow>>Here is a sample that Colors a block yellow.<<]>>

=== jcxSpan: Create custom-stylable Inline element
======{{{<<{>>Like this<<}>>}}}
or\\
======{{{<<{cssClassName1 cssClassName2>>Like this<<}>>}}}
You can assign CSS classes to your custom elements as shown by the second
sample here, or by using Styler directives as shown immediately below.

Here is a sample that <<{yellow>>colors some text yellow<<}>>.

=== Stylers:  Assign CSS classes to automatic or custom HTML elements.
{{{<>}}}\\
or\\
{{{<>}}}\\
or\\
{{{<>}}}\\
or\\
{{{<>}}}\\
These samples show how to add classes to immediate parent HTML block element,
HTML inline element, jcxBlock, or jcxSpan element.

{{{<>}}}\\
Just change the ##=## to ##-## to add the class name to the //previous//
element which was closed.
This works for all 4 element types.

{{{<>}}}\\
Just change the direction character to ##+## to add the class name to the
//next// element which was closed.
This works for all 4 element types.

A few HTML elements can not be targets of stylers (i.e., you can not add
classes to them using Stylers).
Some elements are purposefully omitted because they make it more difficult to
target more important elements nearby (e.g. spans added for internal formatting
purposes and thead and tbody elements).
Elements added in a very late pass (only TOC-related elements AFAIK) can not be
targeted because the are not written until after the Stylers are applied.

<>
This is a sample that colors this HTML p element yellow.


=== Style sheet
======{{{<>}}}
CSS file links will be inserted into the HTML pages's head section.
You can use multiple styleSheet directives on a single page and the links will
be inserted in the correct order.

This plugin requires application integration to insert into the framing HTML
page.
If you have permission to use this directive, then that should all be taken
care of.

To make it clear that ##styleSheet## directives are in no way a //part// of
any other element (like a paragraph, list, or table), each ##styleSheet##
directive must be placed on a line by itself.

=== Author comments
======{{{<<#author comments>>}}}
Comments written this way never make it to the HTML page.

=== HTML comments
======{{{<>}}}
These comments can be seen by end-users who know how to view source HTML.

=== Section Enumeration
======{{{<>}}}
By default, no headings/sections in the generated page will be enumerated.
The command above says to enumerate top-level (h1) headings like "A", "B',
"C",... and to enumerate the second-level (h2) headings like "1", "2"..., etc.
This effects both headings in the main body and TOCs if you add any (see the
[[#jcsect_TocTableOfContents]] directive below).

You may only use one ##sectionEnumSymbols## directive on a single page, since there is only
one such setting for a page (and location of the directive doesn't matter).
The [[#jcsect_ResettingSectionEnumerations|sectionEnumReset]] and
[[#jcsect_TocTableOfContents|toc]] directives can be used to make
location-specific adjustments to the document-wide sectionEnumSymbols.
To make it clear that a ##sectionEnumSymbols## directive is in no way a //part// of
any other element, it must be placed on a line by itself, separated from other content.

See the [[#jcsect_EnumerationSymbolSpecificationStrings]] section below about the
meaning of the characters in the //enumerationFormats// string ("A1a1_x" above).

=== Resetting Section Enumerations
======{{{<>}}}
Far easier to explain this with an example.
Assume we start a page out with numerical ("1") enumeration symbols and this:
{{{
    === First
    === Second
    === Third
    === Fourth <>
    === Fifth
}}}
The generated section enumerations will be "1", "2", "3", "A', "B".
Note that the reset both changed the enumeration symbols and reset the
sequence counting.
If you assign the same symbol that was already in use ("1" here), then the
only effect will be to reset the counting sequence.

===TOC: Table of Contents
======{{{<>}}}
or\\
======{{{<>}}}
or\\
======{{{<>}}}
or\\
======{{{<>}}}
##toc## elements must be in a separate block.
I.e. they have to be separated from other text with a blank line.

These samples all generate a table of contents listing at the location where
you code the directive--- just like the one
[[#jcsect_JcreoleAuthorReference|at the top of this page]].
The first two samples will include/exclude sections and use enumerations symbols per the page settings.
The last two samples specify section-inclusion explicitly.
CSS classes must be specified in the TOC directive (as opposed to using Stylers) because Stylers can not effect TOCs (because the table of contents are generated by a pass after Stylers are applied).

See the [[#jcsect_EnumerationSymbolSpecificationStrings]] section below about the
meaning of the characters in the //section-inclusion string//
("{{{___xxx}}}" above).

You can include as many table-of-contents in a page as you want to.
The Java API also has getters for obtaining both TOC HTML and the data
structures, so that applications can write the TOC to a framing tile or header,
either using a pre-fab or building it manually.

To make it clear that ##toc## directives are in no way a //part// of
any other element (like a paragraph, list, or table), each ##toc##
directive must be placed on a line by itself.

===Footnotes

Add references~<> like this, and..

Mark paragraphs as footNote entries like ~<> this.
The ##footNoteEntry## directive instructs Creole to remove this paragraph from
its position in the document body and put it into the footnotes listing instead.
The paragraph may contain any regular paragraph markup, excepting
footnote, master list, and index Directives.
For reference or bibliography entries, you will often want to use
[[#jcsect_ExplicitHyperlinks]] with & [[#jcsect_WindowTargetedLinks]]
in the paragraph.

Then finally, where you want the footnote entries to appear in the document,
add...

======{{{<>}}}
or\\
======{{{<>}}}
or\\
======{{{<>}}}
or\\
======{{{<>}}}
##footNotes## elements must be in a separate block.
I.e. they have to be separated from other text with a blank line.

Just use "##~<>##" for the default footnotes layout.
"##DEF_ORDER##" specifies to list the footnotes in the sequence that the
footnotes were written (with ##footNoteEntry##s), instead of the default
order (##REF_ORDER##, the order of the first reference to each footnote in
the main document body).
To make it clear that ##footNotes## directives are in no way a //part// of
any other element (like a paragraph, list, or table), the ##footNotes##
directive must be placed on a line by itself.

You place ##footNote## directives where you want references to appear;
you place the single ##footNotes## directive where you want the footnotes
listing to appear; and you put ##footNoteEntry## directives any place at all
(because JCreole will collect all ##footNoteEntry## paragraphs into the
footnotes listing).
Write the ##footNoteEntry##s wherever it is more convenient for you.
You may want to keep them together, or maintain each one by the relevant
body content.

The entry names, ##yourEntryName## in the examples above, are arbitrary.
Though they do not appear in the generated document at all, they serve an
important purpose.
They allow multiple references (##footNote## directives) to point to a single
footnote entry.
Since you can use any names that you want to, you can use names that remind you
of what the entry is for, are easy to remember, and are easy to type.
For example, if you have a footnote entry listing your source documents for
genetic inheritance details, you could name that entry something like
//genetic-inheritance-sourcedocs// or //inheritance-src//, depending on your
compromise between conciseness and descriptiveness.

//If you click on a footnote link (superscripted digit) and the footnote text
is not displayed in a pop-up, then you are viewing a standalone mode reference doc.
In that case, your browser will scroll to the target location in the document.

==== Full Footnotes Sample

<>Second sample entry.

Main body text paragraph here, with the first reference<>
and a second reference<>.
And to show that multiple references to a shared entry work, here's a second
ref to the first entry<>.

<>First sample entry.

=====Sample Footnotes Document Section
Note that though you will usually want to insert the footnote entry listing at
the end of your document, it's awful useful for special cases like this one, to
be able to place it wherever you want to.
<>

=== Index
Mark entries in the document body ~<<(>>like this~<<)>> or
like this~<>.

Then where you want the index to appear in the document, add...

======{{{<>}}}
or\\
======{{{<>}}}
or\\
======{{{<>}}}
or\\
======{{{<>}}}

Just use "##~<>##" for the default index layout.
"##REF_ORDER##" or "##NAME_BY_JAVA##" specify to display the index entries
sorted by reference order or by Java collation of the heading text, instead of
by the default dictionary sorting of the heading text.
To make it clear that ##index## directives are in no way a //part// of
any other element (like a paragraph, list, or table), the ##index##
directive must be placed on a line by itself.

You place ##indexed## or ##(...)## directives in the document body where you
want index entries to point to; and
you place the single ##index## directive where you want the index
listing to appear.

Mark targets of index entries in the main document body using these two methods.
#When you want the index entry heading to be exactly the same as the target text
in the document body, mark the entry by surrounding the target text with
"##~<<(>>##"... "##~<<)>>##" directives.
#When you do not want the index entry heading to be exactly the same as
text in the document body, add a single "##~<>##" Directive with
parameter of exactly what the text of the index entry heading will be.

For the first method, enclose just the target text, not markup, or the markup
characters may appear in the generated heading.
If you don't want to deal with that, then just use the second method.

==== Full Index Sample

Main body text paragraph here, with the first index target<>
and a second index target<>.
And to show that multiple index targets for a shared entry work, here's a second
target for the first entry<>.

Another paragraph with <<(>>two instances<<)>> of index targets.  Here's a third target for the multi-entry <<(>> first  Entry  <<)>>.

=====Sample Index Document Section
Note that though you will usually want to insert the index at
the end of your document, it's awful useful for special cases like this one, to
be able to place it wherever you want to.
<>

===Master Definition List

Add ~[[entryName|explicitly labelled reference]]s or default-labelled
references like this: ~[[entryName]], and...

Mark paragraphs as master definition entries like ~<> this.
The ##masterDefEntry## directive instructs Creole to remove this paragraph from
its position in the document body and put it into the masterDefList listing instead.
The paragraph may contain any regular paragraph markup, excepting
footnote, glossary, and index Directives.
Then finally, where you want the definition entries to appear in the document,
add...

======{{{<>}}}
or\\
======{{{<>}}}
or\\
======{{{<>}}}
or\\
======{{{<>}}}
##masterDefList## elements must be in a separate block.
I.e. they have to be separated from other text with a blank line.

Just use "##~<>##" for the default list layout.
"##REF_ORDER##" or "##NAME_BY_JAVA##" above are samples of (optional)
specification for ordering of the list entries.
The supported values are
*=NAME_BY_DICTIONARY|Definienda are sorted with dictionary collation. **
 This is the default setting.**
*=NAME_BY_JAVA|Same as NAME_BY_DICTIONARY except Java collation is used.
*=DEF_ORDER|List is displayed in the same exact order as you authored the
 entries (i.e. the order of your ##masterDefEntry## directives).
*=REF_ORDER|List is displayed in the order of the first reference to each one
 in the main document body.
To make it clear that ##masterDefList## directives are in no way a //part// of
any other element (like a paragraph, list, or table), the ##masterDefList##
directive must be placed on a line by itself.

A Master Definition List is a generalization of a glossary.
One Creole document can have only one master definition file (hence //master//).
Add definitions for any words, terms, phrases, or whatever you want to
explicitly define for your audience.

You place explicit link directives where you want references to appear;
you place the single ##masterDefList## directive where you want the entry
listing to appear; and you put ##masterDefEntry## directives any place at all
(because JCreole will collect all ##masterDefEntry## paragraphs into the
entry listing).
Write the ##masterDefEntry##s wherever it is more convenient for you.
You may want to keep them together, or maintain each one by the relevant
body content.

Notice that you write links to definition entries as
[[#jcsect_ExplicitHyperlinks]].
Each explicit hyperlink in your document with a relative URL (i.e.
not #localAnchor URL and not absolute URL and not wiki:link) is checked against
all def list entries.
If the URL matches a master definition list entry name, then it is linked to it.

Multiple links can point to a single definition entry.
Definition entries do not need to be linked to at all.

//If you click on a reference link  and the definition text
is not displayed in a pop-up, then you are viewing the standalone mode reference doc.
In that case, your browser will scroll to the target location in the document.

==== Full Master Definition List Sample

=====Sample Master Definition List Section
You can insert the Definition List wherever you want to in your document.
<>

<>Office manager.

Main body text paragraph here, with the [[Scott, Michael]] auto-labelled link,
and a second [[Beasley, Pam|explicitly labelled link]].
And to show that multiple references to a shared entry work, here's a
[[Scott, Michael|second link to the Scott entry]].

<>Saleswoman.  Previously the office receptionist.


==Styling <>

This section of the reference guide explains how to style text beyond the
abilities of the basic text styling directives ([[#jcsect_StrongText]],
[[#jcsect_EmphasizedText]], [[#jcsect_MonospaceFonts]], etc.).

If you have permissions to use the [[#jcsect_StyleSheet]] directive, then you
can customize the appearance and layout of the many un-classed elements that
JCreole generates, as well as the several CSS classes that JCreole writes for
this purpose.

===Styling arbitrary HTML Elements
To avoid unintended consequences to the framing HTML page, you should always
narrow your CSS selectors.
Since applications should always wrap JCreole-generated content with a
##jcreole## div, you should narrow with ##div.jcreole##.
For example, say you want to color all divs and paragraphs blue,
you should not style with
{{{
    div, p { background-color: blue; }
}}}
but with
{{{
    div.jcreole div, div.jcreole p { background-color: blue; }
}}}

===Available JCreole-generated CSS Classes
The following CSS selectors are useful for targeting styles as described.

*=div.jcreole|The entire block of JCreole-generated content.\\
(JCreole sets this class in the provided framing boilerplate, we set it in all
of our applications, and recommend that integrators do the same, but we can't
guarantee that applications will provide it.)
*=span.jcreole_underline|You (or your application) should normally
style this class as ##text-decoration:underline##.
*=span.jcreole_orphanLink|You can infer the purpose.
*=table.jcreole_data}Generated tables
*=table.jcreole_even|Even numbered body rows of generated tables
*=table.jcreole_odd|Odd numbered body rows of generated tables
*=div.jcx|[[#jcsect_JcxblockCreateCustomStylableBlockElement|jcxBlocks]].
*=span.jcx|[[#jcsect_JcxspanCreateCustomStylableInlineElement|jcxSpans]].
*=div.jcx_toc|HTML ##div## container for [[#jcsect_TocTableOfContents]].\\
Present whether table generated by programmatic calls or by toc directive.
*=ul.jcx_toc|HTML ##ul## container for [[#jcsect_TocTableOfContents]].\\
Present unless your application generates the TOC table HTML itself.
*=span.jcreole_nowiki|Inline ~{{{...~}}} Nowiki as described in the
[[#jcsect_PreventingMarkupInterpretation]] section.
*=span.jcx_enum|Section enumeration labels in body headings and in
table-of-contents (but the latter may be overridden with following class name).
This does style the § character as well as the varying string.
If you want stylings to apply only to body heading tags, then narrow your
selectors with heading tag names.
*=div.jcx_toc span.jcx_enum|Same as previous but only applies to
enumeration labels inside of table-of-contents, and only if the t-o-c HTML is
generated by JCreole (as opposed to by your application).
*=span.jcreole_hbody|Heading tag text content.
Includes any section enumeration formatting (i.e., these elements include
jcx_enum spans, if any).
Narrow the selector with heading tag names for heading-level-specific styling.
*=span.jcreole_lh|Heading segment of [[#jcsect_HeadedListItems]], analogous to a table ##th## cell.
*=span.jcreole_ld|Data segment of [[#jcsect_HeadedListItems]], analogous to a table ##td## cell.

Class names with the string "jcx" instead of "jcreole" are for management of
Plugin-specific functionalities.
For example, class names related to tables are prefixed with "jcreole_" since
tables are a basic Creole 1.0 feature;
but class names related to table-of-contents are prefixed with "jcx_" since
table-of-contents are implemented as a JCreole plugin and there is no such
feature in basic Creole.

As mentioned in the relevant sections above, by default JCreole generates no
section enumerations or table-of-contents, so setting the CSS classes for those
functions will have no effect if you or your application don't enable the
feature.

===Pretty-printing CSS Classes

If your JCreole system has been set up with pretty-printing support, then you
can use or modify the CSS classes written by the google-code-prettify
Javascript library.
The [[&http://google-code-prettify.googlecode.com/svn/trunk/README.html|google-code-prettify web site]]
is the definitive source for documentation about google-code-prettify CSS.

==Enumeration Symbol Specification Strings

An //enumeration symbols string// is a 6-character string that specifies what symbols to use to enumerate each of the six heading/section levels or ordered-list nesting levels.
For example, in the ##sectionEnumFormat## specification "##{{{A0a1__}}}##", ##A## specifies the
formatting for level 1 headings (//h1//'s), ##0## specifies the formatting for
level 2 headings, etc.

=== Formatting characters

Each character in the enumeration formatting string specifies the formatting of
level indicated by the character's position, as follows.

*=A:|A, B, C, D...
*=a:|a, b, c, d...
*=0:|0, 1, 2, 3...  (at this time available only for headings/sections, not for ordered lists)
*=1:|1, 2, 3, 4...
*=i:|i, ii, iii, iv... (at this time available only for ordered lists, not for headings/sections)
*=I:|I, II, III, IV... (at this time available only for ordered lists, not for headings/sections)
*=_ or x:|//no label// for headings/sections; //default symbol// for ordered lists.  (There is no difference between ##_## and ##x## except for building TOCs for sections/headings as explained in the [[#jcsect_InclusionCharacters]] section).

We intend to add support for additional formatting symbols in the future
(especially ##I## and ##i## for headings/sections.

=== Section-inclusion Strings

Table-of-contents may display all section levels, or may exclude specified
levels.

A //section-inclusion string// is a 6-character string that specifies inclusion
of a heading/section for each of the 6 supported  heading levels.
For example, in the specification "##{{{x_0101}}}##", ##x## specifies inclusion
(or in this case exclusion) for level 1 headings (//h1//'s), ##_##
specifies inclusion for the level 2 heading, etc.

=== Inclusion characters

Each character in the section-inclusion string specifies inclusion or exclusion
of the level indicated by the character's position, as follows.

* **x**  Exclude headings of this level from the TOC.
* **_** or **A** or **a** or **0** or **1**

To state this more generally, the character x means to exclude the level, and
any other //supported// character means to include the level---
where the supported characters are characters listed in the list in the
[[#jcsect_FormattingCharacters]] section.

You can completely control section inclusion/exclusion by using just the
characters ##x## and ##_##.
The only reason we support the alternative characters in place of ##_## is
so you can make up one optimized enumeration-formatting + section-inclusion
string that can fulfill both purposes.
I.e. you could use the same exact string in both ##{{{<>}}}## and
##{{{<>}}}## directives.




© 2015 - 2025 Weber Informatics LLC | Privacy Policy