myfaces-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Sean Schofield" <sean.schofi...@gmail.com>
Subject Re: APT documentation format
Date Thu, 02 Mar 2006 18:19:44 GMT
APT is nice and simple but I agree its limited.  I was thinking we
should switch back to xdoc where it makes sense.  It might be nice to
have a "download box" on the rhs of the page like like the maven home
page has.

Sean

On 3/2/06, Mike Kienenberger <mkienenb@gmail.com> wrote:
> Hey James,
>
> I do appreciate your effort you've put into this, and it's not any
> reflection on your work.
>
> I also think the APT format is going to be limited, whereas an XML
> format is in theory going to allow us to do anything that the
> underlying media will support (in this case, html).
>
> Also, I'm not sure what process you are using to convert these
> documents, but it seems like an XSLT would be the way to do it rather
> than doing it by hand.   Then you could tweak anything needing
> customization afterward.    This assumes that we are going to continue
> with the APT format.
>
> On 3/2/06, James Holmes <james@jamesholmes.com> wrote:
> > I'm curious about this too after having spent the time to convert
> > 10 - 15 pages. The APT format is very limited. For example, I don't
> > know of a way to insert images into a table. I'm sure there are a
> > million other examples like this.
> >
> > James
> >
> > On Thu Mar  2  9:39 , "Mike Kienenberger"  sent:
> >
> > >Has anyone else looked at the apt format?   It's more like a wiki
> > >markup than xml.
> > >
> > >The xdocs format is transformable, but the apt format isn't.   We can
> > >easily convert to apt, but not the other way around.
> > >
> > >Seems like we'd lose a lot of work (or be creating a lot of work) the
> > >next time we switch documentation systems.
> > >
> > >Is this really the way we want to go with our documentation?  Do we
> > >really need to be learning and using Yet Another Text Processing
> > >Language?
> > >
> > >-Mike
> > >
> > >On 2/16/06, James Holmes james@jamesholmes.com> wrote:
> > >> Thanks for the feedback Sean. From reading everyone else's feedback too,
I'm
> > >> thinking it's best to just convert what already exists in xdoc format to
APT
> > >> format initially. Once that's done, we can address what the desired content
> > >> of the pages should be and make the requisite changes.
> > >>
> > >> In the interest of cutting down on the # of JIRA tickets, I will attach
> > >> multiple converted files to each ticket. I'm working on this in my spare
> > >> time so it will be a trickle of files.
> > >>
> > >> James
> > >>
> > >> -----Original Message-----
> > >> From: Sean Schofield [sean.schofield@gmail.com','','','')">sean.schofield@gmail.com]
> > >> Sent: Wednesday, February 15, 2006 10:33 AM
> > >> To: MyFaces Development
> > >> Subject: Tomahawk Documentation --> (Was ADF Faces)
> > >>
> > >> Sorry.  Meant to post this to the list.
> > >>
> > >> Sean
> > >>
> > >> ---------- Forwarded message ----------
> > >> From: Sean Schofield sean.schofield@gmail.com>
> > >> Date: Feb 15, 2006 9:04 AM
> > >> Subject: Re: ADF Faces
> > >> To: James Holmes james@jamesholmes.com>
> > >>
> > >>
> > >> James,
> > >>
> > >> Thanks for the offer.  JIRA tickets sound good.  The APT format sounds
> > >> great!  Try to submit your patches as large chunks so we can update a
> > >> bunch at once.  Every once and a while you can ping the dev list if
> > >> you find they're not getting applied.
> > >>
> > >> I have a few other ideas about the revised docs.  I'm not sure syntax
> > >> and usage are that helpful.  We now have a pretty good subsistute for
> > >> syntax in the form of the TLD docs.  Maybe we could have a "See TLD
> > >> Documentation" under the syntax section for each component? (ex.
> > >> http://myfaces.apache.org/tomahawk/tlddoc/index.html)
> > >>
> > >> My thinking is that instructions section highlights some of the key
> > >> aspects of the component.  Some of the components are pretty trivial.
> > >> Others are more complicated (like Tree2.)
> > >>
> > >> Finally, an optional FAQ would be nice.  For instance, there are a lot
> > >> of tree2 FAQ I would like to add there eventually.
> > >>
> > >> Maybe you should start another thread on tomahawk docs so people can
> > >> weigh in on this?  Everyone could take a look at a new sample doc you
> > >> come up with before you do them all?
> > >> Just an idea ...
> > >>
> > >> Looking forward to seeing your stuff!
> > >>
> > >> Sean
> > >>
> > >>
> > >> On 2/14/06, James Holmes james@jamesholmes.com> wrote:
> > >> > Excellent. I'm going to get started by converting the Tomahawk docs
to APT
> > >> > format. After that I'd like to go through and fill in the gaps in
those
> > >> docs
> > >> > as well as clean up some of the "broken" English there.
> > >> >
> > >> > I guess for now I will open JIRA tickets with files attached. Let
me know
> > >> if
> > >> > you want me to submit the APT files a different way.
> > >> >
> > >> > James
> > >> >
> > >> > -----Original Message-----
> > >> > From: Sean Schofield [sean.schofield@gmail.com','','','')">sean.schofield@gmail.com]
> > >> > Sent: Monday, February 13, 2006 6:08 PM
> > >> > To: james@jamesholmes.com
> > >> > Subject: Re: ADF Faces
> > >> >
> > >> > James,
> > >> >
> > >> > We'd love to have your help on the project.  I know your documentation
> > >> > skills well b/c I still sometimes use your site as a quick JSF
> > >> > reference.  Since you are already on the Struts team you are familiar
> > >> > with the process of earning karma.  Once someone has a demonstrated
> > >> > sufficient interest in MyFaces through the normal meritocracy process
> > >> > they will be invited to join.
> > >> >
> > >> > In the past we have fast-tracked a few committers from other projects
> > >> > and I see no reason why we couldn't do the same for you.  Because
you
> > >> > have already demonstrated a committment to open source on another
> > >> > project this will work in your favor.
> > >> >
> > >> > In the meantime please feel free to jump right in.  We'd love to have
> > >> > someone with your JSF expertise join the team.  Bug fixes and
> > >> > documentation are always welcome.  The PMC will feel more inclined
to
> > >> > vote a new committer the more of this they see.
> > >> >
> > >> > Welcome to the community!
> > >> >
> > >> > Sean
> > >> >
> > >> > On 2/13/06, James Holmes james@jamesholmes.com> wrote:
> > >> > > It looks like you're right. I was trying to dig up this very
same info
> > >> on
> > >> > the ASF
> > >> > > site. Well, it was worth a shot...
> > >> > >
> > >> > > I just finished writing a 100 page chapter on MyFaces for my
upcoming
> > >> JSF:
> > >> > The
> > >> > > Complete Reference book. I'm looking to get involved in the Myfaces
> > >> > project and
> > >> > > would ideally like to become a committer. Specifically I'm interested
in
> > >> > working to
> > >> > > clean up alot of the docs and help with the Tomahawk stuff. I
found
> > >> there
> > >> > to be a
> > >> > > lot of inconsistency in the docs while writing the MyFaces chapter.
Let
> > >> me
> > >> > know
> > >> > > what you think.
> > >> > >
> > >> > > James
> > >> > >
> > >> > >
> > >> > > On Mon Feb 13 13:06 , Sean Schofield sean.schofield@gmail.com>
sent:
> > >> > >
> > >> > > >I don't see Ted on the list of members[1] but I believe he
is one
> > >> > > >since I saw him at the board meeting at ApacheCon that I
wandered
> > >> > > >into.
> > >> > > >
> > >> > > >If this weren't an issue Martin Marinshek or any of the other
PMC's on
> > >> > > >this project could qualify.  I believed Martin had volunteered
(on the
> > >> > > >PMC list) but I seemed to recall him beeing told he could
not serve
> > >> > > >since he was not a member.
> > >> > > >
> > >> > > >From the ASF website[2]:
> > >> > > >
> > >> > > >The incubator filters projects on the basis of the likeliness
of them
> > >> > > >becoming successful meritocratic communities. The basic requirements
> > >> > > >for incubation are:
> > >> > > >
> > >> > > >    * a working codebase -- over the years and after several
failures,
> > >> > > >the foundation came to understand that without an initial
working
> > >> > > >codebase, it is generally hard to bootstrap a community.
This is
> > >> > > >because merit is not well recognized by developers without
a working
> > >> > > >codebase. Also, the friction that is developed during the
initial
> > >> > > >design stage is likely to fragment the community.
> > >> > > >    * the intention to donate copyright of the software and
the
> > >> > > >intellectual property that it may contain to the foundation
-- this
> > >> > > >allows the foundation to obtain an irrevocable and permanent
right to
> > >> > > >redistribute and work on the code, without fearing lock-in
for itself
> > >> > > >or for its users.
> > >> > > >    * a sponsoring ASF member or officer -- this person will
act as
> > >> > > >the main mentor, giving directions to the project, helping
out in the
> > >> > > >day-to-day details and keeping contact with the incubator
PMC.
> > >> > > >
> > >> > > >Sean
> > >> > > >
> > >> > > >[1] http://www.apache.org/foundation/members.html
> > >> > > >[2] http://www.apache.org/foundation/how-it-works.html#asf-members
> > >> > > >
> > >> > > >
> > >> > > >
> > >> > > >
> > >> > > >On 2/13/06, James Holmes james@jamesholmes.com> wrote:
> > >> > > >> I don't believe Ted is on the board of the ASF. Again
I could be
> > >> wrong,
> > >> > but I
> > >> > > think
> > >> > > >> I am eligible to do this for you all. You can confirm
with Ted. He
> > >> will
> > >> > know for
> > >> > > >> sure.
> > >> > > >>
> > >> > > >> James
> > >> > > >>
> > >> > > >> On Mon Feb 13 12:51 , Sean Schofield sean.schofield@gmail.com>
sent:
> > >> > > >>
> > >> > > >> >No I mean a board member of the ASF.  I am no expert
on the ASF
> > >> rules
> > >> > though.
> > >> > > >> >
> > >> > > >> >Sean
> > >> > > >> >
> > >> > > >> >On 2/13/06, James Holmes james@jamesholmes.com>
wrote:
> > >> > > >> >> Sean,
> > >> > > >> >>
> > >> > > >> >> Do you mean a member of the Jakarta PMC? I
believe I quality, but
> > >> > stand to be
> > >> > > be
> > >> > > >> >> corrected.
> > >> > > >> >>
> > >> > > >> >> James
> > >> > > >> >>
> > >> > > >> >> On Mon Feb 13 12:33 , Sean Schofield sean.schofield@gmail.com>
> > >> sent:
> > >> > > >> >>
> > >> > > >> >> >James,
> > >> > > >> >> >
> > >> > > >> >> >I believe you have to be an ASF Member
to be a mentor.  Still,
> > >> > thanks
> > >> > > >> >> >for volunteering to help out.  We can use
some more volunteers in
> > >> > this
> > >> > > >> >> >area.
> > >> > > >> >> >
> > >> > > >> >> >Sean
> > >> > > >> >> >
> > >> > > >> >> >On 2/13/06, James Holmes james@jamesholmes.com>
wrote:
> > >> > > >> >> >> Hi Jonas,
> > >> > > >> >> >>
> > >> > > >> >> >> I'm a committer on the Struts project
as well as a PMC member.
> > >> > I'd
> > >> > > >> >> >> like to help you guys by being your
mentor. Let me know what
> > >> the
> > >> > > >> >> >> next steps are.
> > >> > > >> >> >>
> > >> > > >> >> >> James
> > >> > > >> >> >>
> > >> > > >> >> >> On Mon Feb 13 12:13 , Jonas Jacobi
 sent:
> > >> > > >> >> >> >
> > >> > > >> >> >> >Hi Martin et all,
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >Ted told us that he will not have
time helping out as a mentor
> > >> > for the
> > >> > > >> >> >> >ADF Faces donation, since he is
busy bringing Webwork into
> > >> > Struts. Omar
> > >> > > >> >> >> >and I are very actively working
on getting another mentor, but
> > >> > if
> > >> > > >> >> >> >anyone knows someone that can
be interested in mentoring this
> > >> > project
> > >> > > >> >> >> >please let us know.
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >Currently three people have voted
to progress with the
> > >> proposal
> > >> > and
> > >> > > >> >> >> >send it off to the Incubator as
is. Of course I'm +1, but I
> > >> > don't know
> > >> > > >> >> >> >how many votes are needed to send
the proposal to the
> > >> Incubator
> > >> > PMCs.
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >Thanks,
> > >> > > >> >> >> >
> > >> > > >> >> >> >Jonas
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >Martin Marinschek wrote:
> > >> > > >> >> >> >
> > >> > > >> >> >> >  Hi Ted,
> > >> > > >> >> >> >
> > >> > > >> >> >> >the ADF faces proposal is getting
close to be posted to
> > >> > incubator - I
> > >> > > >> >> >> >wanted to ask if you had time
now for being a mentor or if
> > >> that
> > >> > > >> >> >> >wouldn't fit your timeframe (as
far as I remember, you said
> > >> you
> > >> > > >> >> >> >wouldn't have time until end of
January)?
> > >> > > >> >> >> >
> > >> > > >> >> >> >If not, can you suggest anyone
we should try to get in touch
> > >> > with?
> > >> > > >> >> >> >
> > >> > > >> >> >> >regards,
> > >> > > >> >> >> >
> > >> > > >> >> >> >Martin
> > >> > > >> >> >> >
> > >> > > >> >> >> >--
> > >> > > >> >> >> >
> > >> > > >> >> >> >http://www.irian.at
> > >> > > >> >> >> >
> > >> > > >> >> >> >Your JSF powerhouse -
> > >> > > >> >> >> >JSF Consulting, Development and
> > >> > > >> >> >> >Courses in English and German
> > >> > > >> >> >> >
> > >> > > >> >> >> >Professional Support for Apache
MyFaces
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >--
> > >> > > >> >> >> >
> > >> > > >> >> >> >Jonas Jacobi
> > >> > > >> >> >> >
> > >> > > >> >> >> >Author: Pro
> > >> > > >> >> >> >JSF and Ajax: Building Rich Internet
Components
> > >> > > >> >> >> >
> > >> > > >> >> >> >Blog:
> > >> > > >> >> >> >http://www.orablogs.com/jjacobi
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >> >
> > >> > > >> >> >>
> > >> > > >> >> >>
> > >> > > >> >> >>
> > >> > > >> >>
> > >> > > >> >>
> > >> > > >> >>
> > >> > > >>
> > >> > > >>
> > >> > > >>
> > >> > >
> > >> > >
> > >> > >
> > >> >
> > >> >
> > >>
> > >>
> >
> >
> >
>

Mime
View raw message