[zeromq-dev] Documentation converted to AsciiDoc

[Peter Alexander]

On Wed, Feb 10, 2010 at 10:30 AM, Martin Lucina <mato at kotelna.sk> wrote:
> All,
>
> in commit r354efc5 I have converted all the existing manual pages to
> AsciiDoc[1].
>
> This allows us to generate nicer documentation in more formats, so e.g. we
> can distribute HTML documentation for Windows users. This will be included
> in the next release.
>
> It also gives us a much nicer syntax for the documentation source.
>
> I've tried to do this in a way that doesn't force people to install the
> entire AsciiDoc toolchain if they just want to build 0MQ. So:
>
> 1) Future release tarballs will include prebuilt manual pages and HTML from
> the AsciiDoc source. This is done during "make dist" from git. Therefore,
> you do *not* need AsciiDoc to build 0MQ from a release tarball.
>
> If, however, you modify any of the AsciiDoc source files then "make" will
> probably try to rebuild things, which will break unless you do have
> AsciiDoc.
>
> 2) If you are building from git, configure will check for the presence of
> asciidoc and xmlto on your system and if these are not found, manual pages
> or HTML will *NOT* be built.
>
> Maintainer notes:
>
> - "make clean" or "make distclean" do not remove built .html or man files.
> - "make maintainer-clean" does, should you want to do that.
> - "make dist" will include HTML and manpages in the released tarball
>
> If this breaks anything for distribution packagers, please speak up now!
>
> Cheers,
>
> -mato
>
> [1] http://www.methods.co.nz/asciidoc/.
>    To install on Debian "apt-get install asciidoc xmlto" should be
>    sufficient.
> _______________________________________________
> zeromq-dev mailing list
> zeromq-dev at lists.zeromq.org
> http://lists.zeromq.org/mailman/listinfo/zeromq-dev
>

Hi Martin.
Just figured I'd mention.. Are familiar with restructured text[1] and
its companion, sphinx[2]. Very nice and easy to use with multiple
output targets available. Depending on Python is downfall though.

Peter

[1] http://www.answers.com/main/ntquery?s=restructured+text&gwp=13
[2] http://www.answers.com/topic/sphinx-documentation-generator