synapse-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andreas Veithen <andreas.veit...@gmail.com>
Subject Re: Synapse Documentation
Date Thu, 25 Nov 2010 20:36:10 GMT
On Thu, Nov 25, 2010 at 19:14, Hiranya Jayathilaka <hiranya911@gmail.com> wrote:
> On Thu, Nov 25, 2010 at 8:57 AM, Ruwan Linton <ruwan.linton@gmail.com> 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. 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. Even the
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).

[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 <hiranya911@gmail.com>
>> 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: hiranya@wso2.com;  Mobile: +94 77 633 3491
>>> Blog: http://techfeast-hiranya.blogspot.com
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@synapse.apache.org
>>> For additional commands, e-mail: dev-help@synapse.apache.org
>>>
>>
>>
>>
>> --
>> 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: ruwan@wso2.com; 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: hiranya@wso2.com;  Mobile: +94 77 633 3491
> Blog: http://techfeast-hiranya.blogspot.com
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@synapse.apache.org
> For additional commands, e-mail: dev-help@synapse.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@synapse.apache.org
For additional commands, e-mail: dev-help@synapse.apache.org


Mime
View raw message