Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Received-SPF: neutral (athena.apache.org: local policy)
Content-Type: text/plain; charset=us-ascii
Mime-Version: 1.0 (Apple Message framework v1278)
Subject: Re: Docs, second try
From: Jan Lehnardt <jan@apache.org>
In-Reply-To: <436CC93B-6244-4A01-9933-46B2937AB331@apache.org>
Date: Thu, 21 Jun 2012 17:18:07 +0200
Content-Transfer-Encoding: quoted-printable
Message-Id: <BF439EFB-238D-44BD-BD78-97A5BD154AB2@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>
 <70658AB3-81FA-4E3A-ABE6-D6299ED2704A@apache.org>
 <E2D5A5F1B3794024BBEC5AD03852711F@cloudant.com>
 <436CC93B-6244-4A01-9933-46B2937AB331@apache.org>
To: dev@couchdb.apache.org


On Jun 21, 2012, at 17:01 , Jan Lehnardt wrote:

>=20
> On Jun 21, 2012, at 16:55 , Simon Metson wrote:
>=20
>> Hey,
>>> Sorry, my bad, it actually ships with Macs as far as I can tell. I =
updated the README.
>>>=20
>>>=20
>>=20
>> Cool.=20
>>> Did you mean to do `make dev && utils/run` or is `./bin/couchdb` =
done in a `make install` target?
>> It was done in the make install target. make dev && utils/run works.
>>>=20
>>>> * 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
>>>=20
>>> I can't reproduce this in my dev repo or clean checkout.
>> Ah, I cocked up; I'd accidentally removed the jars when running the =
make clean :)=20
>>> It is already linked up in Futon, pointing to =
/_docs/manual/couchdb-manual.html-dir/index.html (see 06210b9), but it =
just jumps to the docs and out of futon, which isn't very user-friendly. =
We could iframe things, or open the docs in a new window/tab, although I =
tend to not like that :)
>>>=20
>=20
> Cool, thanks :)
>=20
>>>=20
>>>=20
>>=20
>> I think I mean where do we go now. Agree that integrating the docs =
into futon would be nice (though I don't know how to do that with =
docbook, not used it before now, will dig in).
>=20
> This has nothing to do with docbook, we generate HTML and we can link =
to that in Futon, I don't think we want to generate the Futon-docs part =
in docbook, but happy to be proven wrong. I think it'd be easer to make =
a docs.html in futon that keeps the header and sidebar and just shows =
the /_docs/... link.

Like this:

    https://dl.dropbox.com/u/82149/couchdb-futon-docs.png

Source:

    =
https://github.com/janl/couchdb/commit/bcfa57bee491837e91c65045870aaddf706=
b303d

Plus fine-tuning :)

Cheers
Jan
--=20


>=20
>=20
>> What about things like pulling in Dale's jquery.couch.js docs =
(daleharvey.github.com/jquery.couch.js-docs/symbols/index.html)?
>=20
> We should definitely consider this, but I think that is out of scope =
for this particular patch.
>=20
>=20
>> Once this is integrated with the main make I guess it makes sense to =
have a "normal" make just create the html for serving, and making =
building the pdf etc something you explicitly trigger.
>=20
> Agreed :)
>=20
> Cheers
> Jan
> --=20
>=20
>=20