Trust the user.

If you write invalid Pretext, you'll get invalid markup. one _two three
four_._ But Pretext tries to make it obvious if you do.

It's not Pretext's job to save you from XSS attacks or other acts of
malevolence. You should run the output through a filter if use Pretext for
untrusted inputs.

What you write should look like what you typically get.

This is the rationale for /italic/, bold, _links_, and the list syntax.

Of course you can

Pretext should encourage you to write maintainable text.

The format should be as uniform as possible. (When it comes to the ordered list
syntax, this is at odds with

Pretext should be forgiving of user errors.

, without taking into account

#

Don't take HTML semantics too seriously.

The current HTML standard
mandates that you should use <i> for "an alternate voice or mood, [or] a
technical term, [or lots of things that are typically italicized]". <em>
should be used stress emphasis, which is typically italicized.

Likewise – this is my interpretation – <b> should be used for text that
isn't particularly important but you still want it to needs out, and <strong>
should be used for things that are important and therefore needs to stand out.
Both are typically set in boldface.

Pretext doesn't really care which one you mean. It generates <i> for /this/
and <b> for this by default. And it talks about making things 'bold' and
'italic' instead of 'warranting attention without being especially important'
and 'offset from normal prose because it's in an alternate voice or mood or
because of some other aspect in which it's different', because it's easier.

To use <em> or <strong>, just use them as you would in HTML.

Code blocks are also simply wrapped inside <pre> instead of <pre><code>,
like the standard suggests. This is mainly done to make the resulting HTML look
better: <pre> allows us to put a newline before the first line, so it doesn't
meddle with the content's formatting. Then again, even though Pretext calls
them 'code blocks' instead of 'preformatted text', they are basically
preformatted text and you might want to use them for different purposes than
computer code. It wouldn't be particularly semantic to wrap a printout or a
poem inside <code>, would it?

The user will encounter problems. They should be easy to solve.

There should ideally be an intuitive solution to a problem.

Example: I want to quote
Problems should be solvably first intuitive, googleable, or trying a couple of
different solution. There should be only one obvious solution to a problem.

Examples of problems:

• add a class attribute to a link
  
• use a different kind of link
  

Whenever there's a recurring problem, there should be a plugin to do it; if
there isn't, it should be relatively straightforward to write one.

There are roughly two kinds of problems:

• the user wants to do something Pretext supports, but Pretext fails to deliver.
  
• the user wants to do something Pretext doesn't support,
  

Order of priorities

1. Extensible
   
2. Simple (in this order: simple to learn, simple to use, simple to extend)
   
3. Small
   
4. Fast
   

(1), (2) and (3) go hand in hand: in order to be small, it needs to be simple;
in order to be simple, it needs to be extensible.

Each time a concept or a building block is introduced to a system, you create a
set of expectations for the user. To reduce user's mental burden, Pretext
introduces as few concepts as possible, and tries very hard not to break your
expectations.

For instance, the user expects \ to quote things where they need to be
quoted. That means quoting special characters outside

The user will encounter problems. They should be easy to solve.

Implementing plugins

Pretext processing is split into phases. Phases are functions that take some
input and produce some output.

TODO document phases

TODO move this to later; this is just a shorthand for defining plugins on a fly.
Possibly demonstrate it like this:

pretext.before('all', function(input) { do something to input });

and then congratulate the reader of having written his first Pretext plugin.

If you need to do your processing before some other phase:

pretext.before(<phase>, function(input) { return output; });

If you need to do your processing after some other phase:

pretext.after(<phase>, function(input) { return output; });

To replace a phase:

pretext.replace(<phase>, function(input) { return output; });

To remove a phase:

pretext.remove(<phase>);

Inside phase functions, you can invoke other phases with:

output = this.<phase>(content)

this is the pretext object.

By default, Pretext attempts to inject your plugin immediately after or before a
phase. In the case of multiple plugins, the last to come will win.

Plugins will themselves become phases once they are installed.

(Eventually there may be multiple constraints between different plugins and some
dependency analysis to determine a suitable order.)

You can use pretext directly. In that case, it comes with the default settings:

var pretext = require('pretext');
console.log(pretext('# Hello'));

You can use install to install plugins. Using a newly created instance is
recommended (but not enforced):

var Pretext = require('pretext').Pretext;
var pretext = new Pretext();
pretext.install('uglify');
pretext.install('sanitize');
pretext.install(require('pretext-newlines'));

Or, more succinctly:

var Pretext = require('pretext').Pretext;
var pretext = new Pretext('uglify', 'sanitize', require('pretext-newlines'));

A plugin is either a string (in which case it's looked up in the internal
plugins, of which there will be a few), or a function with an optional member
(one of after, before or replace) that tells the phase where it should be
plugged in.

The pretext-newlines plugin, for example, is defined as:

function newlines(text) {
    return text.replace('\n', '<br>');
}
// Or whatever 
newlines.after = 'filter';
module.exports = newlines;

TODO some plugins may want to install multiple phases in different places. What
then?

TODO some plugins may want to access a data object that collects data during the
processing. Or is that actually necessary? We could also do things like a
plugin that collects a list of figures from the text:

var figures = [];
pretext.after('filter', function collect(text) { // collect figures in figures });
pretext.after('all', function summarize(text) { // append list of figures at the end }); 

Ideally, the data would live as a variable inside the second phase, but it needs
to be readable by the first phase. Perhaps allow this: