Mailing-List: contact river-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: river-dev@incubator.apache.org
Received-SPF: neutral (nike.apache.org: local policy)
Message-ID: <4D05FE10.7060004@zeus.net.au>
Date: Mon, 13 Dec 2010 21:05:52 +1000
From: Peter Firmstone <jini@zeus.net.au>
User-Agent: Thunderbird 2.0.0.14 (X11/20080531)
MIME-Version: 1.0
To: river-dev@incubator.apache.org
Subject: Re: Website, docuemntation links, and river/src-doc/static/index.html
References: <843458.46775.qm@web33803.mail.mud.yahoo.com>
	<AANLkTinZ9YMJMR0uMK0AM7p7-j4ZHTdW9OTEK1firRjz@mail.gmail.com>
	<4D045DBA.1040606@zeus.net.au>	<4D04AA37.9000109@qcg.nl>
	<4D04AE0F.90601@zeus.net.au>	<4D04B2C9.3000009@qcg.nl>
	<4D056F51.7090607@zeus.net.au>
	<AANLkTimq=W+omFfAjDkMfVsR3CZu25znM8ummhGfW-vr@mail.gmail.com>
 <AANLkTi=ezsKzSVhxeYGNdOo7+Kgswe1iYfLciQC=hedo@mail.gmail.com>
In-Reply-To: <AANLkTi=ezsKzSVhxeYGNdOo7+Kgswe1iYfLciQC=hedo@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Tom Hobbs wrote:
> Speaking to Sim just now, he raised something that I skipped past entirely.
>
> I've been changing the Jini Specs from HTML into a style which matches
> the rest of our website - i.e. markdown.  In retrospect, maybe that
> wasn't the right thing to do, because (as has been pointed out) we'll
> need to convert the specs back from markdown into HTML for easy
> download/reading on part of the users.
>   

Actually don't rush into reversing your changes, lets think it through, 
Markdown is intended to be viewable as text, we've got a doc-src 
directory, we could keep your changes and include markdown as a build 
dependency.

> As I mention in this email, having Javadocs in a different format to
> the website is okay, and I guess that having the Jini Spec in a
> different format is okay also.  So I'm going to rollback my changes
> for the Jini Spec only.  This way we can just pull it off the site SVN
> for easy packaging in/with the release.
>   

Ok, can we go in the other direction though?  I like to build it 
locally, make changes, update and check links etc.

Can it be staged via an ant task.

Still a markdown javadoc tool sounds neat, makes source code easier to 
read too.

If there is an ant task to assist developers to download the required 
gpl libs like the markdown javadoclet, and jtreg for developers, then we 
aren't distributing them with the release, so not breaking any rules ;)

Cheers, Peter.
> The other bits of documentation that came along with the JS I think
> should still be converted to markdown because I don't think they're
> really things that are going to need downloading and distributing
> outside of the website.
>
> Is that okay?
>
>
> On Mon, Dec 13, 2010 at 10:07 AM, Tom Hobbs <tvhobbs@googlemail.com> wrote:
>   
>> The "Release Notes" that come along with the Jini specs that I
>> recently put into staging, aren't (I think) "release notes" in the
>> traditional sense.  At least not all of them.  There's some real
>> nuggets of information in them that need to appear under a title other
>> than "Release notes".
>>
>> With regards to what goes into our releases, the release notes as
>> generated out of Jira and anything else that we've been doing in the
>> past.  The RNs as described above don't necessarily fit into that
>> criteria.
>>
>> I don't know about markdown and javadocs, I do want to be able to host
>> the javadocs (automatically, as much as possible) on the website and
>> update them everytime we do a new release.  The Jini Specs should have
>> absolute links in them to refer to the most up-to-date javadocs.  We
>> can provide additional downloads for the javadocs (or include it in
>> the release download if we think that's necessary.)  I'm not convinced
>> that the Jini Spec needs to be included in each release, although a
>> single downloadable package of the stuff would be nice.
>>
>> Can we make it so that Hudson generates the Javadoc, and for a release
>> build, copies the Javadoc up into our website area?  The Javadoc could
>> also be zipped and made available from the Downloads page.  I don't
>> think that having the Javadoc in a different CSS/style thing to our
>> website is a big problem, in fact having non-matching Javadocs is
>> pretty common - from what I've seen elsewhere.
>>
>> To summarise, my thoughts would be:
>> - Hudson to build the Javadoc from the source as normal HTML
>> - Hudson to copy the Javadoc HTML to somewhere that it can be served
>> by our website
>> - Hudson to create a ZIP of the Javadoc HTML ready for download
>> - Hudson to create the release containing binaries/source and release
>> notes and made ready for download from website
>> - Jini Specifications (and other documentation) to be in markdown
>> format on the website and contain absolute links to the most
>> up-to-date Javadocs
>> - Jini Specifications (and other documentation) to be taken from the
>> HTML site SVN, zipped and made available for download
>>
>> On Mon, Dec 13, 2010 at 12:56 AM, Peter Firmstone <jini@zeus.net.au> wrote:
>>     
>>> The standards and release notes contain links to the build generated
>>> javadoc, built from java source.
>>>
>>> Is it possible to generate javadoc in the markdown format from the source
>>> code?  Or can markdown generate javadoc?
>>>
>>> If we could, then we could pull the website from it's svn path, and pull the
>>> standards, release notes and javadoc from river/trunk.
>>>
>>> This looks interesting: http://code.google.com/p/markdown-doclet/
>>>
>>> I think we currently access the javadoc from hudson builds for our website,
>>> but this isn't suitable for our release.  It would be nice if we could
>>> satisfy the website and the release with one source, since this reduces
>>> maintenance.
>>>
>>> I'm not sure what the way forward is at the moment, it requires some more
>>> thought.
>>>
>>> Cheers,
>>>
>>> Peter.
>>>
>>> Sim IJskes - QCG wrote:
>>>       
>>>> On 12/12/2010 12:12 PM, Peter Firmstone wrote:
>>>>         
>>>>> Ok, sounds logical, when you checkout and build River, all the
>>>>> documentation is build able from ant, which is then included in the
>>>>> build that I release, so the copy we build for the website should also
>>>>> be buildable from ant? Does this mean we need a new tool in our lib's to
>>>>> build the docs?
>>>>>           
>>>> Could be, yes. We could decide to include the docs in original markdown
>>>> format, or scrape them from the website, or convert them to html by
>>>> markdown. The only quick solutions that i see are include the original
>>>> mdtext files, or pull the converted mdtext files from the svn repo that
>>>> contains the website just before publishing (all html).
>>>>
>>>> Gr. Sim
>>>>
>>>> the chain is as follow for ASF CMS:
>>>>
>>>> mdtext in svn
>>>> stage:
>>>> convert to html
>>>> store html in website repo
>>>> checkout to staging website
>>>> publish:
>>>> copy html in website repo to other repo dir
>>>> chechout to production website (all the mirrors)
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>         
>>>       
>
>