Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Received-SPF: neutral (nike.apache.org: local policy)
Content-Type: text/plain; charset=windows-1252
Mime-Version: 1.0 (Apple Message framework v1278)
Subject: Re: Docs, second try
From: Jan Lehnardt <jan@apache.org>
In-Reply-To: 
 <CAJ_m3YB6-SpqQ70EzwOA5QXK1xj=TQV8FoFAi3Sar+cDXZkzMw@mail.gmail.com>
Date: Thu, 21 Jun 2012 15:53:30 +0200
Content-Transfer-Encoding: quoted-printable
Message-Id: <84B56A26-24F2-4C25-8534-C48092282A3B@apache.org>
References: <EC73BB16-F86A-4F6B-9143-A22B88381108@apache.org>
 <8A69B3F1-C955-4127-B92B-B0DA1AA9AEB6@apache.org>
 <19EB8367-1282-4406-9C51-B3AE4AFA0080@apache.org>
 <D5FEC7AA-2294-41F5-81E9-AF982BF29976@apache.org>
 <2E5C3210-58B9-48A7-9E21-3B6206D24899@apache.org>
 <382956416E9B4787895A95D59AC5ECC1@cloudant.com>
 <CAJ_m3YB6-SpqQ70EzwOA5QXK1xj=TQV8FoFAi3Sar+cDXZkzMw@mail.gmail.com>
To: dev@couchdb.apache.org

Thanks for the feedback, Paul.

On Jun 21, 2012, at 15:16 , Paul Davis wrote:

> I did some poking through of that docs branch the other day. I'll try
> and summarize my thoughts but I preface this with the fact I've been
> up all night debugging.
>=20
> The biggest technical issues I see is that I really dislike having the
> non-autotools build inside the autotools build. =46rom the discussion
> I've seen so far this seems to make things fail a lot in icky ways.
> The raw make system that the docs uses seems straightforward enough
> that redoing it to be a proper autotools build just seems like a
> matter of time for someone that knows autotools. But I'd prefer this
> were fixed before inclusion or it'll end up being one of those "we'll
> fix it later but never do" scenarios.

I'd greatly prefer that, I even gave it a shot, but gave up. I'm happy
to do a pairing session with you or Noah on this one.


> There's also the question of making it a soft dep. The doc builds
> require both perl and Java which is two more languages that we'd
> require if they're a hard dependency. Once the doc builds are
> integrated into autotools I don't think this will be a terribly
> difficult thing to accomplish but its another one of those things I'd
> like to happen so its not just carried on and hand waved forever.

The current implementation is a soft dependency, if COUCHDB_DOC_JAR_DIR
isn't defined, the docs aren't built and a message is printed at make
time.


> For legal stuff I'm mostly mollified from my reading. Though I think
> we should also start a thread on legal-discuss (or someone link me to
> one) about possibly non-ASL2.0 compatible dependencies for building
> docs (that aren't required to build the code and would be
> pre-generated for releases so as to not require downstream users to
> install said deps). I think we're good here but I'm unsure enough that
> I'd like some supervision on it.

I think we are good on this based on the "soft dependency" rule.

The dependencies and their licenses are:

 Saxon: Mozilla Public License version 1.0
 Xalan: Apache 2.0 (xalan.apache.org)
 Xerxes: Apache 2.0 (xerxes.apache.org)
 xslthl: zlib/libpng

All licenses can be included in source (Apache 2, zlib) or binary
form (MPL) in a release, which we don't even do. None of the
binaries "infect" the documentation .html files we'd ship as far
as I can tell.

But! =97 I think it is a great idea to present this to legal-discuss@
and get a second opinion.


> Other than that I think it looks good. We should probably take Jan's
> notes from this thread and put them in share/docs/(README|BUILDING) or
> something. And make sure the build system references that loudly if
> things go borkity borkity meatballs.

I hope that is all already in the README :)

Cheers
Jan
--=20


>=20
> On Thu, Jun 21, 2012 at 7:27 AM, Simon Metson <simon@cloudant.com> =
wrote:
>> I've been prodding Jan's docs branch this morning. Some successes, =
some fails.
>>=20
>> * I can't install xsltproc via brew (as in the docs README):
>>=20
>> $ brew install xsltproc
>> Error: No available formula for xsltproc
>>=20
>>=20
>> * Regardless of that I got the docs to build, and made a PDF/bunch of =
html files.
>> * I couldn't get this to work with a make of couch itself, the build =
of couch crashes:
>>=20
>> /tmp/couch $ ./bin/couchdb
>> Apache CouchDB 1.3.0a-7f1461e-git (LogLevel=3Dinfo) is starting.
>> {"init terminating in =
do_boot",{{badmatch,{error,{bad_return,{{couch_app,start,[normal,["/tmp/co=
uch/etc/couchdb/default.ini","/tmp/couch/etc/couchdb/local.ini"]]},{'EXIT'=
,{{badmatch,{error,shutdown}},[{couch_server_sup,start_server,1,[{file,"co=
uch_server_sup.erl"},{line,96}]},{application_master,start_it_old,4,[{file=
,"application_master.erl"},{line,274}]}]}}}}}},[{couch,start,0,[{file,"cou=
ch.erl"},{line,18}]},{init,start_it,1,[]},{init,start_em,1,[]}]}}
>>=20
>> Crash dump was written to: erl_crash.dump
>> init terminating in do_boot ()
>>=20
>> which I assume isn't related to docs.
>> * did a make clean in both docs and main dir, once I did that the =
docs build fails:
>> SEVERE: Exception
>> javax.xml.transform.TransformerException: =
org.apache.fop.fo.ValidationException: =
"{http://www.w3.org/1999/XSL/Format}block" is not a valid child of =
"fo:root"! (See position 1110:144)
>>=20
>>=20
>> I'm guessing something didn't get cleaned up correctly - I'm going to =
try a fresh check out next.
>>=20
>> Where do you want to go with this beyond having it available from =
futon? Like I said in Berlin I'm happy to contribute where I can...
>>=20
>>=20
>> On Sunday, 17 June 2012 at 14:17, Jan Lehnardt wrote:
>>=20
>>>=20
>>> On Jun 17, 2012, at 15:05 , Jan Lehnardt wrote:
>>>=20
>>>>=20
>>>> On Jun 17, 2012, at 12:47 , Jan Lehnardt wrote:
>>>>=20
>>>>>=20
>>>>> On Jun 17, 2012, at 12:12 , Jan Lehnardt wrote:
>>>>>=20
>>>>>> Same repo, some news:
>>>>>>=20
>>>>>> - updated NOTICE
>>>>>> - added minimal css styling to make it not look ass
>>>>>> - made make distcheck pass* (wooo!)
>>>>>> - linked the per-chapter build in Futon instead of the =
full-page.**
>>>>>>=20
>>>>>> As far as I can see, this is good to go into master.
>>>>>=20
>>>>> Well, one more thing=99: I need to hook this up to `make install`.
>>>>> I'll try and do this right away.
>>>>>=20
>>>>=20
>>>>=20
>>>> I got this half done, but I think I will need from you guys.
>>>>=20
>>>> The latest version is still on =
https://github.com/janl/couchdb/tree/docs
>>>>=20
>>>> If you do
>>>>=20
>>>> $ export COUCHDB_DOC_JAR_DIR=3D/path/to/doc/jars
>>>> $ make
>>>> $ cd share/docs
>>>> $ make
>>>> $ cd ../..
>>>> $ make install
>>>>=20
>>>=20
>>>=20
>>> actually:
>>>=20
>>> $ cd share/docs
>>> $ make
>>> $ cd ../..
>>> [$ make]
>>> $ make install
>>>=20
>>> Cheers
>>> Jan
>>> --
>>>=20
>>>>=20
>>>> The docs get installed properly and the hook up with Futon works =
just fine.
>>>>=20
>>>> Obviously, we want `make` in `share/doc` to run as part of the top =
level
>>>> make, but I don't know how to hook this up.
>>>>=20
>>>> I tried porting all `Makefiles` in `share/doc` to `Makefile.am =
(http://Makefile.am)` like we do
>>>> elsewhere, but then the docs build system gets confused with paths, =
I don't
>>>> think this is going to work without porting the whole docs build =
system to
>>>> the way CouchDB uses make. An easier way for now would be to treat =
the docs
>>>> build system as a black box that gets started with `make` in =
share/docs.
>>>> `make install` for docs is handled in `share/Makefile.am =
(http://Makefile.am)`.
>>>>=20
>>>> Any help is appreciated!
>>>> Cheers
>>>> Jan
>>>> --
>>>>=20
>>>=20
>>>=20
>>>=20
>>=20
>>=20