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. * 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. 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]
