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. > > The biggest technical issues I see is that I really dislike having the > non-autotools build inside the autotools build. From 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! — 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 -- > > On Thu, Jun 21, 2012 at 7:27 AM, Simon Metson <[email protected]> wrote: >> I've been prodding Jan's docs branch this morning. Some successes, some >> fails. >> >> * I can't install xsltproc via brew (as in the docs README): >> >> $ brew install xsltproc >> Error: No available formula for xsltproc >> >> >> * 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: >> >> /tmp/couch $ ./bin/couchdb >> Apache CouchDB 1.3.0a-7f1461e-git (LogLevel=info) is starting. >> {"init terminating in >> do_boot",{{badmatch,{error,{bad_return,{{couch_app,start,[normal,["/tmp/couch/etc/couchdb/default.ini","/tmp/couch/etc/couchdb/local.ini"]]},{'EXIT',{{badmatch,{error,shutdown}},[{couch_server_sup,start_server,1,[{file,"couch_server_sup.erl"},{line,96}]},{application_master,start_it_old,4,[{file,"application_master.erl"},{line,274}]}]}}}}}},[{couch,start,0,[{file,"couch.erl"},{line,18}]},{init,start_it,1,[]},{init,start_em,1,[]}]}} >> >> Crash dump was written to: erl_crash.dump >> init terminating in do_boot () >> >> 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) >> >> >> I'm guessing something didn't get cleaned up correctly - I'm going to try a >> fresh check out next. >> >> 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... >> >> >> On Sunday, 17 June 2012 at 14:17, Jan Lehnardt wrote: >> >>> >>> On Jun 17, 2012, at 15:05 , Jan Lehnardt wrote: >>> >>>> >>>> On Jun 17, 2012, at 12:47 , Jan Lehnardt wrote: >>>> >>>>> >>>>> On Jun 17, 2012, at 12:12 , Jan Lehnardt wrote: >>>>> >>>>>> Same repo, some news: >>>>>> >>>>>> - 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.** >>>>>> >>>>>> As far as I can see, this is good to go into master. >>>>> >>>>> Well, one more thing™: I need to hook this up to `make install`. >>>>> I'll try and do this right away. >>>>> >>>> >>>> >>>> I got this half done, but I think I will need from you guys. >>>> >>>> The latest version is still on https://github.com/janl/couchdb/tree/docs >>>> >>>> If you do >>>> >>>> $ export COUCHDB_DOC_JAR_DIR=/path/to/doc/jars >>>> $ make >>>> $ cd share/docs >>>> $ make >>>> $ cd ../.. >>>> $ make install >>>> >>> >>> >>> actually: >>> >>> $ cd share/docs >>> $ make >>> $ cd ../.. >>> [$ make] >>> $ make install >>> >>> Cheers >>> Jan >>> -- >>> >>>> >>>> The docs get installed properly and the hook up with Futon works just fine. >>>> >>>> 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. >>>> >>>> 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)`. >>>> >>>> Any help is appreciated! >>>> Cheers >>>> Jan >>>> -- >>>> >>> >>> >>> >> >>
