* why the lucky stiff <ruby-talk / whytheluckystiff.net> [Feb, 06 2004 23:40]:
> I'm not terribly familiar with reStructuredText, so another might be
> better suited.  reST is a more expansive (markup for definitions, field
> lists) and makes use of footnotes for linking.  reST is also bit more
> focused on making the text look like it's just formatted text.  You
> still often have to use <pre> in Textile.

good summary I'd say.

> However, Textile is geared more toward HTML generation, so there are
> hooks into using style sheets.  Also, tables are simpler.  The HTML
> generator does smart quotes, title/alt tags, citations, acronyms.  I
> think there are ways of doing this in reST.

i quite like the balance between not too much markup while still
allowing for flexibility.  the problem with reST in my opinion (why I
can't use it for my thesis anymore) is that it is too limiting, you
can't add new stuff yourself easily.

> reST is probably a better overall design, especially if you want PDF
> output for your text.  Textile is great for HTML stuffs.

Rant
----

mm...I'm getting the "Donald Knuth Complex" here, while writing my
masters' thesis...I still need to write all the code for my project, yet
i'm still contemplating writing my own documentation format as none of
the one i've ever used satisfy me.  DocBook is great, if it weren't for
its verbosity and shoddy design (honestly, it's too limiting).  relax ng
and docbook 5 will hopefully aleviate this somewhat...and, i'm sorry,
but MathML2 is great, if you're a markup processor.  if you're a
documentor, it's truly far too verbose, even with content markup...and
the fact that the DocBook MathML Module requires you to use the mml:
namespace you don't really gain much by having short element names such
as <mml:cn>1</mml:cn>...I'm thinking of doing some xslt preprocessing of
my DocBook files to make this a bit simpler, but in the end it's still a
bit too verbose...and the fact that there doesn't seem to be a good way
to have more than one DocBook Module in a document really blows.
My vision is to have something much like reST without all the html
related shortcuts (the multitude of ways to link stuff really annoys me)
and also not be so limiting in always maintaining WYSIWYG because it
makes parsing hell and it's not always necessary to be this way to be
appreciable text-wise.  Anyway, math and graphics would be drawn by
eqn(1) and pic(1) from [gt]roff, which are very textual in their
functionality, which would keep to the reST spirit.  Anyway, I dunno...I
really just need to start focusing on the stuff I really need to get
done...*sigh*...

What I would like to see in a good documentation format is:

* PS/PDF output backends
* Math support done in an intuitive way
* Graphics support done in an intuitive way
* Markup that doesn't chop the input into bits while still allowing you
  to markup easily and with meaning (such as adding emphasis and so on)

	nikolai

P.S.
TeX produces wonderful output, but is crap when it comes to actually
writing documents with it, I'm sorry to say.  And its graphics packages
are rather retarded as well.

Lout is stupid...end of story

roff is ugly and unreadable, breaks up input too much...xml is easier to
follow...

hm, that's about the end of my list of formats I've ooked at

D.S.

--
::: name: Nikolai Weibull    :: aliases: pcp / lone-star / aka :::
::: born: Chicago, IL USA    :: loc atm: Gothenburg, Sweden    :::
::: page: www.pcppopper.org  :: fun atm: gf,lps,ruby,lisp,war3 :::
main(){printf(&linux["\021%six\012\0"],(linux)["have"]+"fun"-97);}