On Fri, Nov 26, 2010 at 2:06 AM, Andreas Veithen <[email protected]> wrote: > On Thu, Nov 25, 2010 at 19:14, Hiranya Jayathilaka <[email protected]> > wrote: >> On Thu, Nov 25, 2010 at 8:57 AM, Ruwan Linton <[email protected]> wrote: >>> I guess andreas wrote some apt documentation, not so sure why though :-) >> >> I believe we need to convert them to the XML form for consistency >> sake. > > Before doing this, please note the following statement from the Maven > documentation: "An 'xdoc' is an XML document conforming to a small and > simple set of tags. Xdoc was the primary documentation format in Maven > 1, Maven 2 largely replaced this by Apt, but xdoc is still supported." > >> They seem to follow a different styling scheme. > > That is because some of the Xdoc documents define their own styles > (see e.g. Synapse_Extending.xml) instead of simply conforming to the > site-wide styles. Xdoc and APT are just two different input formats > for the same rendering engine.
That is true. I'm in the process of fixing these xdoc files to use the site wide css. If the site is designed correctly, > their will not be any visible difference between the two. > >> Not sure whether >> we have time for fixing these for 2.0 release. In that case we should >> definitely do it for the next release. > > Why? As Sanjiva would say, let many flowers bloom ;-) More seriously, > I don't see any good reason for converting everything to a single > format, especially not to Xdoc, considering that it only exists for > compatibility reasons and that APT is the recommended format. Well to me this is inconsistent and something we should fix. It just doesn't make any sense to have half of the documentation in one format and the rest in another format. Also this means that contributors updating the documentation should be familiar with both these formats. We should stick to one format, and adhere to a set of project wide standards when it comes to documentation. However given the amount of documentation we have, I don't think it's a good idea to implement these changes now. But IMO we should do it in the trunk in the near future. I also think that the way we present our samples is not optimal. We should improve that. > site [1] of the Maven project itself uses both formats. The fact that > Xdoc is predominant in Axis2 and related projects doesn't necessarily > mean that it's a good choice. The reason for this predominance is > actually two-fold: the heritage from Maven 1 (which was still used in > Axis2 1.0) and the misconception that Xdoc is a subset or a superset > of XHTML (i.e. that it is possible to write a document that is both a > correct Xdoc and XHTML document). Well I prefer xdoc over apt since it allows me to use the little HTML knowledge I have to develop web pages. I always thought apt markup is awkward and hard to learn. But if somebody can give me some good reasons I'm willing to invest some time on learning apt. Thanks, Hiranya > > [1] http://svn.apache.org/repos/asf/maven/site/trunk/src/site/ > >> Thanks, >> Hiranya >> >>> Thanks, >>> Ruwan >>> >>> On Thu, Nov 25, 2010 at 6:01 AM, Hiranya Jayathilaka <[email protected]> >>> wrote: >>>> >>>> Hi, >>>> >>>> Any idea why some of the documentation is written as apt files instead of >>>> xml? >>>> >>>> Thanks >>>> -- >>>> Hiranya Jayathilaka >>>> Senior Software Engineer; >>>> WSO2 Inc.; http://wso2.org >>>> E-mail: [email protected]; Mobile: +94 77 633 3491 >>>> Blog: http://techfeast-hiranya.blogspot.com >>>> >>>> --------------------------------------------------------------------- >>>> To unsubscribe, e-mail: [email protected] >>>> For additional commands, e-mail: [email protected] >>>> >>> >>> >>> >>> -- >>> Ruwan Linton >>> Software Architect & Product Manager, WSO2 ESB; http://wso2.org/esb >>> WSO2 Inc.; http://wso2.org >>> >>> Lean . Enterprise . Middleware >>> >>> phone: +1 408 754 7388 ext 51789 >>> email: [email protected]; cell: +94 77 341 3097 >>> blog: http://blog.ruwan.org >>> linkedin: http://www.linkedin.com/in/ruwanlinton >>> google: http://www.google.com/profiles/ruwan.linton >>> tweet: http://twitter.com/ruwanlinton >>> >> >> >> >> -- >> Hiranya Jayathilaka >> Senior Software Engineer; >> WSO2 Inc.; http://wso2.org >> E-mail: [email protected]; Mobile: +94 77 633 3491 >> Blog: http://techfeast-hiranya.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] > > -- Hiranya Jayathilaka Senior Software Engineer; WSO2 Inc.; http://wso2.org E-mail: [email protected]; Mobile: +94 77 633 3491 Blog: http://techfeast-hiranya.blogspot.com --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
