couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Newson <rnew...@apache.org>
Subject Re: Docs, second try
Date Tue, 31 Jul 2012 14:01:25 GMT

Those are all good points, thanks. I haven't used Sphinx, is it popular? Are there any other
choices?

Does this decision block getting the current work onto the master branch? My main concern
with the donated documentation is not with the DocBook format itself (I quite like it, but
I'd switch in a heartbeat if some other format would encourage more contributions) but the
toolchain needed to build it. Last I looked, and forgive me if this has changed, there was
quite a bit of work (and a JVM) to build the docs. I wouldn't block the merge to trunk on
that basis, but I would probably spend some time to simplify it once it did.

Can we merge what we have into master today and address these problems together within the
code base? In the absolute worst case, we can remove it again for a release, but we could
leave these on the side forever while we mull over these issues.

B.


On 31 Jul 2012, at 14:28, Benoit Chesneau wrote:

> On Tue, Jul 31, 2012 at 3:22 PM, Robert Newson <rnewson@apache.org> wrote:
>> 
>> I dislike a veto without an adequate reason. Can you make your objections explicit?
What can't we do (that we need) with Markdown?
> 
> I gave some:
>>> [..]  There is no real doc system in markdown which will
>>> force to write another script and we will lost some features given by
>>> docbook (linking, references...)
>>> 
> 
> linking, automatic references, templating. specific section markups ...
> the need to write this tool to generate the doc while we could reuse a
> widely used tool wich is important for me. Also with sphinx you could
> still generate a PDF or event an ebook which is imo important for
> those who want to consult the doc offline.
> 
> - benoƮt


Mime
View raw message