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 <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> 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 [EMAIL PROTECTED]> 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 [EMAIL PROTECTED]','','','')">[EMAIL PROTECTED] > > >> 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 [EMAIL PROTECTED]> > > >> Date: Feb 15, 2006 9:04 AM > > >> Subject: Re: ADF Faces > > >> To: James Holmes [EMAIL PROTECTED]> > > >> > > >> > > >> 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 [EMAIL PROTECTED]> 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 [EMAIL PROTECTED]','','','')">[EMAIL PROTECTED] > > >> > Sent: Monday, February 13, 2006 6:08 PM > > >> > To: [EMAIL PROTECTED] > > >> > 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 [EMAIL PROTECTED]> 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 [EMAIL PROTECTED]> 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 [EMAIL PROTECTED]> 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 [EMAIL PROTECTED]> 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 [EMAIL PROTECTED]> 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 [EMAIL PROTECTED]> > > >> 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 [EMAIL PROTECTED]> 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 > > >> > > >> >> >> > > > >> > > >> >> >> > > > >> > > >> >> >> > > > >> > > >> >> >> > > > >> > > >> >> >> > > > >> > > >> >> >> > > > >> > > >> >> >> > > >> > > >> >> >> > > >> > > >> >> >> > > >> > > >> >> > > >> > > >> >> > > >> > > >> >> > > >> > > >> > > >> > > >> > > >> > > >> > > >> > > > > >> > > > > >> > > > > >> > > > >> > > > >> > > >> > > > > > > >
