On Wed, Jul 21, 2010 at 9:17 PM, Andreas Veithen <[email protected]>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 <[email protected]> wrote: > > +1, even static html is ok in my book. --Srinath > > > > On Wed, Jul 21, 2010 at 2:23 PM, Andreas Veithen > > <[email protected]> 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 > >> <[email protected]> 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 <[email protected]> > 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: [email protected] > >>>>> For additional commands, e-mail: [email protected] > >>>>> > >>>> > >>>> --------------------------------------------------------------------- > >>>> To unsubscribe, e-mail: [email protected] > >>>> For additional commands, e-mail: [email protected] > >>>> > >>>> > >>> > >> > >> --------------------------------------------------------------------- > >> To unsubscribe, e-mail: [email protected] > >> For additional commands, e-mail: [email protected] > >> > >> > > > > > > > > -- > > ============================ > > Srinath Perera, Ph.D. > > WSO2 Inc. http://wso2.com > > Blog: http://srinathsview.blogspot.com/ > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > -- Amila Suriarachchi WSO2 Inc. blog: http://amilachinthaka.blogspot.com/
