[prev in list] [next in list] [prev in thread] [next in thread] 

List:       synapse-dev
Subject:    Re: Synapse Documentation
From:       Hiranya Jayathilaka <hiranya911 () gmail ! com>
Date:       2010-11-25 23:13:55
Message-ID: AANLkTik+ozg0HF2Wwgt7fbsjE44Wa3kUNtdfaa+gCdvm () mail ! gmail ! com
[Download RAW message or body]

On Fri, Nov 26, 2010 at 2:06 AM, Andreas Veithen
<andreas.veithen@gmail.com> wrote:
> 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.

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 <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
>
>



-- 
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


[prev in list] [next in list] [prev in thread] [next in thread]