Re: [mantisbt-dev] Documentation toolchain (was Re: Release MantisBT 1.2.9)

[Gianluca S. <gi...@gm...>]

On Tue, Mar 6, 2012 at 11:35 PM, Robert Munteanu
<rob...@gm...> wrote:
>
> I'm young enough ( MantisBT-wise at least ) to not remember why we
> chose docbook . As John pointed out, there are more lightweight
> alternatives.

We choose Docbook mostly because I proposed (and actually did) the
conversion from the older HTML files that composed the manual at that
time. The format was already known (at least to me, I'm still using it
at work) and covered the requirements we had (most important being one
"source", several output formats).

I agree that some years down the road there are compelling alternatives.


>
> We really should not be locked into using some very specific Linux
> distro to generate it. I recall strong headaches as I managed to get
> it to build on OpenSUSE ( 11.4 , have not tried 12.1 ).

Yay for vendor lock-in :)

The (sadly failed) plan was to make sure it was buildable in the
server, but some bug in the toolchain prevented me from finalizing it;
right now master should be in better shape because we moved to xml
docbook handled by publican which is supposed to be available on more
platforms.

Talking about the alternatives, I really like the Read The Docs
website, that integrates nicely with SCMs so it can build and publish
the docs as soon as they hit the git repo. I'm not sure how easy would
be to use it with mantis though.

-- 
Gianluca Sforna

http://morefedora.blogspot.com
http://identi.ca/giallu - http://twitter.com/giallu