Using backticks-delimited code blocks in lists has apparently
become rather widely used even though the original specification
didn't seem to allow them within lists.
Make the needed changes to allow this.
The changes are actually rather minor.
And do update the syntax document to reflect this change.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Improve compatibility with some other markdown renderers and translate a
backslash (`\`) at the very end of a line (a line that is *not* inside a
table or code block) into a `<br />` in addition to the two-or-more-spaces
at the end of line translation that already takes place and does the
same thing.
As expected, the backslash can be escaped by doubling it to preserve it
(or by enclosing it in backquotes `\` to make it a code span).
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Add a note to the syntax document mentioning that when using
a line of solid hyphens (`-`s) for a horizontal rule, it will
actually be treated as an H2 Setext-style header if the preceding
line is not blank.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
To avoid conflicting (too much) with setext-style H3 headers
that are delimited with a line of tildes, require exactly three
tildes to introduce a tilde-delimited code block.
And, while in there, clean up the backticks-delimited code
blocks pattern a tiny amount and allow either kind of code block
to be closed by more than the number of opening delimiters in
addition to exactly the same number of opening delimiters.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Explain the syntax of the optional YAML front matter.
Include a few examples that demonstrate the known keys.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
When the --wiki option is active, recognize wiki-style image
links in the format:
[[link-to-image.png|align=left,alt=text]]
Where any "well-known" image suffix may be used in place of ".png"
and the "|..." part is optional but may specify any of the "width=",
"height=", "align=" or "alt=" keywords (provided alt= is always last).
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
With a minor enhancement to the support for specifying image
dimensions, images can now be "float"ed to the left or right
or even centered in their own block.
Add the ability to generate a <br clear="all" /> with 3 or
more spaces on the end of a line rather than a plain <br />
with only 2.
Document these additions as well.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Add an explanation of XML comments for those who may not be familiar
with them including a link to the relevant specification, examples,
and exacting details about where they are and are not recognized.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
A link reference may have the URL actually split onto the next line,
not just the title attribute.
Mention this in the syntax description for links.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Given a table like this:
| H1 | H2 | H3 |
|----|----|----|
| x1 | x2 | x3 |
| y1 |too long|y3|
| z1 | z2 | z3 |
The problematic second row can now be split across mulitple lines
like this:
| H1 | H2 | H3 |
|----|----|----|
| x1 | x2 | x3 |
| y1 |too | y3 |\
| |long| |
| z1 | z2 | z3 |
While the example is contrived, even with "sloppy" tables, having
the ability to merge row data like this usually avoids the need for
unsightly long lines when an exceptional cell overflows excessively.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
There's no point to including an empty header row in the output
table. It looks ugly.
While the header row is syntactically required in order to recognize
the table markup, omit it from the output if all its column cells
are empty ignoring any whitespace.
This gives a more pleasing result. Additionally add an extra class
tag "...-table-nohdr" in addition to the usual "...-table" tag to
allow easy custom formatting of these headerless tables if desired.
Empty body rows are always preserved because they can always be
omitted without breaking the table syntax.
Update the docs to describe the new behavior.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
The new `--wiki` option (with optional argument) specifies how to
transform [[wiki style links]] into URLs.
There are a veritable plethora of options available to affect
the transformation.
Absolute URL wiki style links continue to be recognized even without
the `--wiki` option.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
When determining whether or not to add the "--imageroot" or
"--htmlroot" prefix to a relative link, ignore any query string
that may be present. The fragment (if present) was already
being ignored.
Allow URLs given in reference lines to be wrapped like so:
[1]: data:image/gif;base64,R0lGODlhFwAXAPMAMf///+7u7t3d3czMzLu7u6qqqp\
mZmYiIiHd3d2ZmZlVVVURERDMzMyIiIhEREQAAACwAAAAAFwAXAAAExxDISau9Mg\
She8DURhhHWRLDB26FkSjKqxxFqlbBWOwF4fOGgsCycRkInI+ocEAQNBNWq0caCJ\
i9aSqqGwwIL4MAsRATeMMMEykYHBLIt7DNHETrAPrBihVwDAh2ansBXygaAj5sa1\
x7iTUAKomEBU53B0hGVoVMTleEg0hkCD0DJAhwAlVcQT6nLwgHR1liUQNaqgkMDT\
NWXWkSbS6lZ0eKTUIWuTSbGzlNlkS3LSYksjtPK6YJCzEwNMAgbT9nKBwg6Onq6B\
EAOw== "title (100x100)"
This facilitates embedding small amounts of data directly in
the source without causing too much difficulty.
Update the documentation to describe this new feature.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Allow links of the form [...](#...) to find themselves on the
page the same way links of the form [...] can.
Be flexible accepting either '-' or '_' in place of spaces
in the heading name since fragment names may not contain spaces.
Refactor the code that manufactures "img" and "a" tags to both
simplify the code and make sure that all href, src, alt and title
attributes are fully and properly "escaped".
In addition, if the "title" for an image ends with something that
looks like "(512x342)", "(?x342)" or "(512x?)" then strip that out
of the title and set the appropriate width and height attributes
on the manufactured "img" tag. For example something like this:
or this:
![Nice pic][1]
[1]: <pic.jpg> "Nice (500x300)"
now produces this:
<img src="pic.jpg" alt="Nice pic" width="500" height="300" title="Nice" />
Update the syntax doc to mention these additions.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Add support for basic tables.
Nested tables are not supported although tables themselves can
appear within lists and blockquotes and do work properly there.
The commonly used table syntax is recognized including the
left/right/center alignment indicators.
Inline markup within each column also works just fine.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
When using the "implicit link name" shortcut (i.e. the
link name is the same as the link text), the trailing '[]'
is unsightly.
Allow the trailing '[]' to be omitted when the omission is
unambiguous. In other words, if there is no preceding or
following pair of square brackets the trailing '[]' can safely
be omitted.
For example:
See any of [link 1][] [link 2][] [lnik 3][].
The trailing '[]' MUST NOT be omitted in this case because the
result:
See any of [link 1] [link 2] [link 3]
would be misinterpreted. But, if they're separated with commas
or words instead like so:
See any of [link 1], [link 2] or [link 3].
then they cannot be misinterpreted and the trailing '[]' can be
safely omitted making for a much nicer looking document.
To go with this change the basics.md and syntax.md documents
have been modified to take advantage of these new semantics.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
If the input is UTF-8 then lowercase greek letters may
be used for list "numbering" of <ol> lists.
If the style sheet is not included or the result is
displayed by something that does not support style
sheets they will show as lower-alpha instead.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Upper and lower case latters and roman numerals may
now be used as well as a ')' instead of a '.' to
terminate the marker.
The style sheet must be included for the ')' to
show otherwise it will display as a '.' instead.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Clean up the formatting in baiscs and syntax to make it
more readable as a text document.
This is now possible by making use of the automatic
anchors for top-level headers and '~~~~~' style h3's.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Long documents often need to link within themselves in order to
provide a convenient table of contents section.
To facilitate this, all setext-style and atx-style headers defined
at the top-level (i.e. they start at the left margin) now have
automatic anchors added to them and link definitions added for
them provided there is not already a link definition with the
same id present.
These can be easily targeted using the "implicit link name"
shortcut (e.g. [Foo][]).
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Continue to mention that Markdown expands all tabs to spaces
before doing anything else and that it guarantees to expaned
tabs withing ```-delimited code blocks to 8-character tab-stop
positions.
Otherwise always talk about "indent" levels in terms of 4
spaces per level.
There is far too much Markdown content in existence already
that assumes indenting by 4 spaces gives a new indent level.
That does not necessarily imply that all the creators of these
documents have incorrectly attempted to alter the hard-coded
terminal physical tab-stop settings from the fixed value of 8
to something else that the docs seemed to imply was 4.
Users with some other tab-stop setting were left out in the
cold by the docs. In particular, a tab-stop setting of 3 would
have rendered the examples completely useless and the text just
plain wrong.
With this change the docs no longer assume anything in particular
about the user's tab-stop settings.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Cleanup whitespace throughout the code and Markdown sources.
Fix the formatting of the POD documentation so it looks nice
when formatted as either text or html.
Tidy up the license and copyright information.
Retain '<' and '>' around "auto" links.
Avoid using tabs when producing nested <blockquote>...</blockquote>
content.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Get rid of ".text" extension.
Use standard "README" and "LICENSE" names for those.
The help files are markdown so make them have a .md extension.
Markdown.pl is kept as is (rather than changing it to markdown.pl)
because it's also a Perl module (Markdown) and Perl module names
typically start with an uppercase letter. Were it to be renamed
to a ".pm" it would end up being Markdown.pm NOT markdown.pm.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Handle ```-delimited code blocks earlier so that tabs within them
can be correctly expanded to 8-character tab stop positions and
also to avoid the result being incorrectly interpreted any further.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Update version number to 1.0.2 and tweak documentation
to eliminate outside links to documentation that is no
longer complete since the enhancements have been added.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Non-indented code blocks may be used by preceding them
with a line consisting of 3 (or more) ` characters and
following them with a line consisting of the same
number of backtick characters.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Markdown.pl (incorrectly) expands hard tabs to spaces
using a tab stops set 4 spaces apart.
While it would be nice to fix this for code blocks, it
expands the tabs to spaces before doing anything else
so it would be non-trivial to do so.
Instead explain this deviant behavior in the help
files.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
The '*' character can still be used for emphasis within
a word, but '_' will remain unchanged unless it starts
and ends a word.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Using a '~' underline will now generate an h3 header.
A preceding overline made with the same character as the underline
is now permitted.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
Kyle J. McKay