263 lines
8.9 KiB
Plaintext
263 lines
8.9 KiB
Plaintext
.imply(header.ids)
|
|
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
|
|
Complete Syntax
|
|
````````````````````````````````
|
|
As is the case with most any syntax, the best way to learn is to view the end product and the syntax used to generate it.
|
|
|
|
To avoid creating examples of every syntax permutation possible, this section is organized in the following manner:
|
|
* Type of Element
|
|
* General description
|
|
* Special rules
|
|
* Example(s) and Source(s)
|
|
,,,,,,,,,,,,,,,,,,,,,,,,
|
|
1. Formatting rules
|
|
````````````````````````
|
|
,,,,,,,,,,,,,,,,
|
|
.imply
|
|
````````````````
|
|
# .imply(header.ids,header.depth=2)
|
|
|
|
imply rules influence the parsing and conversion of markup on a document-wide level. Through these rules, you can change header sizing behaviors, output tables of contents, create logical sections of converted elements for use in visual styling, and much more.
|
|
|
|
This line must start at the end and/or the beginning of the document and contains the rules inside the ".imply()" formatter.
|
|
|
|
**Possible .imply values:**
|
|
* //header.ids// -- create ids for every header from header text. Replaces spaces with underscores.
|
|
* //header.depth// -- set the starting depth of headers. Defaults to 0.
|
|
* //header.reverse// -- sets smaller headers to be considered as greater, e.g., "==== header ====" is greater than "====== header ======"
|
|
* //header.numbering// -- automatically number headers relative to a parent header and prepend this value to the header content.
|
|
* //version.hide// -- embeds the version of kettext used to create the document in a hidden format. Otherwise is added as a footer.
|
|
* //version.none// -- completely removes version information from the output.
|
|
|
|
Other rules can be implied via the command-line. These override the kettext file's imply rules when a conflict arises. Example:
|
|
|
|
# kettext.pl my_file.ktx --header.ids --header.depth=2
|
|
,,,,,,,,,,,,,,,,
|
|
Element formatters
|
|
````````````````
|
|
# **boldface**.id(alt_bold)
|
|
|
|
Formatters are a set of options that influence the outputted **element**'s styles. These are used by a **Convertor** engine to create particular visual styling. For the [[HTML Convertor]].href(#HTML_Converter), this means applying a class, a style, or any other supported option for a given element tag. Don't clutter your markup source with HTML when you can apply it in a more generalized and clean manner.
|
|
|
|
The placement of formatters varies between the elements, but the general syntax is:
|
|
|
|
# .some_option(some_value).other_option(other_value)
|
|
,,,,,,,,,,,,,,,,,,,,,,,,
|
|
2. Font styling and anchors
|
|
````````````````````````
|
|
Font may be styled by surrounding a section of text around specific delimiters.
|
|
|
|
**example:**
|
|
|
|
# I am **bold**, but I can also be //italic//
|
|
# I am also ((small))!
|
|
# I may also contain ``code``!
|
|
# I can also be an [[anchor]], but you need an [[href]].href(#Font_styling_and_anchors)!
|
|
|
|
I am **bold**, but I can also be //italic//
|
|
I am also ((small))!
|
|
I may also contain ``code``!
|
|
I can also be an [[anchor]], but you need an [[href]].href(#Font_styling_and_anchors)!
|
|
|
|
----
|
|
Styled text may have formatters appended to them:
|
|
|
|
**example:**
|
|
|
|
# **bold**.class(super_bold)
|
|
|
|
**bold**.class(super_bold)
|
|
|
|
----
|
|
If using an HTML convertor, you can pass CSS styling directly:
|
|
|
|
**example:**
|
|
|
|
# **bold**.style(font-size:16pt;color:#AA2299;)
|
|
|
|
**bold**.style(font-size:16pt;color:#AA2299;)
|
|
|
|
# [[link]].href(http://kettek.exoss.net).style(border:1px solid red)
|
|
|
|
[[link]].href(http://kettek.exoss.net).style(border:1px solid red)
|
|
,,,,,,,,,,,,,,,,,,,,,,,,
|
|
3. Headers
|
|
````````````````````````
|
|
A header is some prominently formatted text that precedes a larger section of text and acts as a demarker. Headers are sized in order of precedence, with larger visual headers being considered the parent of smaller headers contained within.
|
|
|
|
Due to kettext's flexible design, header sizing is calculated after document parsing. For HTML conversion, the header with the largest lead will be "<h1>", with smaller leads increasing in number thereafter. If **header.reverse** is set, this behavior is reversed, and the header with the smallest lead is set to "<h1>", with larger leads increasing from there.
|
|
|
|
In kettext, there are two styles of headers, big and small. These styles may be mixed, although big headers have a size precedence over small, so results will be varied.
|
|
|
|
Header contents may have //text styling// applied.
|
|
|
|
,,,,,,,,,,,,,,,,
|
|
Small Headers
|
|
````````````````
|
|
Small headers are similar to other markup languages' headers, but allow for more flexibility in plain text.
|
|
|
|
**example**:
|
|
|
|
#==== //Example Header// =====
|
|
==== //Example Header// ====
|
|
|
|
----
|
|
|
|
Small headers may use any character to signify their lead or close. A space is also required after the lead:
|
|
|
|
**example**:
|
|
|
|
#~~~~ Example Tilde'd Header ~~~~
|
|
~~~~ Example Tilde'd Header ~~~~
|
|
|
|
----
|
|
|
|
Small headers do not require a close:
|
|
|
|
**example**:
|
|
|
|
#==== Example Header Without Close
|
|
==== Example Header Without Close
|
|
|
|
----
|
|
|
|
If the close-style is used, the close must match the lead:
|
|
|
|
**example**:
|
|
|
|
#==== Example Header Without Close ----
|
|
==== Example Header Without Close ----
|
|
|
|
----
|
|
|
|
Formatters are applied at the end of the header content.
|
|
|
|
**example**:
|
|
|
|
#==== Example Header With Formatter .class(alt_header) ====
|
|
==== Example Header With Formatter .class(alt_header) ====
|
|
|
|
#==== Example Header With Formatter .class(alt_header)
|
|
==== Example Header With Formatter .class(alt_header)
|
|
|
|
,,,,,,,,,,,,,,,,
|
|
Big Headers
|
|
````````````````
|
|
Big headers are headers that span 3 lines and may have a more stylized visual. They are also the preferred header style of the author.
|
|
|
|
**example**:
|
|
|
|
#,,,,,,,,,,,,
|
|
#Example Big Header
|
|
#````````````
|
|
,,,,,,,,,,,,
|
|
Example Big Header
|
|
````````````
|
|
----
|
|
Big headers can use any character for the head and the lead. They are not required to match.
|
|
|
|
**example**:
|
|
|
|
#____________
|
|
#//Big Header//
|
|
#------------
|
|
____________
|
|
//Big Header//
|
|
------------
|
|
----
|
|
Formatters are placed at the end of the content line:
|
|
|
|
**example**:
|
|
|
|
#,,,,,,,,,,,,
|
|
#Big Header .class(big_alt)
|
|
#````````````
|
|
|
|
,,,,,,,,,,,,
|
|
Big Header .class(big_alt)
|
|
````````````
|
|
,,,,,,,,,,,,,,,,,,,,,,,,
|
|
4. Text Blocks
|
|
````````````````````````
|
|
Text blocks are a larger collection of text that may span multiple lines. kettext uses 4 unique text blocks: **paragraph**, **preformatted**, **code**, and **block quote**.
|
|
|
|
Universal to all text blocks is the special ".include" command. This command searches for the given file relative to the file being parsed and includes it. For **preformatted** and **code** this file is __unparsed__. For **paragraph** it replaces the paragraph block with the parsed file. //.imply// rules are inherited from the parent kettext file being parsed.
|
|
,,,,,,,,,,,,,,,,
|
|
Paragraph
|
|
````````````````
|
|
A paragraph is a section of text that spans one or more lines. A section of text will continue as a single paragraph until an empty line is found.
|
|
|
|
**example:**
|
|
|
|
# This is a multi-line paragraph
|
|
# that continues to here.
|
|
#
|
|
# This is a **second paragraph**, note the above empty line.
|
|
|
|
This is a multi-line paragraph
|
|
that continues to here.
|
|
|
|
This is a **second paragraph**, note the above empty line.
|
|
----
|
|
Formatters may be applied by having a separate formatter line at the start of the paragraph.
|
|
|
|
**example:**
|
|
|
|
# .class(alt_paragraph)
|
|
# This is a formatted paragraph.
|
|
|
|
.class(alt_paragraph)
|
|
This is a formatted paragraph.
|
|
,,,,,,,,,,,,,,,,
|
|
Preformatted
|
|
````````````````
|
|
Preformatted text is a section of text that is unprocessed by kettext and put within its own paragraph-like section. Every line must be indented by a tab, 2 spaces, or 4 spaces.
|
|
|
|
**example:**
|
|
|
|
# .class(alt_pre)
|
|
# This is preformatted text and
|
|
# it can span multiple lines.
|
|
# //font styling// is **ignored**!
|
|
#
|
|
# and will continue if an indented, but otherwise empty, line is found.
|
|
|
|
.class(alt_pre)
|
|
This is preformatted text and
|
|
it can span multiple lines.
|
|
//font styling// is **ignored**!
|
|
|
|
and will continue if an indented, but otherwise empty, line is found.
|
|
,,,,,,,,,,,,,,,,
|
|
Code
|
|
````````````````
|
|
Code text is a section of text that is also unprocessed by kettext and follows the same general rules as preformatted. Every line must be indented by a tab, 2 spaces, or 4 spaces, and followed by a '#'.
|
|
|
|
**example:**
|
|
|
|
# #.class(alt_code)
|
|
# #This is code text and
|
|
# #it can span multiple lines as well.
|
|
# #//font styling// is **ignored**!
|
|
# #
|
|
# #it also continues if an indented empty line is provided.
|
|
|
|
#.class(alt_code)
|
|
#This is code text and
|
|
#it can span multiple lines as well.
|
|
#//font styling// is **ignored**!
|
|
#
|
|
#it also continues if an indented empty line is provided.
|
|
,,,,,,,,,,,,,,,,
|
|
Blockquotes
|
|
````````````````
|
|
Blockquotes are unprocessed sections of quoted text. They are signified by the first character of a line being a '>'.
|
|
|
|
**example:**
|
|
|
|
#>.class(alt_block)
|
|
#> This is a block quote. If blockquote.parse is not set, //font styling// is **ignored**!
|
|
|
|
>.class(alt_block)
|
|
> This is a block quote. If blockquote.parse is not set, //font styling// is **ignored**!
|