Readme: Markdown version with syntax highlighting, converter

README.md

@@ -0,0 +1,163 @@
+<!--
+!! auto-generated from .pod by `pod2md.sed`
+!! -->
+
+
+<a name="jscreole" id="jscreole"></a>
+jscreole - Parse Creole into DOM
+================================
+```js
+var creole = new creole({
+    interwiki: {
+        MeatballWiki: 'http://www.usemod.com/cgi-bin/mb.pl?',
+        TiddlyWiki: 'http://www.tiddlywiki.com/#',
+        WikiCreole: 'http://www.wikicreole.org/wiki/',
+        Palindrome: function(link) {
+                return 'http://www.example.com/wiki/' + link.split('').reverse().join('');
+            }
+    },
+    linkFormat: '#'
+});
+
+var div = document.createElement('div');
+creole.parse(div, "* This is [[Wikipedia:Wikitext|wikitext]]");
+```
+
+This module implements Creole 1.0 parser, as defined by
+http://www.wikicreole.org/wiki/Creole1.0 .
+
+
+<a name="options" id="options"></a>
+Options
+-------
+
+* <a name="defaultimagetext" id="defaultimagetext"></a>`defaultImageText`: Alternative text for an image with no alternative text
+  ```text
+  {{image.png}}
+  ```
+
+  as opposed to empty alternative text
+  ```text
+  {{image.png|}}
+  ```
+
+  Note that strict Creole 1.0 doesn't allow images with no alternative text.
+
+* <a name="interwiki" id="interwiki"></a>`interwiki`: Interwiki map. Object properties' values are strings, arrays of one or two
+  strings, or functions. The first string is a leading part
+  of the URL. If the second string is given as well, it is a
+  trailing part. If the value is a function, which takes a link identifier as an
+  argument, its return value is the whole URL.
+
+* <a name="linkformat" id="linkformat"></a>`linkFormat`: Internal links' format. Same format as in ["interwiki"](#interwiki)'s properties.
+
+* <a name="strict" id="strict"></a>`strict`: Whether the parser is strict Creole 1.0. For constructor only, i. e.
+  non-overridable in `parse` method. A non-strict parser allows images in tables
+  and images with no alternative text.
+
+<a name="creole" id="creole"></a>
+creole._base - Parse text into DOM
+==================================
+```js
+// Define grammar
+var g = {
+    para: { _tag: 'p',
+        _regex: /([ \t]*\S.+((\r?\n|\r)[ \t]*\S.*)*)/, _capture: 0 }
+};
+g._root = { _children: [ g.para ] };
+
+// Create parser
+var parser = new creole._base(g);
+
+// Parse
+var div = document.createElement('div');
+parser.parse(div, 'para\n' +
+                  ' continues\n\n' +
+                  'another para\n \n' +
+                  'yet another para');
+```
+
+This module implements a simple recursive descent parser using regular
+expressions for lexical analysis. The result is stored into a DOM object,
+that can be then put in a document or traversed using standard DOM API.
+
+
+<a name="parser" id="parser"></a>
+Parser
+------
+
+* `new creole._base(grammar, options)`:
+
+  The constructor creates a new parser object given a grammar and options.
+  The grammar is an object of any type, which must contain a root property,
+  that also must be an object of any type. The root is cast to a
+  type specified by `this._ruleConstructor`, being `creole._rule`
+  by default. See ["Rules"](#rules) for more info on defining rule objects.
+
+  Options are optional but if passed it must be an object. The only option
+  available in `creole._base` is `forIE`, which should be set `true` for
+  Microsoft Internet Explorer compatibility. Derived objects and subinterfaces
+  may extend the `options` object with their own options.
+
+* `parse(node, data, options)`:
+
+  This method parses flat text data and creates a DOM tree inside a given node,
+  which should be a Node object. If options are passed, they override those
+  passed to the constructor. Options merge at the first depth, merging
+  nested options is not supported.
+
+<a name="rules" id="rules"></a>
+Rules
+-----
+
+* `_regex`: A regular expression to match the input.
+
+* `_capture`: What should be captured for the output data: 0 for the whole matched substring,
+  1 and so on for corresponding capturing brackets. If not listed, data will be
+  empty.
+
+* `_replaceRegex`, `_replaceString`: If set, captured data will be processed before output.
+
+* `_tag`: If set, captured data will be enclosed inside a new child element, otherwise
+  they will be put in the current node.
+
+* `_attrs`: If set to an object, a new child element will have the given attributes.
+
+* `_children`: An array of grammar rules, which define possible child nodes.
+
+* `_fallback`: If there are chunks which don't match any child rule, they are being
+  processed with this one.
+
+<a name="author" id="author"></a>
+Author
+======
+
+Ivan Fomichev <[[email protected]](mailto:[email protected])>
+
+
+<a name="copyright" id="copyright"></a>
+Copyright
+=========
+```text
+Copyright (c) 2008 Ivan Fomichev
+
+Portions Copyright (c) 2007 Chris Purcell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```

util/npm-pkg/.gitignore

@@ -0,0 +1,2 @@
+
+/Pod/Markdown.pm

util/npm-pkg/perl-podmd-optim.sed

@@ -0,0 +1,52 @@
+#!/bin/sed -nrf
+# -*- coding: UTF-8, tab-width: 2 -*-
+
+: read_all
+  $!{N;b read_all}
+: normalize_input
+  s~[ \t]+(\n|$)~\1~g
+  s~^\s*~<!--\n!! auto-generated from .pod !!\n!! -->\n\n\n~
+
+: identify_blocks
+  s~\n# NAME\n+([^\f\n]+\n)~\n\n\1\f<underline>=\1~g
+  s~\n# (DESCRIPTION|SYNOPSIS)\n+~\n~g
+  # s~\n((\n+ {4}[^\f\n]+)+)~\f<code>\1\f</code>~g
+
+: simple_transforms
+  s~\f<titlecase-word>([A-Z])([A-Z]+)~\1\L\2\E~g
+
+: code_block_init
+  s~(\f<code>)(\n*)~\2```\n\1~g
+  s~(```)(\n\f<code>[^\f]*\n *var [a-z]+ = )~\1js\2~g
+  s~(```)(\n\f<code>)~\1text\2~g
+  s~(\n*)(\f</code>)~\n\2```\1~g
+: code_block_again
+  s~(\f<code>)(\n+)~\2\1~g
+  s~(\f<code>) {4}([^\f\n]+)~\2\1~g
+  s~(\f<code>)(\f</code>)~~g
+t code_block_again
+
+: underline
+  #s~(^|\n)([^\n]+\n) *(\f<underline>)~\n\f<hl>\2\2\3~g
+  #s~\f<hl>([A-Za-z-]+)\b[^\n]*~<a name="\L\1\E" id="\L\1\E"></a>~g
+  s~(\f<underline>)(\S)[^\f\n]~\2\1\2~g
+  s~(\f<underline>)(\S)(\n|$)~\3~g
+t underline
+
+: list_optim
+  s~(\n *\- )((new |[A-Za-z]+\.)*([a-z\\_]+[A-Z]?)+(|\
+    | *\([^\n]*\)))\n~\1`\2`\n~g
+
+
+
+: normalize_output
+  s~^\s+~~
+  s~\s*$~\n~
+  s~\n+=cut\n+$~~
+  p
+b eof
+
+
+
+
+: eof

util/npm-pkg/pod2md.sed

@@ -0,0 +1,79 @@
+#!/bin/sed -rf
+# -*- coding: UTF-8, tab-width: 2 -*-
+
+: read_all
+  $!{N;b read_all}
+: normalize_input
+  s~[ \t]+(\n|$)~\1~g
+
+: identify_blocks
+  s~(^|\n)=head1 NAME\n+([^\f\n]+\n)~\n\n\1\2\f<underline>=\2~g
+  s~\n=head[1-9] (DESCRIPTION|SYNOPSIS)\n+~\n~g
+  s~\n=head1 (AUTHOR|COPYRIGHT)\n~\n\n\f<titlecase-word>\1\
+    \f<underline>=\1\n~g
+  s~\n=head2 ([A-Z][a-z]+)\n+~\n\n\1\n\f<underline>-\1\n\n~g
+  s~\n((\n+  [^\f\n]+)+)~\f<code>\1\f</code>~g
+
+: simple_transforms
+  s~\f<titlecase-word>([A-Z])([A-Z]+)~\1\L\2\E~g
+  s~\bC<([^<>]+)>~`\1`~g
+
+: code_block_init
+  s~(\f<code>)(\n*)~\2```\n\1~g
+  s~(```)(\n\f<code>[^\f]*\n *var [a-z]+ = )~\1js\2~g
+  s~(```)(\n\f<code>)~\1text\2~g
+  s~(\n*)(\f</code>)~\n\2```\1~g
+: code_block_again
+  s~(\f<code>)(\n+)~\2\1~g
+  s~(\f<code>) {2}([^\f\n]+)~\2\1~g
+  s~(\f<code>)(\f</code>)~~g
+t code_block_again
+
+: underline
+  s~(^|\n)([^\n]+\n) *(\f<underline>)~\n\f<hl>\2\2\3~g
+  s~\f<hl>([A-Za-z-]+)\b[^\n]*~<a name="\L\1\E" id="\L\1\E"></a>~g
+  s~(\f<underline>)(\S)[^\f\n]~\2\1\2~g
+  s~(\f<underline>)(\S)(\n|$)~\3~g
+t underline
+
+: list_init
+  s~\n=over\n~\n\f<ul>~g
+  s~\n=item ([^\f\n]+)\n~\f</li>\n* \1:\n\f<li>~g
+  s~\n=item(\n+)~\n* \f<li>~g
+  s~\n=back\n~\n\f</ul>~g
+: list_indent
+  s~(\f<li>)([^\f\n]*)(\n+)~  \2\3\1~g
+t list_indent
+: list_clean_indent
+  s~ +\n~\n~g
+  s~\n+\f<(li|ul)>\f</(li|ul)>\n+~\n\n~g
+: list_mark_identifiers
+  s~(\n *\* )((new |[A-Za-z]+\.)*([a-z_]+[A-Z]?)+(|\
+    | *\([^\n]*\))):\n~\1`\2`:\n~g
+: list_merge_word_defs
+  s~(\n *\* [`A-Za-z_-, ]+):\n+ *\* ([`A-Za-z_-]+:\n)~\1, \2~g
+  s~(\n *\* [`A-Za-z_-, ]+:)\n+ {2}([A-Z])~\1 \2~g
+t list_merge_word_defs
+
+: links
+  s~(\n *\* )(`([A-Za-z-]+)`)(\n|:)~\1<a name="\L\3\E" id="\L\3\E"></a>\2\4~g
+  s~(\b|<)F<([^\f\n <>]+@[^\f\n <>]+)>(>|)~\1[\2](mailto:\2)\3~g
+  s~\bL<("?([A-Za-z-]+)"?)>~[\1](#\L\2\E)~g
+  s~\bL<([a-z]{2,8}://[^\f\n <>]+)>~\f<a> \1 \f</a>~g
+  s~(^|\n|<| )\f<a> ~\1~g
+  s~ \f</a>( |>|\n|$)~\1~g
+  s~\f</?a>~~g
+
+
+: normalize_output
+  s~^\s+~~
+  s~\s*$~\n~
+  s~\n+=cut\n+$~~
+  s~^~<!--\n!! auto-generated from .pod by `pod2md.sed`\n!! -->\n\n\n~
+  p
+b eof
+
+
+
+
+: eof

util/npm-pkg/upd-meta.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# -*- coding: utf-8, tab-width: 2 -*-
+SELFPATH="$(readlink -m "$0"/..)"
+
+
+function upd_npm_pkg_meta () {
+  cd "$SELFPATH" || return $?
+
+  local PODMD_MOD=
+  # PODMD_MOD='Pod::Markdown'
+  # ^-- tested 2015-06-21: yielded quite some ugly Markdown, and no easy
+  #     way to tell code block indentation apart from list indentation.
+  [ -z "$PODMD_MOD" ] || perl_podmd_test 2>/dev/null \
+    || perl_podmd_download || return $?
+
+  local SRC_FN=
+  for SRC_FN in ../../*.pod; do
+    pod2markdown "$SRC_FN" || return $?
+  done
+
+  return 0
+}
+
+
+function perl_podmd_test () {
+  perl -M"$PODMD_MOD" -e ''; return $?
+}
+
+
+function perl_podmd_download () {
+  echo "W: Perl module $PODMD_MOD seems to not be installed." \
+    "Will try to download it:" >&2
+  local CPAN_DL_BASE='https://api.metacpan.org/source/'
+  local PODMD_CPAN_DL='RWSTAUNER/Pod-Markdown-2.002/lib/Pod/Markdown.pm'
+  local SAVE_FN="${PODMD_MOD//:://}".pm
+  mkdir -p "${SAVE_FN%/*.pm}" || return $?
+  wget -O "$SAVE_FN" -c "${CPAN_DL_BASE}${PODMD_CPAN_DL}" || return $?$(
+    echo "E: Unable to download perl module $PODMD_MOD" >&2)
+  perl_podmd_test; return $?
+}
+
+
+function perl_podmd_convert () {
+  perl -M"$PODMD_MOD" -e "$PODMD_MOD"'->new->filter(@ARGV)' "$@"; return $?
+}
+
+
+function pod2markdown () {
+  local SRC_FN="$1"; shift
+  local DEST_FN="$1"; shift
+  [ -n "$DEST_FN" ] || DEST_FN="${SRC_FN%.pod}.md"
+
+  if [ -z "$PODMD_MOD" ]; then
+    sed -nrf "$SELFPATH/pod2md.sed" "$SRC_FN" >"$DEST_FN" || return $?
+    return 0
+  fi
+
+  perl_podmd_convert "$SRC_FN" >"$DEST_FN" || return $?
+  sed -nrf perl-podmd-optim.sed -i "$DEST_FN" || return $?
+  return 0
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+upd_npm_pkg_meta "$@"; exit $?