MarkupExtensions

Summary: Adds a range of character, start of line, and link markup extensions
Version: 2.1.1 (2014–02–13, compatible with php 5.5, requires php 5.3 or above)
Status: Stable
Prerequisites: pmwiki 2.2.56 and above (older versions need the older recipe version)
Maintainer: jr
Categories: Markup PHP55 PHP72 PHP81
Users: +4 (view / edit)

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:

  1. improve the look and readability of pages by displaying em or en dashes, smart quotes, arrows, fractions, ™ and the like
  2. improve the structure of pages using footnotes, teaser paragraphs, sticky notes, run-in headings and the like
  3. 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).

markup-20181207.phpΔ is 2.1.1 without deprecated Markup_e() function calls (tested on pmwiki-2.2.110).
markup-2023-02-09.phpΔ is 2.1.1, without Markup_e() calls, and PHP81 compatible. HansB

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 :

Optional:
$MarkupCss = true;

followed by:

Required:
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”?
Well, I propose renaming the script to “markup” — so one would refer to the “local markup.php script”.

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.

ExtensionMarkupFunction
inote(:inote PageName:)inserts the contents of PageName formatted as a sticky note
abbrn/aprevents wikiwords with only one lower case letter, like PhD or CIOs
`AWiki`Wordanother 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 (&nbsp;)
`:`:backtick-colon makes a mid-dot ·
`f`1/4 `1/2 `3/4makes a fraction ¼ ½ ¾
-d-- d-d +- -dmake 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&aQ: and A:render Q: and A: markups with drop-caps
A;D;rop caps; markupDrop 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 =→textleft, 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 delete
^!!!run-in head!textrun-in headings (if the browser supports this — looks stunning in pdf)
fig=figure image captiondisplay an image and its caption
:::term:definition::more definitionmultiple <dd> tags per <dt> tag (also tidy :: used for indenting) and * item::more text for paragraphs in lists
paraT[*#:] Name#id and (:para Name#id action:)teaser markup and paragraph include markup (action = more, edit)
lazywebwww.affinity.co.nzlazy web links — omit the http://
spacedn/atidy wikiword spacing and display wikiwords like TheReturnOfTheKing as The Return of the King
squon/aautomatic smart quotes
linksn/aautomatic 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 ↔?
I’m willing to add some of these to the distribution, if desired.
I’d love to see the '@ @' 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

jr

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.