Add Plan9 support (from Josh Wood @ utopian.net)

This commit is contained in:
David Parsons
2009-06-14 10:28:09 -07:00
parent fd212c1c30
commit 027e728b6d
4 changed files with 715 additions and 0 deletions
+43
View File
@@ -0,0 +1,43 @@
% Discount on Plan 9
% Josh Wood
% 2009-06-12
# *Discount* Markdown compiler on Plan 9
## Build
% mk 'CONFIG=--enable-all-features' config
% mk install
% markdown -V
markdown: discount X.Y.Z DL_TAG HEADER DEBUG SUPERSCRIPT RELAXED DIV
`--enable-all-features` may be replaced by zero or more of:
--enable-dl-tag Use the DL tag extension
--enable-pandoc-header Use pandoc-style header blocks
--enable-superscript A^B becomes A<sup>B</sup>
--enable-amalloc Enable memory allocation debugging
--relaxed-emphasis underscores aren't special in the middle of words
--with-tabstops=N Set tabstops to N characters (default is 4)
--enable-div Enable >%id% divisions
--enable-alpha-list Enable (a)/(b)/(c) lists
--enable-all-features Turn on all stable optional features
## Notes
The supplied mkfile merely drives Discount's own configure script and
then APE's *psh* environment to build the Discount source, then copies
the result(s) to locations appropriate for system-wide use on Plan 9. There are
a few other *mk*(1) targets:
`install.libs`: Discount includes a C library and header.
Installation is optional. Plan 9 binaries are statically linked.
`install.man`: Add manual pages for markdown(1) and (6).
`install.progs`: Extra programs. *makepage* writes complete
XHTML documents, rather than fragments. *mkd2html* is similar, but
produces HTML.
`test`: Most of Parson's *Discount* test suite succeeds, but
some programs are missing, like *fgrep*(1) and *cut*(1).
+142
View File
@@ -0,0 +1,142 @@
.TH MARKDOWN 1
.SH NAME
markdown \- convert Markdown text to HTML
.SH SYNOPSIS
.B markdown
[
.B -dTV
]
[
.BI -F " bitmap
]
[
.BI -f " flags
]
[
.BI -o " ofile
]
[
.BI -s " text
]
[
.BI -t " text
]
[
.I file
]
.SH DESCRIPTION
The
.I markdown
utility reads the
.IR Markdown (6)-formatted
.I file
(or standard input) and writes its
.SM HTML
fragment representation on standard output.
.PP
The options are:
.TF dfdoptions
.TP
.B -d
Instead of writing the
.SM HTML
file, dump a parse tree to stdout.
.TP
.BI -F " bitmap
Set translation flags.
.I Bitmap
is a bit map of the various configuration options described in
.IR markdown(2)
(the flag values are defined in mkdio.h)
.TP
.BI -f " flags
Set or clear various translation flags, described below. The flags are in a comma-delimited list, with an optional
.B +
(set) prefix on each flag.
.TP
.BI -o " ofile
Write the generated
.SM HTML
to
.IR ofile .
.TP
.BI -s " text
Use the
.IR markdown (2)
function to format the
.I text
on standard input (the default behavior).
.TP
.B -T
If run with the table-of-contents flag on, dump the table of contents before the formatted text.
.TP
.BI -t " text
Use
.IR mkd_text (2)
to format text instead of processing standard input with
.IR markdown (3).
.TP
.B -V
Show version number and configuration. If the version includes the string
.BR DL_TAG ,
.I markdown
was configured with definition list support. If the version includes the string
.BR HEADER ,
.I markdown
was configured to support pandoc header blocks.
.PP
.SS TRANSLATION FLAGS
The translation flags understood by
.B -f
are:
.TF \ noheader
.TP
.B noimage
Don't allow image tags.
.TP
.B nolinks
Don't allow links.
.TP
.B nohtml
Don't allow any embedded HTML.
.TP
.B cdata
Generate valid XML output.
.TP
.B noheader
Do not process pandoc headers.
.TP
.B tabstops
Use Markdown-standard 4-space tabstops.
.TP
.B strict
Disable superscript and relaxed emphasis.
.TP
.B relax
Enable superscript and relaxed emphasis (the default).
.TP
.B toc
Enable table of contents support.
.TP
.B 1.0
Revert to Markdown 1.0 compatability.
.PD
.PP
For example, the option
.B -f nolinks,quot
tells
.I markdown
not to allow
.B <a
tags, and to expand double quotes.
.SH SOURCE
.B /sys/src/cmd/discount
.SH SEE ALSO
.IR markdown (3),
.IR markdown (6)
.PP
http://daringfireball.net/projects/markdown/,
``Markdown''.
.SH DIAGNOSTICS
.I Markdown
exits 0 on success and >0 if an error occurs.
+494
View File
@@ -0,0 +1,494 @@
.TH MARKDOWN 6
.SH NAME
Markdown \- text formatting syntax
.SH DESCRIPTION
Markdown
is a text markup syntax for machine conversion to
the more complex
.SM HTML
or
.SM XHTML
markup languages.
It is intended to be easy to read and to write, with
emphasis on readability.
A Markdown-formatted document should be publishable as-is,
in plain text, without the formatting distracting the reader.
.PP
The biggest source of inspiration for Markdown's
syntax is the format of plain text email. The markup is comprised entirely
of punctuation characters, chosen so as to look like what they mean.
Asterisks around a word look like
.IR *emphasis* .
Markdown lists look like lists. Even
blockquotes look like quoted passages of text, assuming the reader has
used email.
.PP
.SS Block Elements
.TF W
.PD
.TP
Paragraphs and Line Breaks
A paragraph is one or more consecutive lines of text, separated
by one or more blank lines. (A blank line is any line that looks like a
blank line -- a line containing nothing but spaces or tabs is considered
blank.) Normal paragraphs should not be indented with spaces or tabs.
.IP
Lines may be freely broken for readability; Markdown
does not translate source line breaks to
.B <br />
tags. To request generation of
.B <br />
in the output, end a line with two or more spaces, then a newline.
.TP
Headers
Markdown defines two header styles,
.I Setext
and
.IR atx .
.IP
Setext-style headers are
``underlined'' using equal signs (for first-level
headers) and dashes (for second-level headers).
.IP
Atx-style headers use 1-6 hash characters at the start of the line,
corresponding to
.SM HTML
.BR <h^(1-6)^> .
Optional closing hashes may follow
the header text.
.TP
Blockquotes
Lines beginning with
.B >
are output in blockquotes.
Blockquotes can be nested
by multiple levels of
.BR >> .
Blockquotes can contain other Markdown elements, including
headers, lists, and code blocks.
.TP
Lists
Markdown supports ordered (numbered) and unordered (bulleted) lists.
List markers typically start at the left margin, but may be indented by
up to three spaces.
List markers must be followed by one or more spaces
or a tab, then the list item text.
A newline terminates each list item.
.IP
Unordered lists use asterisks, pluses, and hyphens interchangeably as
list markers.
.IP
Ordered lists use integers followed by periods as list markers.
The order of the integers is not interpreted,
but the list should begin with
.BR 1 .
.IP
If list items are separated by blank lines, Markdown will wrap each list
item in
.B <p>
tags in the
.SM HTML
output.
.IP
List items may consist of multiple paragraphs.
Each subsequent
paragraph within a list item must be indented by either 4 spaces
or one tab.
To put a blockquote within a list item, the blockquote's
.B >
marker needs to be indented.
To put a code block within a list item, the code block needs
to be indented
.I twice
-- 8 spaces or two tabs.
.TP
Code Blocks
To produce a code block, indent every line of the
block by at least 4 spaces or 1 tab.
A code block continues until it reaches a line that is not indented.
.IP
Rather than forming normal paragraphs, the lines
of a code block are interpreted literally.
Regular Markdown syntax is not processed within code blocks.
Markdown wraps a code block in both
.B <pre>
and
.B <code>
tags.
One level of indentation -- 4
spaces or 1 tab -- is removed from each line of the code block in
the output.
.TP
Horizontal Rules
Produce a horizontal rule tag (
.B <hr />
) by placing three or
more hyphens, asterisks, or underscores on a line by themselves.
.SS Span Elements
.TF W
.PD
.TP
Links
Markdown supports two styles of links:
.I inline
and
.IR reference .
In both styles, the link text is delimited by square brackets (
.B []
).
To create an inline link, use a set of regular parentheses immediately
after the link text's closing square bracket.
Inside the parentheses,
put the link URL, along with an optional
title for the link surrounded in double quotes.
For example:
.IP
.EX
An [example](http://example.com/ "Title") inline link.
.EE
.IP
Reference-style links use a second set of square brackets, inside
which you place a label of your choosing to identify the link:
.IP
.EX
An [example][id] reference-style link.
.EE
.IP
The label is then assigned a value on its own line, anywhere in the document:
.IP
.EX
[id]: http://example.com/ "Optional Title"
.EE
.IP
Link label names may consist of letters, numbers, spaces, and
punctuation.
Labels are not case sensitive.
An empty label bracket
set after a reference-style link implies the link label is equivalent to
the link text.
A URL value can then be assigned to the link by referencing
the link text as the label name.
.TP
Emphasis
Markdown treats asterisks (
.B *
) and underscores (
.B _
) as indicators of emphasis.
Text surrounded with single asterisks or underscores
will be wrapped with an
.SM HTML
.B <em>
tag.
Double asterisks or underscores generate an
.SM HTML
.B <strong>
tag.
.TP
Code
To indicate a span of code, wrap it with backtick quotes (
.B `
).
Unlike a code block, a code span indicates code within a
normal paragraph.
To include a literal backtick character within a code span, you can use
multiple backticks as the opening and closing delimiters:
.IP
.EX
``There is a literal backtick (`) here.``
.EE
.TP
Images
Markdown image syntax is intended to resemble that
for links, allowing for two styles, once again
.I inline
and
.IR reference .
The syntax is as for each respective style of link, described above, but
prefixed with an exclamation mark character (
.B !
).
Inline image syntax looks like this:
.IP
.EX
![Alt text](/path/to/img.jpg "Optional title")
.EE
.IP
That is:
An exclamation mark;
followed by a set of square brackets containing the `alt'
attribute text for the image;
followed by a set of parentheses containing the URL or path to
the image, and an optional `title' attribute enclosed in double
or single quotes.
.IP
Reference-style image syntax looks like this:
.IP
.EX
![Alt text][id]
.EE
.IP
Where
.I id
is a label used as for reference-style URL links, described above.
.SS Convenience
.TF W
.PD
.TP
Automatic Links
There is a shortcut style for creating ``automatic''
links for URLs and email addresses.
Surround the URL
or address with angle brackets.
.TP
Backslash Escapes
Use backslash escapes to generate literal
characters which would otherwise have special meaning in Markdown's
formatting syntax.
.TP
Inline HTML
For markup that is not covered by Markdown's
syntax, simply use the
.SM HTML
directly.
The only restrictions are that block-level
.SM HTML
elements --
.BR <div> ,
.BR <table> ,
.BR <pre> ,
.BR <p> ,
etc. -- must be separated from surrounding
content by blank lines, and the start and end tags of the block should
not be indented with tabs or spaces. Markdown formatting syntax is
not processed within block-level
.SM HTML
tags.
.IP
Span-level
.SM HTML
tags -- e.g.
.BR <span> ,
.BR <cite> ,
or
.B <del>
-- can be
used anywhere in a Markdown
paragraph, list item, or header.
It is permitted to use
.SM HTML
tags instead of Markdown formatting; e.g.
.SM HTML
.B <a>
or
.B <img>
tags instead of Markdown's
link or image syntax.
Unlike block-level
.SM HTML
tags, Markdown
syntax
.I is
processed within the elements of span-level tags.
.TP
Automatic Special Character Escapes
To be displayed literally in a user agent, the characters
.B <
and
.B &
must appear as escaped entities in
.SM HTML
source, e.g.
.B &lt;
and
.BR &amp; .
Markdown
allows natural use of these characters, taking care of
the necessary escaping.
The ampersand part of a directly-used
.SM HTML
entity remains unchanged; otherwise it will be translated
into
.BR &amp; .
Inside code spans and blocks, angle brackets and
ampersands are always encoded automatically.
This makes it easy to use Markdown to write about
.SM HTML
code.
.PP
.SS Smarty Pants
The
.IR markdown (1)
utility transforms a few plain text symbols into their typographically-fancier
.SM HTML
entity equivalents.
These are extensions to the standard Markdown syntax.
.TF W
.PD
.TP
Punctuation
Input single- and double-quotes are transformed
into ``curly'' quote entities in the output (e.g.,
.B 'text'
becomes
.BR &lsquo;text&rsquo; ).
Input double-dashes (
.B --
) and triple-dashes become en- and em-dashes, respectively,
while a series of three dots (
.B ...
) in the input becomes an ellipsis entity (
.B &hellip;
) in the
.SM HTML
output.
.TP
Symbols
Three other transformations replace the common plain-text shorthands
.BR (c) ,
.BR (r) ,
and
.BR (tm)
from the input with their respective
.SM HTML
entities. (As in
.B (c)
becoming
.BR &copy; ,
the Copyright symbol entity.)
.TP
Fractions
A small set of plain-text shorthands for fractions is recognized.
.B 1/4
becomes
.BR &frac14; ,
for example. These fraction notations are replaced with their
.SM HTML
entity equivalents:
.BR 1/4 ,
.BR 1/2 ,
.BR 3/4 .
.B 1/4th
and
.B 3/4ths
are replaced with their entity and the indicated ordinal suffix letters.
.PP
Like the basic Markdown syntax, none of the ``Smarty Pants'' extensions are processed
inside code blocks or spans.
.PP
.SS Discount Extensions
This
.IR markdown (1)
recognizes a few of its own extensions to the
.IR Markdown (6)
format.
.TF W
.PD
.TP
Image dimensions
Markdown embedded images have been extended to allow specifying the dimensions of the image by adding a new argument =/height/x/width/ to the link description. The new syntax is:
.IP
.EX
![Alt text](/path/to/image.jpg =/height/x/width/ "Title")
.EE
.TP
Pseudo-protocols
Three pseudo-protocols have been added to links:
.IP
.BR id :
The alt text is marked up and written to the output, wrapped with
.B <a id=id>
and
.BR </a> .
.IP
.BR class :
The alt text is marked up and written to the output, wrapped with
.B <span class=class>
and
.BR </span> .
.IP
.BR raw :
The title is written -- with no further processing -- to the output. The alt text is discarded.
.TP
Pandoc headers
If
.I markdown
was configured with
.BR --enable-pandoc-header ,
the markdown source can have a 3-line Pandoc header in the format of
.IP
.EX
% Title
% Author
% Date
.EE
.IP
which will be made available to the
.IR mkd_doc_title ,
.IR mkd_doc_author ,
and
.I mkd_doc_date
functions.
.TP
Definition lists
If configured with
.BR --enable-dl-tag ,
markup for definition lists is enabled. A definition list item is defined as
.IP
.EX
=term=
definition
.EE
.TP
Embedded stylesheets
Stylesheets may be defined and modified in a
.B <style>
block. A style block is parsed like any other block-level
.SM HTML;
.B <style>
starting on column 1, raw
.SM HTML
(or, in this case,
.SM CSS \)
following it, and either ending with a
.B </style>
at the end of the line or at the beginning of a subsequent line.
.IP
Be warned that style blocks work like footnote links: no matter where you define them, they are valid for the entire document.
.TP
Relaxed emphasis
If
.I markdown
was configured with
.BR --relaxed-emphasis ,
the rules for emphasis are changed so that a single
.B _
will not count as an emphasis character if it's in the middle of a word.
This is primarily for documenting code, if you don't with to have to backquote all code regerences.
.TP
Alpha lists
If configured with
.BR --enable-alpha-list ,
alphabetic lists are supported.
So:
.IP
.EX
a. this
b. is
c. an alphabetic
d. list
.EE
.IP
will produce an
.SM HTML
.B ol
ordered list.
.PD
.SH SEE ALSO
.IR markdown (1)
.PP
http://daringfireball.net/projects/markdown/syntax/,
``Markdown: Syntax''.
.PP
http://daringfireball.net/projects/smartypants/,
``Smarty Pants''.
+36
View File
@@ -0,0 +1,36 @@
BIN=/$objtype/bin
CC='cc -D_BSD_EXTENSION'
markdown:
ape/psh -c 'cd .. && make'
none:V: markdown
test: markdown
ape/psh -c 'cd ..&& make test'
install: markdown
cp ../markdown $BIN/markdown
install.progs: install
cp ../makepage $BIN/makepage
cp ../mkd2html $BIN/mkd2html
install.libs: install
cp ../mkdio.h /sys/include/ape/mkdio.h
cp ../libmarkdown.a /$objtype/lib/ape/libmarkdown.a
install.man: install
cp markdown.1 /sys/man/1/markdown
cp markdown.6 /sys/man/6/markdown
installall:V: install.libs install.man install.progs
config:
ape/psh -c 'cd .. && ./configure.sh $CONFIG'
clean:
ape/psh -c 'cd .. && make clean'
nuke:
ape/psh -c 'cd .. && make distclean'