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||

 

[Erik Max Francis]

I'm looking for something to help developers wirte documentation for
bits of software they are writing.

reStructredText. Bigtime.

 

[Jacek Generowicz]

reStructredText. Bigtime.

Way cool !

I am rather shocked that this (or its ancestors) has not registered on
my radar before now.

Thanks !

 

[Peter Hansen]

Way cool !

I am rather shocked that this (or its ancestors) has not registered on
my radar before now.

It's ancestors, at least in the "Structured Text" world, weren't
up to the task.

But they didn't have David Goodger behind them...

-Peter

 

[Paul Rubin]

Please don't invent yet another markup language. It gets incredibly
difficult to keep them all straight. There's some standard being
developed for Wiki markup. Why don't you use that. The stuff in your
example already looks pretty similar to wikipedia markup. Another
idea is use Texinfo.

 

[Aahz]

Way cool !

I am rather shocked that this (or its ancestors) has not registered on
my radar before now.

You should be shocked. ;-) It's been discussed lots. The really neat
thing about reST is that it scales upward fairly well -- I'm writing a
book with it, and so is at least one other person.

 

[William Park]

Please don't invent yet another markup language. It gets incredibly
difficult to keep them all straight.

Seconded. At least, try to use whitespace as markup tags... you'll be
surprised.

 

[Michele Simionato]

<snip>

I write everything in rst format and then convert to HTML,Latex,PS, PDF, etc.
For what concerns the documentation, I write snippets and examples inside
it, then I execute the text file using (a minor hack to) doctest and I
get (additional) tests for free. Finally, I write the documentation (call
it implementation proposal if you wish) before writing the actual code,
so I get Documentation Driven Development

Way cool: it is something between literate programming and TDD. Most
importantly it works. I have yet to implement the second step: the idea
is to convert the documentation in HTML, put it on the Web and let
the customer run the tests with a click on the browser as soon as he reads
the documentation (or proposal of implementation) and see if he/she likes it.
It is not difficult to implement though.

I think you get the picture. doctest is still largely unexplored but it
has enourmous potentiality in terms of easy of use and convenience.
Think only to the fact that you get always updated documentation by definition.


Michele Simionato

 

[Magnus Lie Hetland]

[snip]

I second the suggestion to use reStructuredText, but just in case you
really want to play around with a format of your own, you could take a
look at Atox, which lets you do that:

http://atox.sf.net