Goal
Replicate and enhance some local customisations from PmWiki 1 in PmWiki 2, as a single MarkupExtensions package. For details, see the list of extensions.
It provides the following types of capability:
- improve the look and readability of pages by displaying em or en dashes, smart quotes, arrows, fractions, ™ and the like
- improve the structure of pages using footnotes, teaser paragraphs, sticky notes, run-in headings and the like
- enhanced markup support, such as
<dfn>,<cite>,<kbd>, small caps, drop caps
Solution
Please note. The PublishPDF library includes the current version of the MarkupExtensions recipe.
Version 2.1.1 works with PmWiki 2.2.56 or above. It requires php 5.3 or above and is compatible with php 5.5 (no more /e in calls to Markup).
For PmWiki 2.2.55 and below:
Use extendmarkup_pre44.phpΔ with versions of PmWiki before the introduction of $SiteGroup in beta 44.
Put extendmarkup.php and break_page.php in the PmWiki cookbook/ directory (you may have to create it).
To use the markup.css file, put markup.css in the pub/css/ directory and add the following line to local/config.php :
$MarkupCss = true;
followed by:
include_once("$FarmD/cookbook/extendmarkup.php");
include_once("$FarmD/cookbook/break_page.php");
- Aside
- Why is the script called “extendmarkup” and the css is just called “markup”?
See the change log (edit) for a history of this recipe. The latest entry in the change log is:
- 27 April 2006 — fix (I mean really fix) problem with title markup in pmwiki 2.1 (marcon title extension)
- 28 and 30 March 2006 — revise for compatibility with pmwiki 2.1
- 21 September 2005 — revert to standard AsSpaced, plus smartening; thanks to Hans
Note. Some extensions present in an early version are now part of PageTableOfContents. The aim is to allow different recipes to operate independently of one another.
Discussion
See Discussion at MarkupExtensions-Talk.
This adds a range of markup extensions to PmWiki 2. It combines into a single script a whole lot of separate items from PmWiki 1, adds some more, and fixes one or two minor bugs.
All extensions are now optional, controlled through the $MarkupExtensionsFmt array. This is set to:
SDV($MarkupExtensionsFmt,
array("inote abbr `A `. `- `s `: `f -d ... aquo mac '/ '@ '; [^",
"q&a A; {|} =| {= revisions ^!! fig :: para lazyweb spaced squo links"));
To enable a selected subset of these markups, copy the above 3 lines into local/config.php before the include statement and remove the markups you don’t want. For example, the following enables just 4 extensions:
$MarkupExtensionsFmt = "para [^ :: {|}";
Under php8.1, this approach generates warning messages for undefined array keys. Instead, use the following code (based on the example above):
$MarkupExtensionsDefaultState = false;
foreach array("para", "[^", "::", "{|}") as $mkup
$MarkupExtensions[$mkup] = true;
To disable one or two markups, add one or more lines like the following before including extendmarkup.php:
$MarkupExtensions['item'] = false;
For example, $MarkupExtensions['q&a'] = false; will disable the variant of Q: and A: markup, restoring PmWiki’s default behaviour.
| Extension | Markup | Function |
|---|---|---|
| inote | (:inote PageName:) | inserts the contents of PageName formatted as a sticky note |
| abbr | n/a | prevents wikiwords with only one lower case letter, like PhD or CIOs |
| `A | Wiki`Word | another way to prevent wikiwords, like PhD |
| `. | `. | invisible stop; removed on output, tells markups such as para to “stop” |
| `- | `- | backtick-hyphen makes an en dash – (meaning “to” as in A–B) |
| `s | ` | backtick-space makes a non-breaking space ( ) |
| `: | `: | backtick-colon makes a mid-dot · |
| `f | `1/4 `1/2 `3/4 | makes a fraction ¼ ½ ¾ |
| -d | -- d-d +- -d | make em dash —, digit en dash digit, plus or minus ±, and minus digit |
| ... | ... | ellipsis … |
| aquo | <- -> <<...>> <...| |...> | left and right arrows ← → and angle quotes « … » ‹ … | and | … › |
| mac | {vowel} | macronised vowels Ā, ā, Ē, ē, etc |
| [@’/text@] | <cite>text</cite> (often rendered in italics) | |
| ‘@ | '@text@' | <kbd>text</kbd> (often rendered in monospace) |
| ‘; | ';text;' | small caps text (if the browser supports this font variant) |
| [^ | [^footnote text^] and [^#^] | swallow footnote text and list the footnotes, with links both ways |
| copy | (tm) (r) (c) | ™ ® © symbols |
| q&a | Q: and A: | render Q: and A: markups with drop-caps |
| A; | D;rop caps; markup | Drop cap followed by small caps (looks stunning in pdf) |
| {|} | {abbr|abbreviation} and {:term:definition} | <abbr title=‘…’> and <dfn title=‘…’> tags (with print equivalents) |
| =| | =←text, =|text and =→text | left, centred and right aligned text (left and right aligned omitted in print) |
| {= | {=sticky note|colour=} | a sticky note, colour (optional) is yellow, green, blue, purple, pink, grey |
| revisions | (:revisions:) | toggle between show and hide revision markups insert and |
| ^!! | !run-in head!text | run-in headings (if the browser supports this — looks stunning in pdf) |
| fig | =figure image caption | display an image and its caption |
| :: | :term:definition::more definition | multiple <dd> tags per <dt> tag (also tidy :: used for indenting) and * item::more text for paragraphs in lists |
| para | T[*#:] Name#id and (:para Name#id action:) | teaser markup and paragraph include markup (action = more, edit) |
| lazyweb | www.affinity.co.nz | lazy web links — omit the http:// |
| spaced | n/a | tidy wikiword spacing and display wikiwords like TheReturnOfTheKing as The Return of the King |
| squo | n/a | automatic smart quotes |
| links | n/a | automatic tool tips on wiki links, if the page starts with a heading or definition. Also disables links to the page you’re on, and highlights them. |
- what about markup for ↑ and ↓?
- and what about markup for ↔?
'@ @' markup added to the distribution- I often want to place unixy config files in a wiki, but long lines can really jack up the lean skin.. Peter
Usage notes
It adjusts the line height so superscripts and subscripts no longer produce uneven line spacing.
Smart quotes now deal correctly with html tags that split across a line break.
Many things from PmWiki 1 are not yet complete, but we release early and often. Treat this release as a demonstrator.
Contributor
Questions
See Discussion at MarkupExtensions-Talk.
User notes +4: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.