production of Varnish Documentation

[Jean-Baptiste Quenot]

2010/4/11 Poul-Henning Kamp <phk at phk.freebsd.dk>:
>
> Yes, if you write documentation for half your workday, that works,
> but if you write code most of your workday, that does not work.
> Trust me on this, I have 25 years of experience avoiding using such
> tools.
>
> I found one project which has thought radically about the problem,
> and their reasoning is interesting, and quite attractive to me:
>
>        1. .TXT files are the lingua franca of computers, even if
>        you are logged with TELNET using IP over Avian Carriers
>        (Which is more widespread in Norway than you would think)
>        you can read documentation in a .TXT format.
>
>        2. .TXT is the most restrictive typographical format, so
>        rather than trying to neuter a high-level format into .TXT,
>        it is smarter to make the .TXT the source, and reinterpret
>        it structurally into the more capable formats.
>
> In other words: we are talking about the "ReStructuredText" of the
> Python project.

+1

I use RST+Docutils with Sphinx (a tool to build the documentation with
just a simple 'make') for my project, and I'm quite happy with it.
-- 
Jean-Baptiste Quenot