blox Plugin Markup Guide == Welcome == This entry is a guide to the markup notation built into the *_blox* plugin_, v0.98. To best display this page, the blox configurable variables [=$break_singles] and [=$styles_active] should both be set to 1. If everything is set well, the next sentence will be on its own line. This should be a separate line, and *these six words should be bold*. === Overview === The *_blox* plugin_ has some very simple styling shortcuts built in, as part of its job to make your entry-typing easier. The shortcuts are based on [Brian Ingerson's Kwiki module http://www.kwiki.org] (the "official" [blosxom wiki http://wiki.oreillynet.com/blosxom/]), with modifications to be a touch more versatile and to allow existing html markup. The notation appears to be very robust -- this whole page is formatted without a single html tag (barring 4 examples of "real" tags), and the markup doesn't break or bog down. The following text explains and illustrates using this simple markup in your entry files. Comments about markup success or failure appear to the right of examples, indicated by "<--". Examples of "what to type" are presented in comments as [=code]. The last line(s) in each section demontrate how to escape (negate) the markup. === _Heads_ === Put 1 to 6 "=" at start of line, then a space, then head text and end-of-line. Optionally, put a space and matching number of "=" after head text. Escape by preceding with "!". 1) = Here's an H1 == Here's an H2 === Here's an H3 ==== Here's an H4 ===== Here's an H5 ====== Here's an H6 1a) Trailing "=" must balance leading "=", or they won't be removed [==== Wups ====] === Wups ==== 2) The next line is styled; type it like this: [=== !/Styled H2/] == /Styled H2/ 3) The next line fails; there is no space between "=" and the head text ==Not an H2 4) The next line fails; too many spaces between "=" and the head text: [=== Not an H2] == Not an H2 5) The next line fails; "=" must be first character on line: This is == not an H2 6) The next line puts equals signs in heads; type it like this (note the trailing space): "[===== == Equals Signs in Heads == ]" (no quotes) ==== == Equals Signs in Heads == 7) The next two lines demonstrate escaping headline markup: !=== Negation <-- escaping; type it like this: [=!=== Negation] !==== Negation ==== <-- escaping; type it like this: [=!=== Negation ===] ---- === _Rules_ Four "-" at start of line; nothing else on the line. Escape by preceding with "!". 1) The next line fails due a space after "[=---- ]": ---- 2) The next line is an escape; type it like this: [=!----] !---- 3) The next line is a rule, which breaks the rule about escape examples being the last line, and ends this section ;-) ---- === _Bold_ (actually, <strong>) Enclose single-line words with "*". Escape by preceding with "!". 1) This is a *test* of bold. <-- one word... 2) This is *a 6-word test of bold*. <-- ...or several: [=!*a 6-word test of bold*] 3) This is a t*est of bo*ld. <-- fails; words not enclosed: [=a t*est of bo*ld] 4) This is a* test of* bold. <-- fails; words not enclosed: [=a* test of* bold] 5) "*bold within plain double quotes*" <-- [="!*bold within plain double quotes*"] 6) This is a !*test* of UNbolding. <-- escaping; type it like this: [=!!*test*] ---- === _Italic_ (actually, <em>) Enclose single-line words with "/". Escape by preceding with "!". 1) This is a /test/ of italic. 2) This /is a test of/ italic. <-- [=This !/is a test of/ italic.] 3) This /is a test o/f italic. <-- fails; words not enclosed: [=/is a test o/f] 4) '/Italic within single quotes/' <-- [='!!/Italic within single quotes/'] 5) This is a !/test/ of UNitalicizing. <-- escaping; type it like this: [=!!/test/] ---- === _Bold-Italic_ ... 1) This is a */test/* of bold-italic. <-- [=!*!/test/*] 2) */This is a test/* of bold-italic. <-- [=!*!/This is a test/*] 3) *This /is a test/* of bold-italic. <-- [=!*This !/is a test/*] 4) *This /is a test*/ of bold-italic. <-- this works: [=!*This !/is a test*/] 5) *This /is a test* of/ bold-italic. <-- this works, too: [=!*This !/is a test* of/] 6) Th*is i/s a test/* of bold-italic. <-- fails; words not enclosed: [=Th!*is i!/s a test/*] 7) This i*/s a test/* of bold-italic. <-- fails _poorly_; words not enclosed: [=i!*!/s a test/*] 8) !*Escaping !/bold-italic*!/. <-- escaping; type it like this: [=!!*Escaping !!/bold-italic*!!/] (The final "!" is just to be safe against further "/" in the line ;-) ---- === ...and _Italic-Bold_ 1) This is a /*test*/ of italic-bold. <-- [=!/!*test*/] 2) /*This is a test*/ of italic-bold. <-- [=[!/!*This is a test*/] 3) /This *is a test of*/ italic-bold. <-- [=!/This !*is a test of*/] 4) /This *is a test of/* italic-bold. <-- this works: [=!/This !*is a test of/*] 5) /This *is a test/ of* italic-bold. <-- this works, too: [=!/This !*is a test/ of*] 6) Th/is i*s a test*/ of italic-bold. <-- fails; words not enclosed: [=Th!/is i!*s a test*/] 7) This i/*s a test*/ of italic-bold. <-- fails _poorly_; words not enclosed: [=i!/!*s a test*/] 8) !/Escaping !*italic-bold/!*. <-- escaping; type it like this: [=!!/Escaping !!*italic-bold/!!*] (The final "!" is just to be safe against further "*" in the line ;-) ---- === _Underline_ Enclose single-line words with "_". Escape by preceding with "!". When combined with other styles, underline must be the innermost markup. 1) This is a _test_ of underline. 2) This is _a test of_ underline. 3) This is a test of _under_line. <-- fails; words not enclosed: [=!_under_line] 4) This is a *_bold /slant/ on underline_*. <-- [=!*!_bold !/slant/ on underline_*] 5a) For compound styles, */_underline must be innermost_/* <-- [=!*!/!_underline must be innermost_/*] 5b) Fails; *_/underline must be innermost/_* <-- [=!*!_!/underline must be innermost/_*] 5c) Once more; _*Underline-bold*_ fails, but *_bold-underline_* works <-- [=!_!*Underline-bold*_ fails, but !*!_bold-underline_* works] 6) This is a !_test_ of UN_under_lining. <-- escaping; type it like this: [=!!_test_] 7) !*!/!_Escaping/ compound* styles_ <-- type it like this: [=!!*!!/!!_Escaping/ compound* styles_] ---- === _Code_ Enclose any text with "![=" and "]"; multi-line works, so make sure you close it! Escape by preceding with "!". (there's just about no way coding can fail.) 1) This is a [=test of coding]. <-- ![=[=test of coding]] 2) [=This is a test of coding]. <-- ![=This is a test of coding] 3) This is a te[=st of coding]. <-- a te![=st of coding] 4) [=This is a multi-line test of coding: This is line 2... This is line 4, the final line.] <-- if you forget this close, get ready for lots of unwanted [=code]! 5) Th![=is is a t]est ![=of UNco]ding. <-- escaping; type it like this: Th!![=is is a t]est !![=of UNco]ding. ---- === _"Raw" URL Linking_ Enclose single-line URLs with "[" and "]"; URLs must begin with "http:" or "ftp:" or "irc:". Escape by preceding with "!". 1) A test of raw linking: [http://www.example.com]. <-- [=![http://www.example.com]] 2) A raw ftp link: [ftp://ftp.example.net]. <-- [=![ftp://ftp.example.net]] 3) A raw link: [ http://example.com]. <-- fails; space between [ and http: [=![ http://example.com]] 4) Style /within/ a link [http://www.*example*.com]. <-- cute, but goes nowhere: [=![http://www.!*example*.com]] 5a) Bold link *[http://www.example.com]*. <-- works with "!*" enclosing link: [=!*![http://www.example.com]]* 5b) Italic link /[http://www.example.com]/. <-- works with "!/" enclosing link: [=!/![http://www.example.com]]/ 5c) Underline link _[http://www.example.com]_. <-- works with "!_" enclosing link: [=!_![http://www.example.com]]_ 6) This is a test of UNlinking ![http://www.example.com]. <-- type it like this: [=!![http://www.example.com]] 7) UNlinking styled links !*![http://example.org/styled_links]!*. <-- !!*!![http://example.org/styled_links]!!* (The final "!" is just to be safe against further "*" in the line ;-) ---- === _"Named" URL Linking_ Enclose single-line link name, a space, and complete URL with [ and ]. Escape by preceding with "!". 1) A test of [named linking http://www.example.com]. <-- [=![named linking http://www.example.com]] 1a) A [9-named w~h%a//c[k]y link http://www.example.com]. 2) A [named ftp link ftp://ftp.example.com]. 3) A na[med link http://www.example.com]. <-- fails; words not enclosed: [=na![med link http://www.example.com] 4) A named[ link http://www.example.com]. <-- fails; space between [ and name: [=[ named http://example.com]] 5a) A styled [*named link* http://www.example.com]. <-- markup enclosing /name/ works OK: [=![!*named link* http://www.example.com]]. Style tags are enclosed by the <a>_</a> tags: [=<a href="http://www.example.com"><strong>named link</strong></a>] 5b) A /styled [named link http://www.example.com]/. <-- markup surrounding /[ and ]/ works OK: [=!/![named link http://www.example.com]]/. Style tags are enclosed by the <a>_</a> tags: [=<em<<a href="http://www.example.com"<named link</a<</em<] 6) This is a test of ![named UNlinking http://www.example.com]. <-- [=!![named UNlinking http://www.example.com]] 7) UNlinking styled ![!*named links* http://example.org]. <-- !![!!*named links* http://example.org] ---- === _URL sanity-check_ These "normal" links (i.e. [=<a href="http://example.com">link<!/a>]) should not be altered by blox formatting: 1) link 1 2) link 2 3) link 3 ---- === Not "Bugs" -- /anomalies/ ;-) This markup always does what it should; it's just not very bright. 1) Path-like text may be mistaken for italic: /Library/WebServer/Documents/<-- looks like one word: [=!/Library/WebServer/Documents/] The fix is to escape such sequences: [=!!/Library/WebServer/Documents/] 1a) Note that _this_ path-like text is OK, as it looks like improper markup: /Library/WebServer/Documents <-- [=!/Library/WebServer/Documents] 1b) This anomaly will not bother you in properly marked raw or named links. 2) As illustrated in *_Raw URL Linking* 4)_, there's nothing preventing you from styling elements within an address, even though such links won't go anywhere. 3) To prevent styling /within/ words (which would cause big headaches for me to code ;-), an underscore character cannot preceed a bold or italic style. Thus, as illustrated in *_Underline* 5)_, whenever you want to combine bold and/or italic with underlining, the underline markup _must be innermost_. 4) There is nothing in blox to prevent you from doing silly things, such as bolding some text that's already been bolded by html tags (*oops?* <-- see browser's source view). You're even free to break your html by doing something like this: [=<PR![=woops]E> Failed PRE block</PRE>] 5) While it's not silly, it bears repeating -- if you want to document html tags in a <PRE> block, the arrows need to be typed in as "entities": "<" typed in as [=&lt;], and ">" typed in as [=&gt;]. You can't use markup to style text within a <PRE> block. *Of course,* if you do find a bug in this markup system, let me know by writing to the blosxom list, or by posting at [http://groups.yahoo.com/group/blosxom/messages/]. ---- === Can't do/To do... The blox markup notation does not do lists or tables; lists may be coming, tables won't be. There are no plans for mailto: addresses. You can't do anchors, but they may be coming. I'm not sure if styling will be "ignorable" thru the noblox file... maybe via any of the several [=config] plugins. You can't style your entry's title with blox; not sure if that will be added.... You can't style text within <PRE> blocks; no plans to do so. ---- === Roll Your Own... If [=<em>] and [=<strong>] aren't your cup of tea, change 'em! There are two instances of "em>" (p'bly change to "i>"), and two instances of "strong>" (p'bly change to "b>") in the script. To use a config plugin to turn styling on/off, look for [=my $styles_active =] in the Configuration Section, and change the whole line to [=$styles_active = 0 unless defined $styles_active;]. ---- === Hope You Enjoy! I hope I havent crossed the line between simplicity and convenience by adding this simple markup system to blox; if you don't like it, turn it off by setting the [=$styles_active] configurable variable to 0 (zero). Love it, hate it...let me know. Thanx, and enjoy! - S2 blox [=v0.97 2004.07.22]