You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@click.apache.org by Bob Schellink <sa...@gmail.com> on 2009/01/16 20:17:18 UTC
New docs format
Hi all,
In the past we've had a discussions about porting the documentation to
Docbook. This would allow us to generate
documentation in both Html and PDF format and provide a single document
which is easy to search.
I've converted the Introduction section to Docbook and uploaded the
result here:
http://people.apache.org/~sabob/test/click-docs.zip
All feedback is appreciated.
kind regards
bob
Re: New docs format
Posted by Bob Schellink <sa...@gmail.com>.
Gilberto C. Andrade wrote:
> I'm looking for svn click url, but without success! The docs only
> mention this one:http://svn.apache.org/viewvc/incubator/click/trunk.
Ah sorry that url is for browsing. There is a new developer-guide in
trunk but not published yet.
Anyways for checkout use these urls:
http://svn.apache.org/repos/asf/incubator/click/
http://svn.apache.org/repos/asf/incubator/click/trunk/tools/docbook/
kind regards
bob
>
> Any tip?
>
> Gilberto
>
> 2009/1/18 Bob Schellink <sa...@gmail.com>:
>> I've checked in the new Click Docs project under tools/docbook:
>>
>> http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/
>>
>> There is also a README.txt which provides some info on how to setup and
>> build the project.
>>
>> Once the conversion is done, we'll move the Docbook docs into the Click
>> distribution under 'documentation/docs/user-guide'. The new docs will most
>> likely only be included in 2.1.0.
>>
>> @Gilberto, the easiest way to contribute docs would be to create patches and
>> upload them to the JIRA. We should also communicate to this list which
>> section is being worked on. For example if you are busy converting
>> 'pages.html' just post a message here, otherwise we might end up duplicating
>> effort. Unfortunately our Apache JIRA is not available yet so we will have
>> to wait a little while longer before we can start the conversion process.
>>
>> If you have any questions don't hesitate to ask.
>>
>> kind regards
>>
>> bob
>>
>>
>> Bob Schellink wrote:
>>> For a start I think the following should be converted:
>>>
>>> introduction.html
>>> why-click.html
>>> pages.html
>>> controls.html
>>> configuration.html
>>> best-practices.html
>>>
>>> Best to grab the latest version from trunk[2]:
>>>
>>> Btw I forgot to include the actual Docbook in click-docs.zip earlier, but
>>> its available now. Just download click-docs.zip again [3].
>>>
>>> kind regards
>>>
>>> bob
>>>
>>> [1]: http://velocity.apache.org/docbook/
>>> [2]:
>>> http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/docs/
>>> [3]: http://people.apache.org/~sabob/test/click-docs.zip
>>>
>>
>
Re: New docs format
Posted by Bob Schellink <sa...@gmail.com>.
Gilberto C. Andrade wrote:
> I've found this one:
> https://svn.apache.org/repos/asf/incubator/click/trunk
I suggest you use 'http' instead of 'https'. 'https' is for developers
who has login credentials so even if you checkout, you won't be able
to checkin.
I've created a JIRA where you can upload patches:
https://issues.apache.org/click/browse/CLK-482
>
> But with erro:
> Error validating server certificate for https://svn.apache.org:443:
> - Unknown certificate issuer
> Fingerprint: cc:54:a4:a9:ec:3a:9b:1c:23:ac:2d:57:c6:96:9f:5f:4a:1d:2d:86
> Distinguished name: 07969287,
> http://certificates.godaddy.com/repository, GoDaddy.com, Inc.,
> Scottsdale, Arizona, US
> Can I accept this certificated?
Btw this is the correct certificate for Apache source. See here for
details: http://www.apache.org/dev/version-control.html
kind regards
bob
>
> Gilberto
>
> 2009/1/19 Gilberto C. Andrade <gi...@gmail.com>:
>> I'm looking for svn click url, but without success! The docs only
>> mention this one:http://svn.apache.org/viewvc/incubator/click/trunk.
>>
>> Any tip?
>>
>> Gilberto
>>
>> 2009/1/18 Bob Schellink <sa...@gmail.com>:
>>> I've checked in the new Click Docs project under tools/docbook:
>>>
>>> http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/
>>>
>>> There is also a README.txt which provides some info on how to setup and
>>> build the project.
>>>
>>> Once the conversion is done, we'll move the Docbook docs into the Click
>>> distribution under 'documentation/docs/user-guide'. The new docs will most
>>> likely only be included in 2.1.0.
>>>
>>> @Gilberto, the easiest way to contribute docs would be to create patches and
>>> upload them to the JIRA. We should also communicate to this list which
>>> section is being worked on. For example if you are busy converting
>>> 'pages.html' just post a message here, otherwise we might end up duplicating
>>> effort. Unfortunately our Apache JIRA is not available yet so we will have
>>> to wait a little while longer before we can start the conversion process.
>>>
>>> If you have any questions don't hesitate to ask.
>>>
>>> kind regards
>>>
>>> bob
>>>
>>>
>>> Bob Schellink wrote:
>>>> For a start I think the following should be converted:
>>>>
>>>> introduction.html
>>>> why-click.html
>>>> pages.html
>>>> controls.html
>>>> configuration.html
>>>> best-practices.html
>>>>
>>>> Best to grab the latest version from trunk[2]:
>>>>
>>>> Btw I forgot to include the actual Docbook in click-docs.zip earlier, but
>>>> its available now. Just download click-docs.zip again [3].
>>>>
>>>> kind regards
>>>>
>>>> bob
>>>>
>>>> [1]: http://velocity.apache.org/docbook/
>>>> [2]:
>>>> http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/docs/
>>>> [3]: http://people.apache.org/~sabob/test/click-docs.zip
>>>>
>>>
>
Re: New docs format
Posted by "Gilberto C. Andrade" <gi...@gmail.com>.
I've found this one:
https://svn.apache.org/repos/asf/incubator/click/trunk
But with erro:
Error validating server certificate for https://svn.apache.org:443:
- Unknown certificate issuer
Fingerprint: cc:54:a4:a9:ec:3a:9b:1c:23:ac:2d:57:c6:96:9f:5f:4a:1d:2d:86
Distinguished name: 07969287,
http://certificates.godaddy.com/repository, GoDaddy.com, Inc.,
Scottsdale, Arizona, US
Can I accept this certificated?
Gilberto
2009/1/19 Gilberto C. Andrade <gi...@gmail.com>:
> I'm looking for svn click url, but without success! The docs only
> mention this one:http://svn.apache.org/viewvc/incubator/click/trunk.
>
> Any tip?
>
> Gilberto
>
> 2009/1/18 Bob Schellink <sa...@gmail.com>:
>> I've checked in the new Click Docs project under tools/docbook:
>>
>> http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/
>>
>> There is also a README.txt which provides some info on how to setup and
>> build the project.
>>
>> Once the conversion is done, we'll move the Docbook docs into the Click
>> distribution under 'documentation/docs/user-guide'. The new docs will most
>> likely only be included in 2.1.0.
>>
>> @Gilberto, the easiest way to contribute docs would be to create patches and
>> upload them to the JIRA. We should also communicate to this list which
>> section is being worked on. For example if you are busy converting
>> 'pages.html' just post a message here, otherwise we might end up duplicating
>> effort. Unfortunately our Apache JIRA is not available yet so we will have
>> to wait a little while longer before we can start the conversion process.
>>
>> If you have any questions don't hesitate to ask.
>>
>> kind regards
>>
>> bob
>>
>>
>> Bob Schellink wrote:
>>>
>>> For a start I think the following should be converted:
>>>
>>> introduction.html
>>> why-click.html
>>> pages.html
>>> controls.html
>>> configuration.html
>>> best-practices.html
>>>
>>> Best to grab the latest version from trunk[2]:
>>>
>>> Btw I forgot to include the actual Docbook in click-docs.zip earlier, but
>>> its available now. Just download click-docs.zip again [3].
>>>
>>> kind regards
>>>
>>> bob
>>>
>>> [1]: http://velocity.apache.org/docbook/
>>> [2]:
>>> http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/docs/
>>> [3]: http://people.apache.org/~sabob/test/click-docs.zip
>>>
>>
>>
>
Re: New docs format
Posted by "Gilberto C. Andrade" <gi...@gmail.com>.
I'm looking for svn click url, but without success! The docs only
mention this one:http://svn.apache.org/viewvc/incubator/click/trunk.
Any tip?
Gilberto
2009/1/18 Bob Schellink <sa...@gmail.com>:
> I've checked in the new Click Docs project under tools/docbook:
>
> http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/
>
> There is also a README.txt which provides some info on how to setup and
> build the project.
>
> Once the conversion is done, we'll move the Docbook docs into the Click
> distribution under 'documentation/docs/user-guide'. The new docs will most
> likely only be included in 2.1.0.
>
> @Gilberto, the easiest way to contribute docs would be to create patches and
> upload them to the JIRA. We should also communicate to this list which
> section is being worked on. For example if you are busy converting
> 'pages.html' just post a message here, otherwise we might end up duplicating
> effort. Unfortunately our Apache JIRA is not available yet so we will have
> to wait a little while longer before we can start the conversion process.
>
> If you have any questions don't hesitate to ask.
>
> kind regards
>
> bob
>
>
> Bob Schellink wrote:
>>
>> For a start I think the following should be converted:
>>
>> introduction.html
>> why-click.html
>> pages.html
>> controls.html
>> configuration.html
>> best-practices.html
>>
>> Best to grab the latest version from trunk[2]:
>>
>> Btw I forgot to include the actual Docbook in click-docs.zip earlier, but
>> its available now. Just download click-docs.zip again [3].
>>
>> kind regards
>>
>> bob
>>
>> [1]: http://velocity.apache.org/docbook/
>> [2]:
>> http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/docs/
>> [3]: http://people.apache.org/~sabob/test/click-docs.zip
>>
>
>
Re: New docs format
Posted by Bob Schellink <sa...@gmail.com>.
I've checked in the new Click Docs project under tools/docbook:
http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/
There is also a README.txt which provides some info on how to setup
and build the project.
Once the conversion is done, we'll move the Docbook docs into the
Click distribution under 'documentation/docs/user-guide'. The new docs
will most likely only be included in 2.1.0.
@Gilberto, the easiest way to contribute docs would be to create
patches and upload them to the JIRA. We should also communicate to
this list which section is being worked on. For example if you are
busy converting 'pages.html' just post a message here, otherwise we
might end up duplicating effort. Unfortunately our Apache JIRA is not
available yet so we will have to wait a little while longer before we
can start the conversion process.
If you have any questions don't hesitate to ask.
kind regards
bob
Bob Schellink wrote:
>
> For a start I think the following should be converted:
>
> introduction.html
> why-click.html
> pages.html
> controls.html
> configuration.html
> best-practices.html
>
> Best to grab the latest version from trunk[2]:
>
> Btw I forgot to include the actual Docbook in click-docs.zip earlier,
> but its available now. Just download click-docs.zip again [3].
>
> kind regards
>
> bob
>
> [1]: http://velocity.apache.org/docbook/
> [2]:
> http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/docs/
>
> [3]: http://people.apache.org/~sabob/test/click-docs.zip
>
Re: New docs format
Posted by Bob Schellink <sa...@gmail.com>.
Malcolm Edgar wrote:
> Yes the code examples in the PDF.
OK its fixed. One area where the PDF generation isn't ideal yet is
page breaking. I've upgraded to FOP 0.95 which supports "soft breaks".
However with soft breaks one still need to add hints in the markup
where "breaking" should occur.
Some info on this: http://www.sagehill.net/docbookxsl/PageBreaking.html
kind regards
bob
Re: New docs format
Posted by Malcolm Edgar <ma...@gmail.com>.
Yes the code examples in the PDF.
regards Malcolm
On Sat, Jan 17, 2009 at 9:27 AM, Bob Schellink <sa...@gmail.com> wrote:
> Malcolm Edgar wrote:
>>
>> One minor recommendation would be to drop the code example font size a
>> point or two to prevent line wrapping the examples.
>
>
> You mean the PDF? I'll have a look.
>
Re: New docs format
Posted by Bob Schellink <sa...@gmail.com>.
Malcolm Edgar wrote:
> One minor recommendation would be to drop the code example font size a
> point or two to prevent line wrapping the examples.
You mean the PDF? I'll have a look.
Re: New docs format
Posted by Malcolm Edgar <ma...@gmail.com>.
Hi Bob,
this looks very good.
One minor recommendation would be to drop the code example font size a
point or two to prevent line wrapping the examples.
regards Malcolm Edgar
On Sat, Jan 17, 2009 at 8:21 AM, Bob Schellink <sa...@gmail.com> wrote:
>
>> Yes, I'm reading it right now (image1.png). Did you already use that
>> editor (xmlmind: http://www.xmlmind.com/xmleditor/ )?
>> It looks very good!
>>
>
> Nods did use it initially but since I'm not familiar with Docbook I prefer
> to edit it directly until
> have more experience :)
>
Re: New docs format
Posted by Bob Schellink <sa...@gmail.com>.
> Yes, I'm reading it right now (image1.png). Did you already use that
> editor (xmlmind: http://www.xmlmind.com/xmleditor/ )?
> It looks very good!
>
Nods did use it initially but since I'm not familiar with Docbook I
prefer to edit it directly until
have more experience :)
Re: New docs format
Posted by "Gilberto C. Andrade" <gi...@gmail.com>.
2009/1/16 Bob Schellink <sa...@gmail.com>:
> Hi Gilberto,
>
>
> Gilberto C. Andrade wrote:
>>
>> Very good!
>> Is there anything I can help?
>
>
> That would be much appreciated. I still need to setup instructions on
> changes I made to Velocity Docbook[1]. In the meantime you can download the
> Velocity Docbook framework and familiarize yourself with it.
Ok, I will!
> For a start I think the following should be converted:
>
> introduction.html
> why-click.html
> pages.html
> controls.html
> configuration.html
> best-practices.html
>
> Best to grab the latest version from trunk[2]:
>
> Btw I forgot to include the actual Docbook in click-docs.zip earlier, but
> its available now. Just download click-docs.zip again [3].
>
Yes, I'm reading it right now (image1.png). Did you already use that
editor (xmlmind: http://www.xmlmind.com/xmleditor/ )?
It looks very good!
Gilberto
> kind regards
>
> bob
>
> [1]: http://velocity.apache.org/docbook/
> [2]:
> http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/docs/
> [3]: http://people.apache.org/~sabob/test/click-docs.zip
>
Re: New docs format
Posted by Bob Schellink <sa...@gmail.com>.
Hi Gilberto,
Gilberto C. Andrade wrote:
> Very good!
> Is there anything I can help?
That would be much appreciated. I still need to setup instructions on
changes I made to Velocity Docbook[1]. In the meantime you can
download the Velocity Docbook framework and familiarize yourself with it.
For a start I think the following should be converted:
introduction.html
why-click.html
pages.html
controls.html
configuration.html
best-practices.html
Best to grab the latest version from trunk[2]:
Btw I forgot to include the actual Docbook in click-docs.zip earlier,
but its available now. Just download click-docs.zip again [3].
kind regards
bob
[1]: http://velocity.apache.org/docbook/
[2]:
http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/docs/
[3]: http://people.apache.org/~sabob/test/click-docs.zip
Re: New docs format
Posted by "Gilberto C. Andrade" <gi...@gmail.com>.
Very good!
Is there anything I can help? I don't have a good java experience, but
I think documentation area is a way to start helping!
Gilberto
Analista de Sistemas/DBA
www.secad.to.gov.br
www.jroller.com/gilbertoca
2009/1/16 Bob Schellink <sa...@gmail.com>:
> Hi all,
>
> In the past we've had a discussions about porting the documentation to
> Docbook. This would allow us to generate
> documentation in both Html and PDF format and provide a single document
> which is easy to search.
>
> I've converted the Introduction section to Docbook and uploaded the result
> here:
>
> http://people.apache.org/~sabob/test/click-docs.zip
>
> All feedback is appreciated.
>
> kind regards
>
> bob
>
>
Re: New docs format
Posted by Ricardo Lecheta <rl...@gmail.com>.
Hi bob,
looks very nice, it will be very useful
regards
On Fri, Jan 16, 2009 at 5:17 PM, Bob Schellink <sa...@gmail.com> wrote:
> Hi all,
>
> In the past we've had a discussions about porting the documentation to
> Docbook. This would allow us to generate
> documentation in both Html and PDF format and provide a single document
> which is easy to search.
>
> I've converted the Introduction section to Docbook and uploaded the result
> here:
>
> http://people.apache.org/~sabob/test/click-docs.zip<http://people.apache.org/%7Esabob/test/click-docs.zip>
>
> All feedback is appreciated.
>
> kind regards
>
> bob
>
>
--
Ricardo Lecheta
Re: New docs format
Posted by Bob Schellink <sa...@gmail.com>.
Andrus Adamchik wrote:
> Without looking at what it takes to maintain the docbook sources,
I took a cue from Ted Husted and wrote most of it by hand. Once you
get going it doesn't seem much harder than writing HTML.
Also since Docbook is new to me I'm still under influence of the
Hawthorne effect[1], so at this stage its all fun seeing the nice
looking PDF and HTML generated. I'm sure once the novelty wears off
you'll hear a different story :)
kind regards
bob
[1]: http://en.wikipedia.org/wiki/Hawthorne_effect
>
> Andrus
>
>
> On Jan 16, 2009, at 9:17 PM, Bob Schellink wrote:
>> Hi all,
>>
>> In the past we've had a discussions about porting the documentation to
>> Docbook. This would allow us to generate
>> documentation in both Html and PDF format and provide a single
>> document which is easy to search.
>>
>> I've converted the Introduction section to Docbook and uploaded the
>> result here:
>>
>> http://people.apache.org/~sabob/test/click-docs.zip
>>
>> All feedback is appreciated.
>>
>> kind regards
>>
>> bob
>>
>>
>
>
Re: New docs format
Posted by Andrus Adamchik <an...@objectstyle.org>.
Without looking at what it takes to maintain the docbook sources, I'd
say this is a good idea. At times I regret we didn't do it for Cayenne.
Andrus
On Jan 16, 2009, at 9:17 PM, Bob Schellink wrote:
> Hi all,
>
> In the past we've had a discussions about porting the documentation
> to Docbook. This would allow us to generate
> documentation in both Html and PDF format and provide a single
> document which is easy to search.
>
> I've converted the Introduction section to Docbook and uploaded the
> result here:
>
> http://people.apache.org/~sabob/test/click-docs.zip
>
> All feedback is appreciated.
>
> kind regards
>
> bob
>
>