Re: Nice job on new configuration document

[Jens Goldhammer <go...@googlemail.com>]

Hi Ruwan,

*generation of pdf:*
it is a good point to have a generation to pdf. I have found some 
information on the maven site:
http://maven.apache.org/doxia/index.html

I have read that XDoc is still supported, but is replaced by Apt in general.
http://maven.apache.org/doxia/references/xdoc-format.html
http://maven.apache.org/doxia/references/apt-format.html

Ok, you use xdoc, so maybe this is a point to generate the pdf?

*what do others according to pdf docs?*
For example, camel uses BOOM CSS in conjunction with Prince to generate 
a good looking pdf.

http://activemq.apache.org/camel/pdf-documentation-guide.html
http://www.princexml.com/samples/

But I don´t know how do they get Prince- it is very expensive (except 
the personal license)....

*my persional opinion to pdf documentaiton:*
LaTeX is the best way to generate a good looking pdf-documentation. I 
have written my thesis with it and it was great to have so many packages 
who format my text, listings, figures and tables like I want. 
Nevertheless it will be a pain to have two entry points for 
documentation- the LaTeX files for pdf and the xdoc files for html. Both 
must be kept synchronized. But I would prepare a LaTeX template if you 
are interested in! Maybe you say, the documentation on the website and 
the pdf have not to be the same.
Maybe, anybody knows a better way?
What´s about docbook?

*general comments/hints:
*- Is there any way to have a autobreak for the source listings, e.g. in 
http://synapse.apache.org/Synapse_Configuration_Language.html?
   Some code cannot be read very good...
- My opinion about the website in general is that it would be better to 
have a cms or a wiki behind it? It would be great to have changes on the 
news site without building and deploying the complete synapse 
documentation. (I think, you have a good mechanism on your site wso2.org)
- do you ever think of joining synapse and wso2 esb? I know, Synapse is 
hosted at Apache and wso2 esb not, but it would be better for the users 
to know that there is one product and you get the admin-ui as a plugin? 
Or are there any licence hurdles?

Thanks,
Jens


Ruwan Linton schrieb:
> Hi Jay,
>
> Thanks for the comments, I think the pdf of the above specified guide is a
> cool addition. We need to find a mechanism to generate the pdf from the xdoc
> pages. I will work on this and try to add a pdf of the documents too.
>
> Thanks,
> Ruwan
>
> On Tue, Apr 29, 2008 at 2:14 AM, Jaeger, Jay <ja...@dot.state.wi.us>
> wrote:
>
>   
>> Just a quick follow up on a message I sent long, long ago.
>>
>> The new configuration document at
>> http://synapse.apache.org/Synapse_Configuration_Language.html seems much
>> improved -- some good ground-level explanations of structure, examples, a
>> basic explanation of what Axis2 is doing there, and so on.
>>
>> Now, that being said, one small critique:  because of the way it is laid
>> out, it won't print reasonably from some certain browsers made by a vendor
>> whose name begins with "M" unless you print it in landscape mode.  It
>> would
>> be really nice to see a PDF of this thing.
>>
>> (The Quick Start guide has the same kind of issue).
>>
>> Overall, though, a really nice job.  Keep up the good work.
>>
>> Jay Jaeger
>>
>> -----Original Message-----
>> From: Jaeger, Jay
>> Sent: Monday, October 01, 2007 7:54 AM
>> To: 'synapse-user@ws.apache.org'
>> Subject: RE: any news about new version of synapse?
>>
>>
>> I would like to add my voice to those who have expressed interest in JDBC
>> as
>> an interface/transport for synapse.
>>
>> We have a number of systems in our organization which interact in an
>> unstructured way, by reading from and writing to each others' databases.
>>  We
>> have found that in trying to institute more of an SOA approach, that it
>> has
>> been very hard to convince projects to invest even modest amounts of time
>> to
>> build or user service interfaces.  The single biggest reason I am
>> following
>> developments of synapse is a hope that if we could expose those databases
>> in
>> a more structured way, by coupling an HTTP service to a JDBC SQL Query
>> (with
>> data in our out) we could "lift" these interactions out of application
>> code
>> into service interfaces without having to write code.  Once we have some
>> services, the client side requesting the service will probably fall into
>> place, and once we do that, then I think it will be easier to get folks to
>> define higher level service interfaces.
>>
>> But we have to start somewhere, and getting started has proved
>> challenging.
>>
>> I would a;lso point out the need for some higher level documentation /
>> tutorial.  The tutorial is great for installation verification, and as
>> code
>> examples, but is not so great for trying to figure out what synapse might
>> actually be good for, or for understanding what all the pieces do.  (For
>> example, a newbie might ask, what the heck is Axis2, anyway....).
>> Ordinarily, it is the kind of thing I might volunteer to dig in and do,
>> but
>> with a full time "day job" plus teaching a 3 credit course at the local
>> tech
>> school in Linux (with labs and all that -- coming to another 12 hours/week
>> including class time), I just won't have the time.
>>
>> JRJ
>>
>>
>>     
>
>
>