Return-Path: X-Original-To: apmail-cayenne-dev-archive@www.apache.org Delivered-To: apmail-cayenne-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 7E3BD8199 for ; Mon, 29 Aug 2011 00:31:16 +0000 (UTC) Received: (qmail 82624 invoked by uid 500); 29 Aug 2011 00:31:16 -0000 Delivered-To: apmail-cayenne-dev-archive@cayenne.apache.org Received: (qmail 82501 invoked by uid 500); 29 Aug 2011 00:31:15 -0000 Mailing-List: contact dev-help@cayenne.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@cayenne.apache.org Delivered-To: mailing list dev@cayenne.apache.org Received: (qmail 82481 invoked by uid 99); 29 Aug 2011 00:31:15 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 29 Aug 2011 00:31:15 +0000 X-ASF-Spam-Status: No, hits=0.7 required=5.0 tests=SPF_NEUTRAL,TO_NO_BRKTS_PCNT X-Spam-Check-By: apache.org Received-SPF: neutral (nike.apache.org: local policy) Received: from [59.167.240.32] (HELO fish.ish.com.au) (59.167.240.32) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 29 Aug 2011 00:31:06 +0000 Received: from ip-136.ish.com.au ([203.29.62.136]:57849) by fish.ish.com.au with esmtpsa (TLSv1:CAMELLIA256-SHA:256) (Exim 4.76) (envelope-from ) id 1QxpkH-0000kF-1k; Mon, 29 Aug 2011 10:30:34 +1000 X-CTCH-RefID: str=0001.0A150202.4E5ADDAA.003A,ss=1,re=0.000,fgs=0 Message-ID: <4E5ADDA8.1050000@maniatis.org> Date: Mon, 29 Aug 2011 10:30:32 +1000 From: Aristedes Maniatis User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:6.0) Gecko/20110812 Thunderbird/6.0 MIME-Version: 1.0 To: dev@cayenne.apache.org CC: Andrus Adamchik Subject: Re: docbook - continued References: <95584249-7F68-4248-A6CD-C6853F90A80C@objectstyle.org> <4E591646.7000307@maniatis.org> <08B40CE3-A206-4C93-B4F8-C61DF0815522@objectstyle.org> In-Reply-To: <08B40CE3-A206-4C93-B4F8-C61DF0815522@objectstyle.org> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Virus-Checked: Checked by ClamAV on apache.org On Sun Aug 28 23:40:28 2011, Andrus Adamchik wrote: > > On Aug 28, 2011, at 12:30 PM, Andrus Adamchik wrote: > >> I am less concerned about syntax coloring though, more about code blocks standing out on the page via a different background color and/or border. Especially since the PDF version is likely be black and white (?) > > Same thing for the tables. I just started on Appendix A (a list of Cayenne properties) and the big font used for the blocks and the lack of borders and backgrounds make them a bit unreadable in either HTML or PDF formats. > > Also even though we only have like 5% of the new docs ready, I think this maybe the 5% that matters. I almost finished all the DI and ServerRuntime chapters. So we should consider publishing this on the site and with the upcoming release. > > BTW, working on the docs now allows me to take a user view of the framework, and I am noticing things that we can polish a bit. Two most obvious points: > > 1. DI property names per Appendix A (make them shorter and more symmetrical) > > 2. Default modeler object naming (UntitledDomain, UntiltledDomainMap) trickles to the XML file naming, so we'd rather come up with something that makes sense. E.g. "project" for domains (there can be only 1 per project in 3.1), "datamap", "datamap1", etc. for DataMaps. These will result in cleaner file names like cayenne-project.xml, datamap.map.xml etc.). > > Andrus Let's get what we have published and I can continue to work on the formatting to make it cleaner and more readable. There is no reason why the PDF cannot be coloured. Please don't worry about the XML file naming. That will not be visible in the html or pdf output, so use whatever naming makes sense. I'll try and make some time in the next week to review what you've already done and what I can do to make it prettier. As for the publishing, I am not sure what the current Apache thinking is for best practice: * Jenkins: publish -> p.a.o * Build script on p.a.o * Jenkins build, script on p.a.o to pull results Ari Ari -- --------------------------> Aristedes Maniatis GPG fingerprint CBFB 84B4 738D 4E87 5E5C 5EFA EF6A 7D2E 3E49 102A