axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Amila Suriarachchi <amilasuriarach...@gmail.com>
Subject Re: [Vote] Simplifying the Axis2 release process
Date Sat, 24 Jul 2010 07:10:18 GMT
On Wed, Jul 21, 2010 at 9:17 PM, Andreas Veithen
<andreas.veithen@gmail.com>wrote:

> For the moment, the build assumes that some of the files in the
> documentation module are both valid Xdoc files and valid XHTML. More
> precisely, these files are submitted as Xdoc files to the Maven site
> plugin, but also included as XHTML files in the Documents Distribution
> by renaming them from *.xml to *.xhtml. That more or less works,
> because there is a large overlap between Xdoc and XHTML (and the site
> plugin doesn't use schema validation). However, the Xdoc processor
> will misinterpret or strip some of the XHTML specific attributes and
> tags. In addition, this prevents us from using Xdoc specific features
> such as automatic ToC generation or snippets. This also means that
> when modifying the documentation, one would have to check both the
> Maven site and the Documents Distribution to make sure that the
> modification gives the expected result.
>
> To increase the "Sanity Quotient", I think we need to make a choice
> here and agree on one of the following two options:
>
> 1. Consider them as Xdoc files. For the Documents Distribution we
> would then simply package a copy of the generated Maven site into to
> ZIP.
>
> 2. Consider them as XHTML. In that case, we would rename them to .html
> in SVN and include them as static content in the site. They would then
> be displayed in the same way as in the current Documents Distribution,
> i.e. without the navigation stuff generated by Maven.
>
> There are pros and cons for both solutions.
>
> Pros for Xdoc:
>
> * Better integration into the Maven site: all pages have the same
> navigation.
> * One can use APT (which is actually the recommended format in Maven
> 2) instead of Xdoc.
> * Possibility to leverage Xdoc features such as table of contents.
>
> Pros for XHTML:
>
> * Better layout and navigation (although that is probably only a
> matter of optimizing the Maven site styles and navigation).
> * No need to generate the site to validate modifications of the
> documentation.
>
> One should note that in 2010, when presented with the choice between
> browsing documentation online and downloading documentation as a ZIP
> to browse it locally, the vast majority of people will probably choose
> the online option. The only real use case for the Documentations
> Distribution is to be able to read the documentation while traveling
> or while working in a place without Internet connection. For these use
> cases, it should be enough to provide users an offline copy of the
> site.
>
> Therefore, my proposal is as follows:
>
> * As a short term solution, change the Documents Distribution to
> contain a copy of the generated site, i.e. consider the files as Xdoc,
> not XHTML.
>

+1. I think this is what synapse does. It has all the documents in Xdoc
format.


> * As a long term solution, convert the relevant parts of the
> documentation to DocBook and render it as HTML for inclusion in the
> site and as PDF for inclusion in the Documents Distribution. That has
> a real added value because the PDF version allows users to easily
> print the documentation.
>

+1.

The other most important part is to update the documents :). I'll try to go
through them.

thanks,
Amila.

>
> Thoughts?
>
> Andreas
>
> On Wed, Jul 21, 2010 at 11:29, Srinath Perera <srinath@wso2.com> wrote:
> > +1, even static html is ok in my book. --Srinath
> >
> > On Wed, Jul 21, 2010 at 2:23 PM, Andreas Veithen
> > <andreas.veithen@gmail.com> wrote:
> >> At the same time I will also remove the Google Analytics stuff, for
> >> the same reasons as in Axiom [1].
> >>
> >> Andreas
> >>
> >> [1] http://svn.apache.org/viewvc?view=revision&revision=951872
> >>
> >> On Wed, Jul 21, 2010 at 10:49, Andreas Veithen
> >> <andreas.veithen@gmail.com> wrote:
> >>> I'm also going to simplify the download page(s). In the site that is
> >>> currently online, the 1.4 download page actually refers to 1.5 and the
> >>> pages for 1.2 and 1.3 contains links to mirrors, while the overview
> >>> page correctly identifies the status of these releases as archived.
> >>> Since we are not able to maintain these pages correctly, the best is
> >>> to have a single page with download links for all releases.
> >>>
> >>> Andreas
> >>>
> >>> On Tue, Jul 20, 2010 at 15:14, Glen Daniels <glen@thoughtcraft.com>
> wrote:
> >>>> Huge +1 to this increase in the Sanity Quotient. :)
> >>>>
> >>>> --Glen
> >>>>
> >>>> On 7/17/2010 5:58 PM, Andreas Veithen wrote:
> >>>>> All,
> >>>>>
> >>>>> It looks like one of the major pain points when doing an Axis2
> release
> >>>>> is producing and deploying the Maven site. The complexity of this
> part
> >>>>> of the process stems from the fact that in the (deployed) site we
not
> >>>>> only have the documentation for the current release, but also the
> >>>>> pages for previous releases. There are a couple of ant scripts to
> make
> >>>>> this work, but the stuff is difficult to understand, maintain and
> use.
> >>>>> I think that the added value of linking to the documentation of
> >>>>> previous releases doesn't justify this complexity, and I would like
> to
> >>>>> radically simplify this.
> >>>>>
> >>>>> Here is my proposal:
> >>>>>
> >>>>> * Change modules/documentation to make it a simple and
> straightforward
> >>>>> Maven site, without any links to or inclusion of previous releases.
> >>>>> * When doing a release, we archive the site of the previous release
> by
> >>>>> moving it to a subfolder.
> >>>>> * Once the new axis.apache.org site developed by Milinda et al is
> >>>>> ready, we can link to the archived Maven sites from there.
> >>>>>
> >>>>> Here is my +1.
> >>>>>
> >>>>> Andreas
> >>>>>
> >>>>> ---------------------------------------------------------------------
> >>>>> To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
> >>>>> For additional commands, e-mail: java-dev-help@axis.apache.org
> >>>>>
> >>>>
> >>>> ---------------------------------------------------------------------
> >>>> To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
> >>>> For additional commands, e-mail: java-dev-help@axis.apache.org
> >>>>
> >>>>
> >>>
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
> >> For additional commands, e-mail: java-dev-help@axis.apache.org
> >>
> >>
> >
> >
> >
> > --
> > ============================
> > Srinath Perera, Ph.D.
> >    WSO2 Inc. http://wso2.com
> >    Blog: http://srinathsview.blogspot.com/
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
> > For additional commands, e-mail: java-dev-help@axis.apache.org
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
> For additional commands, e-mail: java-dev-help@axis.apache.org
>
>


-- 
Amila Suriarachchi
WSO2 Inc.
blog: http://amilachinthaka.blogspot.com/

Mime
View raw message