Argot 0.6

Description:

Argot 0.6

Argot is a small set of extensions on the markdown markup language designed
primarily for writing technical blog entries. The extensions are not
“proper” markdown extensions; they are implemented as preprocessors that
compile down into markdown or html syntax. In addition to markdown’s regular
syntax, which argot does not interfere with, argot provides these features:

moin-style highlighted code blocks
blockquote blocks
link target processors

You can install argot with pip:
pip install argot
You can fork argot from its hg repository:
hg clone http://bitbucket.org/jmoiron/argot/

requirements
argot requires markdown and pygments. The optional amazon link processor,
disabled by default, requires lxml.


version 0.6 notes
Version 0.6 of argot adds some functionality to the argot script, allowing
you to easily create full HTML documents (with pygments styling) from
argot markup in one easy command.
Version 0.6 of argot is backwards compatible with version 0.5, but maintains
the blockquote blocks which makes it incompatible with versions previous to
0.5. If you are using a version older than 0.5 and wish to upgrade, please
consult the README.rst file in 0.5 for a full list of incompatabilities.


moin-style highlighted code blocks
In markdown, code blocks are blocks of text one level of indentation removed
from the body text. However, when dealing with more primative browser input
mechanisms, indenting lots of text can be problematic (as tab often shifts
input focus). In addition to allowing for this convention, argot implements
moin/tracwiki style code blocks that feature syntax highlighting via pygments.

syntax
The general syntax is ‘{{{’ followed by an optional shebang and desired
pygments parser, followed by your code block, and bookended with ‘}}}’:
{{{#!parser
... code ...
}}}
By default, if no parser is provided, argot uses pygments to try and guess
what language is being used. It falls back to the plain text lexer. If you
want to force the text lexer, use a lexer of text.



blockquote blocks
Like the moin-style highlighted code blocks, blockquote blocks are primarily
intended for easy cut/paste insertion of quoted blocks into a body.

syntax
The syntax for blockquote blocks is similar to that of the code blocks, except
that parens are used instead of braces:
((("citation url"
quoted text
)))
The quoted text is converted to HTML via regular markdown syntax rules.
Nesting blockquote blocks is not supported. The optional citation url can be
surrounded in single quotes (') or double quotes (").



link target processors
Markdown links are in the style of [link text](url), but this will often
interrupt writing with digging around for urls that might be complex or even
unknown. Rather than linking to urls, argot allows you to encode the
target information in customizable ways.

syntax
Link processors are made up of the processor tag, followed by a colon,
followed by a query for that processor. For example:
[Quick reStructured Text](google: restructured text quick ref)
This calls the link processor google with the query restructured text
quick ref. By default, only the link processor google is enabled. There
is an amazon link processor that can be enabled, but it is suggested that
for stable queries you append ‘amazon’ to google queries.


setting a google referer
Google’s ajax search API (which the link processor uses) requires that you
set a referer url. If you set a google referer, Argot will fetch the first
link and use that url directly:
from argot import set_google_referer
set_google_referer('http://example.com')
By default, the google link processor will return a url to an “I’m feeling
lucky” google search page, which will then forward to the first search result.
It’s highly recommended that you cache the results of your argot rendering as
searching google for each url every time a page is loaded will be extremely
slow.


writing new link processors
Link processors are functions that take a single argument, the query as a
string, and return another string:
def wiki_processor(query):
return google_processor('wikipedia %s' % query)
argot.enable_link_processor(wiki_processor)
This hypothetical wiki processor merely does a google search for ‘wikipedia’
and the query provided. The tag for the processor can be provided in 3 ways:

the name of the function before the first underscore
a tag attribute on the function
an optional second argument to enable_link_processor




argot command line tool
Like markdown, argot ships with a command line tool that will convert
text files to html called argot. It’s usage is:
Usage: argot [options] file

Options:
--version show program's version number and exit
-h, --help show this help message and exit
-r REFERER, --referer=REFERER
http referer for google link parser
-d, --document render as full html document
-t TITLE, --title=TITLE
title to use in HEAD (implies -d)
-s STYLE, --style=STYLE
pygments style to use
With the -d option, argot will create a full HTML document with the
specified pygments style (defaults to default).