You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by Howard Lewis Ship <hl...@gmail.com> on 2005/08/03 20:20:16 UTC
[IMPORTANT] Community effort to supply documentation
Over the weekend I added a LARGE number of JIRA Issues, describing the
gaps in the component reference (for the framework, and for the
contrib library).
Thiis is an EXCELLENT chance for the wider Tapestry developer
community to contribute to the project!
Converting from the HTML format to the Forrest XML format is not very
difficult and there's plenty of examples already available. Better
yet, you can be effective without needing commit privs ... because
it's very reasonable to just attach the final file to the JIRA issue.
Here's how I see the process:
- Developers (not committers) select a Component Reference page to work on
- Add a comment to the JIRA issue (i.e., take ownership)
- Create the documentation (Forrest XML) and attach it to the JIRA issue
- A committer applies the file (or patch) and closes the issue
To build the documentation, you need to do a bit of setup, documented
on the Wiki:
http://wiki.apache.org/jakarta-tapestry/BuildingTapestry
Pay attention to the notes at the end, about the live-site target. Very handy.
Thanks in advance to everyone who pitches in!
--
Howard M. Lewis Ship
Independent J2EE / Open-Source Java Consultant
Creator, Jakarta Tapestry
Creator, Jakarta HiveMind
Professional Tapestry training, mentoring, support
and project work. http://howardlewisship.com
---------------------------------------------------------------------
To unsubscribe, e-mail: tapestry-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tapestry-dev-help@jakarta.apache.org
Re: [IMPORTANT] Community effort to supply documentation
Posted by Norbert Sándor <de...@erinors.com>.
I found them.
I give this generating a try.
BR,
Norbi
----- Original Message -----
From: "Howard Lewis Ship" <hl...@gmail.com>
To: "Tapestry development" <ta...@jakarta.apache.org>
Sent: Saturday, August 06, 2005 4:43 PM
Subject: Re: [IMPORTANT] Community effort to supply documentation
As appealing as that is, there's also examples, hyperlinks,
cross-refererences to other classes and components, etc.
On 8/5/05, Norbert Sándor <de...@erinors.com> wrote:
> What about generating the XMLs based on the embedded documentation in
> components? (Maybe with some external documentation like examples.)
>
> Today I finished the integrating of TapDoc and Tapestry's parsing
> features,
> so it works even with annotations as well. (Of course there are several
> enhancements to do yet.)
> It would be possible to create an XSL file (and do some configuration)
> which
> generates the required XMLs.
> (I don't know how Forrest works and I haven't found any component XML on
> CVS, it's just an idea.)
>
> What do you think?
>
> BR,
> Norbi
>
> ----- Original Message -----
> From: "Howard Lewis Ship" <hl...@gmail.com>
> To: "Tapestry development" <ta...@jakarta.apache.org>
> Sent: Wednesday, August 03, 2005 8:20 PM
> Subject: [IMPORTANT] Community effort to supply documentation
>
>
> Over the weekend I added a LARGE number of JIRA Issues, describing the
> gaps in the component reference (for the framework, and for the
> contrib library).
>
> Thiis is an EXCELLENT chance for the wider Tapestry developer
> community to contribute to the project!
>
> Converting from the HTML format to the Forrest XML format is not very
> difficult and there's plenty of examples already available. Better
> yet, you can be effective without needing commit privs ... because
> it's very reasonable to just attach the final file to the JIRA issue.
>
> Here's how I see the process:
> - Developers (not committers) select a Component Reference page to work on
> - Add a comment to the JIRA issue (i.e., take ownership)
> - Create the documentation (Forrest XML) and attach it to the JIRA issue
> - A committer applies the file (or patch) and closes the issue
>
>
> To build the documentation, you need to do a bit of setup, documented
> on the Wiki:
>
> http://wiki.apache.org/jakarta-tapestry/BuildingTapestry
>
> Pay attention to the notes at the end, about the live-site target. Very
> handy.
>
> Thanks in advance to everyone who pitches in!
>
> --
> Howard M. Lewis Ship
> Independent J2EE / Open-Source Java Consultant
> Creator, Jakarta Tapestry
> Creator, Jakarta HiveMind
>
> Professional Tapestry training, mentoring, support
> and project work. http://howardlewisship.com
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tapestry-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: tapestry-dev-help@jakarta.apache.org
>
>
>
>
>
>
--
Howard M. Lewis Ship
Independent J2EE / Open-Source Java Consultant
Creator, Jakarta Tapestry
Creator, Jakarta HiveMind
Professional Tapestry training, mentoring, support
and project work. http://howardlewisship.com
---------------------------------------------------------------------
To unsubscribe, e-mail: tapestry-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tapestry-dev-help@jakarta.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: tapestry-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tapestry-dev-help@jakarta.apache.org
Re: [IMPORTANT] Community effort to supply documentation
Posted by Howard Lewis Ship <hl...@gmail.com>.
This looks like a great head start.
On 8/6/05, Norbert Sándor <de...@erinors.com> wrote:
> I have successfully used TapDoc to generate skeleton Forrest XML files for
> the Framework component reference. I attached the output files.
> You are right that it is not trivial to automatically generate documentation
> because of links, etc.
> But it would be great :)
>
> The current state of TapDoc helps also to build the docs more easily:
> - Component and parameter descriptions should be copied to the jwc files
> - TapDoc can be used to generate skeleton Forrest XML files
> - Custom parts like "see also" and examples should be manually copied to the
> XMLs currently. But it would not be difficult to merge the generated XMLs
> with static hand-written ones (eg. example sections), so copy-paste could be
> eliminated.
>
> I would help (if you accept it) in:
> - copying documentation from current XMLs to component specifications
> - generating Forrest XML skeletons
>
> BR,
> Norbi
>
> ----- Original Message -----
> From: "Howard Lewis Ship" <hl...@gmail.com>
> To: "Tapestry development" <ta...@jakarta.apache.org>
> Sent: Saturday, August 06, 2005 4:43 PM
> Subject: Re: [IMPORTANT] Community effort to supply documentation
>
>
> As appealing as that is, there's also examples, hyperlinks,
> cross-refererences to other classes and components, etc.
>
>
>
--
Howard M. Lewis Ship
Independent J2EE / Open-Source Java Consultant
Creator, Jakarta Tapestry
Creator, Jakarta HiveMind
Professional Tapestry training, mentoring, support
and project work. http://howardlewisship.com
---------------------------------------------------------------------
To unsubscribe, e-mail: tapestry-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tapestry-dev-help@jakarta.apache.org
Re: [IMPORTANT] Community effort to supply documentation
Posted by Howard Lewis Ship <hl...@gmail.com>.
As appealing as that is, there's also examples, hyperlinks,
cross-refererences to other classes and components, etc.
On 8/5/05, Norbert Sándor <de...@erinors.com> wrote:
> What about generating the XMLs based on the embedded documentation in
> components? (Maybe with some external documentation like examples.)
>
> Today I finished the integrating of TapDoc and Tapestry's parsing features,
> so it works even with annotations as well. (Of course there are several
> enhancements to do yet.)
> It would be possible to create an XSL file (and do some configuration) which
> generates the required XMLs.
> (I don't know how Forrest works and I haven't found any component XML on
> CVS, it's just an idea.)
>
> What do you think?
>
> BR,
> Norbi
>
> ----- Original Message -----
> From: "Howard Lewis Ship" <hl...@gmail.com>
> To: "Tapestry development" <ta...@jakarta.apache.org>
> Sent: Wednesday, August 03, 2005 8:20 PM
> Subject: [IMPORTANT] Community effort to supply documentation
>
>
> Over the weekend I added a LARGE number of JIRA Issues, describing the
> gaps in the component reference (for the framework, and for the
> contrib library).
>
> Thiis is an EXCELLENT chance for the wider Tapestry developer
> community to contribute to the project!
>
> Converting from the HTML format to the Forrest XML format is not very
> difficult and there's plenty of examples already available. Better
> yet, you can be effective without needing commit privs ... because
> it's very reasonable to just attach the final file to the JIRA issue.
>
> Here's how I see the process:
> - Developers (not committers) select a Component Reference page to work on
> - Add a comment to the JIRA issue (i.e., take ownership)
> - Create the documentation (Forrest XML) and attach it to the JIRA issue
> - A committer applies the file (or patch) and closes the issue
>
>
> To build the documentation, you need to do a bit of setup, documented
> on the Wiki:
>
> http://wiki.apache.org/jakarta-tapestry/BuildingTapestry
>
> Pay attention to the notes at the end, about the live-site target. Very
> handy.
>
> Thanks in advance to everyone who pitches in!
>
> --
> Howard M. Lewis Ship
> Independent J2EE / Open-Source Java Consultant
> Creator, Jakarta Tapestry
> Creator, Jakarta HiveMind
>
> Professional Tapestry training, mentoring, support
> and project work. http://howardlewisship.com
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tapestry-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: tapestry-dev-help@jakarta.apache.org
>
>
>
>
>
>
--
Howard M. Lewis Ship
Independent J2EE / Open-Source Java Consultant
Creator, Jakarta Tapestry
Creator, Jakarta HiveMind
Professional Tapestry training, mentoring, support
and project work. http://howardlewisship.com
---------------------------------------------------------------------
To unsubscribe, e-mail: tapestry-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tapestry-dev-help@jakarta.apache.org
Re: [IMPORTANT] Community effort to supply documentation
Posted by Norbert Sándor <de...@erinors.com>.
What about generating the XMLs based on the embedded documentation in
components? (Maybe with some external documentation like examples.)
Today I finished the integrating of TapDoc and Tapestry's parsing features,
so it works even with annotations as well. (Of course there are several
enhancements to do yet.)
It would be possible to create an XSL file (and do some configuration) which
generates the required XMLs.
(I don't know how Forrest works and I haven't found any component XML on
CVS, it's just an idea.)
What do you think?
BR,
Norbi
----- Original Message -----
From: "Howard Lewis Ship" <hl...@gmail.com>
To: "Tapestry development" <ta...@jakarta.apache.org>
Sent: Wednesday, August 03, 2005 8:20 PM
Subject: [IMPORTANT] Community effort to supply documentation
Over the weekend I added a LARGE number of JIRA Issues, describing the
gaps in the component reference (for the framework, and for the
contrib library).
Thiis is an EXCELLENT chance for the wider Tapestry developer
community to contribute to the project!
Converting from the HTML format to the Forrest XML format is not very
difficult and there's plenty of examples already available. Better
yet, you can be effective without needing commit privs ... because
it's very reasonable to just attach the final file to the JIRA issue.
Here's how I see the process:
- Developers (not committers) select a Component Reference page to work on
- Add a comment to the JIRA issue (i.e., take ownership)
- Create the documentation (Forrest XML) and attach it to the JIRA issue
- A committer applies the file (or patch) and closes the issue
To build the documentation, you need to do a bit of setup, documented
on the Wiki:
http://wiki.apache.org/jakarta-tapestry/BuildingTapestry
Pay attention to the notes at the end, about the live-site target. Very
handy.
Thanks in advance to everyone who pitches in!
--
Howard M. Lewis Ship
Independent J2EE / Open-Source Java Consultant
Creator, Jakarta Tapestry
Creator, Jakarta HiveMind
Professional Tapestry training, mentoring, support
and project work. http://howardlewisship.com
---------------------------------------------------------------------
To unsubscribe, e-mail: tapestry-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tapestry-dev-help@jakarta.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: tapestry-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tapestry-dev-help@jakarta.apache.org