Simple text markup (-> HTML)

[Jacek Generowicz]

:::Title::: A simple text markup utility :::/Title:::

:::Section Introduction :::

I'm looking for something to help developers wirte documentation for
bits of software they are writing. The main (initially only)
presentation format will be HTML. The idea is to allow the author to
write a plain text file containing the text he wishes to present,
annotated with minimally intrusive markup which describes the
:::emph::: meaning :::/emph::: of parts of the text. The author should
not concern himself with how the output will look; he should trust the
rendering process to Do The Right Thing.

For example, the author might want to communicate that some portion of
text represents source code, or commands to be issued, or output given
by a program.

:::Example:::

A recursive implementation of the Fibonacci function might look like this

:::Source:::
def fib(n):
    if n<2: return 1
    return fib(n-1) + fib(n-2)
:::/Source:::

And it works like this

:::Input::: fib(8) :::/Input:::
:::Output::: 34 :::/Output:::

:::/Example::: :::/Section:::


:::Section Why not XML ? :::

The idea is that the utility should be minimally intrusive to the
author. Given that the author is likely to want to paste source code,
having to substitite all occurances of "<" with &lt and so on is
completely unacceptable.

As you can see, I have been using triple colons in this presentation
as a sufficiently unlikely character combination, to replace XML's "<"
and ">". Clearly this is not ideal. Maybe allowing the author to
specify how the markup should be identified is a solution ... for
example an instruction such as :::SetMarkup ||::: could be used to
change the markup identification sequence to two vertical bars (taking
effect only in "leafward" parts of the parse tree.
||/Section||


||Section Why not LaTeX ? ||

Yes, LaTeX pretty much reifies the idea I am trying to express, and I
could use something in the LateX2HTML genre as a
backend. Unfortunately LaTeX it not politically acceptable in my
environment.

(If the markup is sufficiently simple, then something based on s-exprs
could pass through the political correctness filters ... as long as
implemented in C(++) or Python.)

||Section Automation||

Ideally, I'd like to be able to execute arbitrary Python code within
the document source, in order to "suck in" information from elsewhere.

||Source||
||Macro||
for line in open("example1.cpp",'r'):
    print line
||/Macro||
||/Source||

Given the fragment above, the source code in the file "example1.cpp"
would be inserted into the document.

||Section Inclusion||

Also, I'd like to be able to inline other sources of the same document
format:

||Include ~/docs/fubar.baz||

||/Section||


||Section Summary||

Of course, I am not looking for anything that looks exactly like what
I have shown. What I have presented here merely serves to illustrate
what sort of functionality I am looking for.

Neither am I looking for something of industrial strength, but
something that would solve more problems than it creates. The bottom
line is that I want authors to write something that looks mostly like
plain text, and be able to communicate a few key items of
meta-information via markup.

Any suggestions ?

||/Section||