2010/4/11 Poul-Henning Kamp <[email protected]>: > > 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 _______________________________________________ varnish-dev mailing list [email protected] http://lists.varnish-cache.org/mailman/listinfo/varnish-dev
