docs: getting rid of the troff pages.

Per Buer perbu at
Mon May 31 15:10:07 CEST 2010


Work continues on the documentation. Anders Berg has written the
installation guide and I've written a tutorial. They are both expected
to be more or less complete within a week or two (it's open to debate
whether or not the tutorial should cover advanced topics such as ESI
or if these things only should be documented in the reference guide -
I think the tutorial only should cover the basics).

The third and possibly the most essential part of the documentation is
the reference guide. The reference guide will amongst other things
contain the man pages for all the programs. Since including troff in
reStructuredText is difficult I suggest we convert the existing troff
pages into reStructuredText. This makes it easy to include the man
pages in the reference guide with the added bonus of making
contributing to the man pages easier (no one likes editing troff).

The problem is that we now add a build dependency on the Python
docutils. Personally I don't mind build-dependencies but the FreeBSD
tradition is that one compiles the software in its production
environment and one should try to keep the production environment as
clean as possible. If we are to honor this I suggest we check in the
converted man pages back into SVN the way we do with the TCL output.

Per Buer,  Varnish Software
Phone: +47 21 54 41 21 / Mobile: +47 958 39 117 / skype: per.buer

More information about the varnish-dev mailing list