RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
Craog I have a feeling that whatever is the same will be a lot of piecemeal here and there, excluding of course, web-app documentation. So far yourself, Pier, and Henri are the only three TC developers to post their position on that (re: inter-version relevancy). Pier and I also working together on a separate sub-project, J-T-C. A starting user will first install the servlet-engine and then will try to figure how to link it with its web-server. Should we ask him to switch from one documentation to another ? I thought of another reason for my preference in the shower this morning :-). Consider that I might make a code change that also requires a change to the corresponding docs. If the docs are in the same repository, that can easily be done on the same commit (and it becomes obvious to everyone when a developer makes a change that breaks the documentation, but fails to update it :-). Having a separate docs repository means I need to do two independent check-ins -- it's easy to forget one, and there is no obvious link between them to remind you (for example) to back out the docs change if you back out the code change. If you commit a code change in TC 4.0, you'll only have one doc commit in J-T-D. What's the duplicate effort here ? On the other hand, a separate docs repository has one potential advantage as well: we can grant CVS commit privileges on the docs to people who do not have those privileges on the code repositories. To me, this isn't a big deal -- if we can trust people to get the docs right, we should be able to trust them not to screw up the code -- but it's still there. That's the goal. a redactor will have access only to J-T-D. A tomcat commiter will have access to code docs... * The files that are checked in should only be the XML sources, *not* the generated files. This varies from what Jon set up in jakarta-site2, based on long and drawn out earlier discussions (same issues as those surrounding checking JAR files into CVS :-). Someone will have to setup something that exposes the latest generated documentation on the Jakarta www site. It's being done already for Struts, so I guess that won't be a big problem. It's pretty straightforward. * At least two documentation webapps (developer-oriented and user-oriented) would seem to be appropriate. Having more than two developer as in web or Tomcat? I'm not sure why separating the doc into two packages helps - perhaps I'm missing some obvious benefit trying to think at 7:15am =) Developer in the sense of this sentence is a Tomcat developer. User is the people that just want to download, install, configure, and utilize Tomcat as a servlet container. And a third category is the redactor, someone who write docs to explains users how to install and run TC stuff. He also describe to potentials new developpers Tomcats (3.2/3.3/4.0) architectures and how they could add functionnalities to the main core. That's why Apache HTTPD server was so successfull...
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
On Tue, 10 Jul 2001, GOMEZ Henri wrote: Craog I have a feeling that whatever is the same will be a lot of piecemeal here and there, excluding of course, web-app documentation. So far yourself, Pier, and Henri are the only three TC developers to post their position on that (re: inter-version relevancy). Pier and I also working together on a separate sub-project, J-T-C. A starting user will first install the servlet-engine and then will try to figure how to link it with its web-server. Should we ask him to switch from one documentation to another ? The user doesn't care what repository the docs came from -- they only care that the hyperlinks work correctly :-). In other words, the packaging of the docs in the binary distribution need not have anything to do with the source file organization. I thought of another reason for my preference in the shower this morning :-). Consider that I might make a code change that also requires a change to the corresponding docs. If the docs are in the same repository, that can easily be done on the same commit (and it becomes obvious to everyone when a developer makes a change that breaks the documentation, but fails to update it :-). Having a separate docs repository means I need to do two independent check-ins -- it's easy to forget one, and there is no obvious link between them to remind you (for example) to back out the docs change if you back out the code change. If you commit a code change in TC 4.0, you'll only have one doc commit in J-T-D. What's the duplicate effort here ? Assume a change to class Abc.java and a corresponding change to Abc-doc.html. If they are in the same CVS repository, a single commit does both. Otherwise, you need to remember to do two individual commits (one on each repository). Likewise, when you decide later to back out this change (because it was incorrect or something), you have to remember that there was also a commit on the docs repository. In the same repository, the commit message contains both sets of changes, so you know that you have to back them both out. Craig McClanahan
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:[TomcatDocumentation Redactors To Hire]
On Mon, 9 Jul 2001, Jon Stevens wrote: on 7/7/01 9:33 AM, Craig R. McClanahan [EMAIL PROTECTED] wrote: FWIW, I'm fine with Anakia, XSLT, Cocoon, Stylebook, Docbook, or whatever ... but IF AND ONLY IF the tags for use by the document authors are well documented, and the page generation procedure is amenable to Ant scripting (not a difficult problem in most cases). Jakarta-Site tags are now documented. http://jakarta.apache.org/site/jakarta-site-tags.html Cool. That's exactly what I was looking for. Also, please quit grouping Anakia into Anakia tags need to be documented. It is the Jakarta-Site2 project's tags which need to be documented (and have been). Anakia itself doesn't give a shit what tags you use. :-) That's correct. It's also correct of XSLT :-). -jon Craig
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:[TomcatDocumentation Redactors To Hire]
on 7/7/01 9:33 AM, Craig R. McClanahan [EMAIL PROTECTED] wrote: FWIW, I'm fine with Anakia, XSLT, Cocoon, Stylebook, Docbook, or whatever ... but IF AND ONLY IF the tags for use by the document authors are well documented, and the page generation procedure is amenable to Ant scripting (not a difficult problem in most cases). Jakarta-Site tags are now documented. http://jakarta.apache.org/site/jakarta-site-tags.html Also, please quit grouping Anakia into Anakia tags need to be documented. It is the Jakarta-Site2 project's tags which need to be documented (and have been). Anakia itself doesn't give a shit what tags you use. :-) -jon
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
Developer in the sense of this sentence is a Tomcat developer. User is the people that just want to download, install, configure, and utilize Tomcat as a servlet container. Agree. That's why I suggested that we need to separate Developer Guide from User/Administrator Guide. I believed that the User community is much larger than Developer comunity. Hence, the 1st priority must go into writing the User/Administrator Guide first. I also agreed that we don't really need web application guide. As someone say (Criag ?), all the web application development is almost the same across different containers. What we really need is the documentation about the deployment, which should be placed under User/Administrator Guide. And I also suspect that the Developer Guide would be useful. I don't think we need to document every technical details (like API, function calls, class diagrams), because these will change from time to time. What we really need is some technical notes on the design idea. Of course, if the APIs are stable enough, like RequestIntercepter(3.x) and Filter(4.x) patterns, they need to be properly documented as well. Hence, the Developer Guide serves as effective communication tools among developers. For real hackers who want to know the internals or extend Tomcat, I still believe that source code is the best documentation. I don't have any preference on where the doc should be place, just like what Craig says, it don't bother me much, and just hoping that I don't screw up the code. Punky P.S. Sorry to respond late as I'm 100% off the list since last Friday.
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
On Sat, 7 Jul 2001 [EMAIL PROTECTED] wrote: On Fri, Jul 06, 2001 at 10:06:21PM -0700, Craig R. McClanahan wrote: * Docs should live in the source tree of the project that they are about. Although Henri's suggestion for jakarta-tomcat-docs is noble, what you'll find in practice is that there is very little documentation that is relevant across multiple versions of Tomcat. That remains to be seen. My gut tells me the opposite. I'm thinking connectors, classpath issues (though some details are different with Catalina, a lot are the same), Although the concepts of the issues above are similar, the details are very different. web.xml docs, authentication, These are the same because they are application-related (i.e. portable because of the servlet spec) not Tomcat-related. In principle, anything we write about this should apply to any servlet container. performance-tuning a web app... That's a huge area, and may be somewhat ambitious. But, again, most of this would be portable to any servlet container, not just Tomcat. I'd love to get your input on the outline I just posted if you get around to it -- tell me which sections are definitely different between 3 and 4. Could you repost the most recent version of the proposed outline? My delete key got a little sticky, and I accidentally deleted the most recent version last night. Just for interest's sake, here's the list of user things in Tomcat 4.0 that are new (relative to 3.2), cribbed from my JavaOne talk: * Access logs (web-server style) * CGI support * Configurable realms at Engine, Host, and Context levels, including JNDIRealm. * Container-managed security (DIGEST and CLIENT-CERT modes, plus single sign on support) * Default Context configuration * HTTP/1.1 support in stand-alone mode * JNDI naming context support (including support for configuring env-entry and resource-ref mappings, JDBC connection pooling, and extensible object factories). * Manager web app * MOD_WEBAPP * Request filtering valves (accept/deny based on client hostname or IP address) * Run directly from war file * Server side includes (*.shtml) * User web apps (http://www.mycompany.com/~craigmcc) Now, picture yourself installing Tomcat 3.2 (because it's the current production version). Do you *really* want to wade through the docs on all of the above, which is totally irrelevant to your needs, just because we put the docs for all versions in one file? To say nothing about all the things that were present in 3.2 but are configured differently in 4.0 ... The current situation with the docs on the site for 3.2 and 3.3 illustrate the problem with fragmenting two doc trees that are actually very similar. Nearly everything important about configuring Tomcat is different anyway. The only common stuff is the App Dev Guide. As has been discussed, that probably makes sense in a common docs directory (until you have do decide whether or not to cover both versions of the specs -- servlet 2.2/2.3 and JSP 1.1/1.2 -- in the same docs :-). But, if it's separate, you've also got to figure out how you're going to release it. Any reorganization or new docs or error fixing will need to be propagated back to the 3.2 branch, Why? The code is in maintenance mode -- I don't see a problem with the docs being in maintenance mode as well. Of course, anyone who *wants* to do this is welcome to do so, but I don't see it as a prerequisite. which will be a terror to maintain. I feel the same thing could easily happen with 4.0 vs 4.1 in the near future. Not if we get started with a nice disciplined source directory structure. That's why this discussion is so timely. Not when you remember that the 4.0-4.1 changes won't be a complete rearchitecting (at least to the extent that people listen to me :-), the way that 3.2-3.3 turned out to be. Not when you remember that 4.0 will go into maintenance mode when 4.1 is released, so we can focus energies (both code and docs) on the current version. But 4.1 *will* be different than 4.0. So there will need to be a way to produce the docs for 4.1 *only* -- by that time, users won't care how 4.0 worked, either. IMHO, trying to mix docs for multiple versions in the same document set is a receipie for disaster -- for reasons that I articulated last night, plus the fact that people only care about the version they are installing. It's fine to have comparative features sorts of docs in some separate (common) docs repository, along with the App Dev Guide type stuff that is also common. But that's maybe three-to-five pages worth of stuff -- good, comprehensive docs on something like Tomcat is going to be more in the low hundreds of pages (depending, of course, on how fine-grained we decide to make it), for any given version. * The files that are checked in should only be the XML sources, *not* the generated files. This varies from what Jon set up in jakarta-site2, based on long and drawn
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
On Sat, 7 Jul 2001, Aaron Bannert wrote: On Sat, Jul 07, 2001 at 09:25:46AM -0700, Craig R. McClanahan wrote: Yes, we obviously need pointers in a top-level README on where the docs went. I'm willing to collaborate on these types of docs. On a slight tangent, I'd like to point out that we could use more STATUS and README documents, if only to serve the purpose of a signpost for current and new developers. *Every* CVS module that is a work-in-progress should have some sort of STATUS document, as well as a README describing what the repository contains. The first serves as a road map for any new developers who want to get into the source. The second serves as a roadmap for new builders/testers who want to know what the heck they're looking at. Also, on my list of high level desires, I forgot to include one: * All of the Tomcat documentation should be visible online at the Tomcat web site. which can (at least partially) deal with Alex's how do you set up the VCR issue :-). ( s/Alex/Aaron/ :) Sorry about that ... too many A-list people today :-) That will partially satisfy me, but not everyone has fully-connected high-speed internet access and graphical browsers (at least not while they're trying to get Tomcat working). I'd still like to push for plain text documentation for each of the following: 0) README and STATUS in each of a) jakarta-tomcat-4.0 b) jakarta-regexp c) jakarta-servletapi-4 d) jakarta-tomcat-connectors (* Pier is working on this, I've submitted the beginnings of a README) e) the various TC3.x repositories that I'm less familiar with 1) build instructions for each. Not extensive, just simple bootstrapping instructions, maybe even just in the README. 2) [basic] configuration instructions. Again, not extensive, but enough to get it up. Maybe a recipe that would answer questions like: a) What goes in server.xml? b) How do I start/stop TC? c) What must be already installed in order to run TC? (JDK version, etc...) It definitely makes sense to have enough how to get started stuff in plain text README form to get a newbie going. Hmm, if we can transform XML-HTML, maybe we can just use a different stylesheet (or set of Anakia macros) and transform XML-TXT as well . Who's with me on this? I can submit an outline for each and let the people with more experience fill in the blanks. 2) Why have the docs as a web app? I'm not sure I see the benefits yet, aside from being able to have a pointer to the docs from the ROOT/index page. A couple of reasons: * Because we already do -- and it's quite convenient to be able to look at the docs once you get Tomcat started the first time. The problem today is that we are really overloading the ROOT web app, and it's not particularly well organized. I totally agree that it is convenient, but it may be harder for us to realize the difficulty in getting this beast rolling the first time from our altitude. We want every college student who has ever had any interest in Servlets/JSP running this thing on their home Linux/*BSD/WinXX (*gag*) machine, and they're only going to do that if the barrier to entry is well defined. As a side comment on this topic, Tomcat 4 installation and administration is going to directly benefit from Sun's JavaOne announcement about the Web Services Pack (which will include Tomcat). In particular, my team at Sun is going to put some serious developer hours into these areas, and the vast majority of the resulting code will work just fine for a stand-alone download of Tomcat from Apache as well. By the way, one of the current XML docs (catalina/docs/dev/xdocs/fs-admin-apps.xml) is a proposed set of high level functional requirements for administrative apps for Tomcat 4. Developers interested in this topic are encouraged to read it and suggest improvements. Sun is also increasing the number of folks writing and executing tests of Tomcat 4 features (beyond the issues of spec compliance). In order to do this, the test writers need a description of what correct behavior is -- so one of the things I will personally be working on is functional specs type docs for the various existing features (such as the fs-*.xml files in the same directory as the admin apps doc). That's why I'm quite happy to see a discussion about documentation formats and tools happen now. The net result will be a substantial increase in the amount of useful internals documentation about how Tomcat 4 is put together. -aaron Craig
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
On Mon, 2 Jul 2001, Jon Stevens wrote: on 7/2/01 5:58 PM, Pier P. Fumagalli [EMAIL PROTECTED] wrote: Excellent :) Anakia is a tool written by Jon to translate XML into HTML (correct me if I'm wrong) based on the same language that WebMacro uses... It generates http://jakarta.apache.org/, so, it must be somehow good :) Pier No. It is based on Velocity which is similar but different than WebMacro. In order to use Jakarta-Site2 you don't need to know how to understand the stylesheet though because it is already done for you. All you need to understand is the syntax to use in the XML files. It would sure be nice to have a little HOWTO on what tags (like document and section) Anakia recognizes, and what they do :-). The same, of course, goes for the XSLT stylesheets, including stylebook, that are used in various projects. -jon Craig
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
On Mon, 2 Jul 2001, Rob S. wrote: This seems to be one of the questions that comes up and never gets answered (re: docs, not Jon's behavior ;) I'm not sure what magical solution will get people to read docs. Frankly, I'd just like to get started. Anakia works for Jakarta, Yep, thanks to Jon's hard work setting up jakarta-site2, a large majority of the Jakarta web site is generated using Anakia. it works for Struts Technically, it's not actually *used* by Struts -- Struts uses the Ant style tag, which does an XSLT transformation. However, the XML tags that Anakia (as used in jakarta-site2) understands are very similar to the ones used in the Struts stylesheets -- and that is a very important point. == it'll probably work for Catalina. The important issue is *not* what transformation tool is used. The important issue is on what tags you use in your docs, so that you can use your favorite transformation tool. That's what we should agree on first, because that is the gating factor on actually writing documentation. Committers, [VOTE] on this? +1 on anyone willing to propose *and act on* writing docs, using some reasonable XML format, on all interesting versions of Tomcat. That being said, I do have a couple of thoughts on process -- but they are just my own feelings, not mandates or requirements. * Docs should live in the source tree of the project that they are about. Although Henri's suggestion for jakarta-tomcat-docs is noble, what you'll find in practice is that there is very little documentation that is relevant across multiple versions of Tomcat. * The files that are checked in should only be the XML sources, *not* the generated files. This varies from what Jon set up in jakarta-site2, based on long and drawn out earlier discussions (same issues as those surrounding checking JAR files into CVS :-). * Tomcat docs for a particular version should be delivered as one or more web apps (not necessarily the root webapp as is current practice). That way, the corresponding WAR files could be dropped into *any* container, or opened up and read directly from the filesystem. * At least two documentation webapps (developer-oriented and user-oriented) would seem to be appropriate. Having more than two will make it difficult to create reliable hyperlinks (since you don't have any control over the context path that someone uses to deploy). - r Craig McClanahan
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:[TomcatDocumentation Redactors To Hire]
On Mon, 2 Jul 2001, Rob S. wrote: We've started writing some new docs in XML (catalina/docs/dev/xdocs). The HTML generation is done with XSL, but the DTD should be the same as the one used by Anakia. I noticed the xdocs directory, but I didn't see anything in there. I sent Craig an email about it a week ago, but haven't heard back from him. Just got back from vacation last night. If I'd read your email a week ago, I'd have been in ***big*** trouble with my wife :-). Am I doing something wrong? (re: CVS, not emailing Craig =) There are currently eight XML files in the catalina/docs/dev/xdocs directory. They aren't transformed by the standard build process, because the current use of style was temporary -- until a decision was made on what transformation tool was going to be used. To generate the corresponding HTML files, execute the following: cd $JAKARTA_TOMCAT_40_HOME/catalina ant dev-doc and the generated files will be in $JAKARTA_TOMCAT_40_HOME/build/dev-doc/ You'll need to make sure that you have Ant's optional.jar file in $ANT_HOME/lib, and all three JAXP/1.1 JAR files as well (replacing the jaxp.jar and parser.jar that were already there). - rob web cvs weenie slifka Craig
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
Probably even more... It allows more dummies to install our software, more dummies = more bugs found, more bugs found = more fixes, more fixes = better software... Or that's right only in f**ked up mind? :) Pier +1
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
On Mon, Jul 02, 2001 at 07:38:55PM -0700, Si Ly wrote: I submitted a very simple patch last week, and I haven't heard from anyone about it. It seems to me that outsiders (non-committers) can't get anything into CVS because the committers are not looking at the patches, for whatever reasons. Or maybe it's because there are problems with the patches? Even if that's the case, a response would still be appreciated. Otherwise, what encouragement is there for future submissions? FWIW, if at first you don't succeed in getting a reply, repost your patch. I typically wait about a week in between submissions. After about the third week, I usually drop the patch if no one has responded. =) And, please don't take non-responsiveness personally. It is probably more the case that the people with commit access don't believe that your problem is worth fixing. You'll need to make a convincing argument to stop them from hitting the delete key when reading the message. -- justin
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:[TomcatDocumentation Redactors To Hire]
On Mon, 2 Jul 2001, Si Ly wrote: I submitted a very simple patch last week, and I haven't heard from anyone about it. It seems to me that outsiders (non-committers) can't get anything into CVS because the committers are not looking at the patches, for whatever reasons. Sorry about that, Larry is in vacation, I'm preparing to go in vacation, almost everyone is quite busy. The patch is good, if nobody else get to submit it I'll do that when I return ( and start again on jasper - I just want to make sure the connector is in good state so we can finally have the beta ). Thanks for the patch, sorry for the delay :-( Costin
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
The patch is good, if nobody else get to submit it I'll do that when I return ( and start again on jasper - I just want to make sure the connector is in good state so we can finally have the beta ). If Costin agree with the patch, I'll commit them
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:[TomcatDocumentation Redactors To Hire]
on 7/3/01 8:04 AM, Justin Erenkrantz [EMAIL PROTECTED] wrote: On Mon, Jul 02, 2001 at 07:38:55PM -0700, Si Ly wrote: I submitted a very simple patch last week, and I haven't heard from anyone about it. It seems to me that outsiders (non-committers) can't get anything into CVS because the committers are not looking at the patches, for whatever reasons. Or maybe it's because there are problems with the patches? Even if that's the case, a response would still be appreciated. Otherwise, what encouragement is there for future submissions? The best place to put patches is into the bug tracking system... http://Nagoya.apache.org/bugzilla/ -jon
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
Hi, I'm finally back. I'll see about committing it this week in 3.2.3 and 3.3. It would be helpful to go ahead and log a bug in Bugzilla so this issue can be tracked. Cheers, Larry -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]] Sent: Tuesday, July 03, 2001 11:12 AM To: [EMAIL PROTECTED] Subject: Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire] On Mon, 2 Jul 2001, Si Ly wrote: I submitted a very simple patch last week, and I haven't heard from anyone about it. It seems to me that outsiders (non-committers) can't get anything into CVS because the committers are not looking at the patches, for whatever reasons. Sorry about that, Larry is in vacation, I'm preparing to go in vacation, almost everyone is quite busy. The patch is good, if nobody else get to submit it I'll do that when I return ( and start again on jasper - I just want to make sure the connector is in good state so we can finally have the beta ). Thanks for the patch, sorry for the delay :-( Costin
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:[TomcatDocumentation Redactors To Hire]
Geir Magnusson Jr. wrote: This is deja vu all over again. We should take one copy if this discussion (we had the same thing in Commons, and I am sure it happened everywhere else...), post it somewhere, and people can just submit article numbers or something rather than typing the same arguments over and over. Yes, I know you feel [21], but [17-19,28]. It would be so much quicker... Christopher Cain wrote: being bothered with this thread are both completely irrelevant, Ace. I have no interest in Anakia, and quite frankly, as has been pointed out very astutely by Costin, I have no interest in bothering with XML for the purposes of documentation. I will produce HTML docs with my favorite editor and call it a task adequately completed. Asking anything beyond that will more than likely be more time and effort than I am prepared to invest in simple documentation. Documentation is just as valuable as the software... I could not agree more. What I meant by simple documentation is that I, personally, do not have to requisite expertise to write in-depth docs on the various inner workings of Tomcat. Since there are a fair amount of short docs on specific aspects, such as the NT service, running the connectors in-process, etc., we should keep in mind that the frequency of submissions of such simple documentation by users is inversely proportionate to the complexity of the solution we choose. If I am Joe User, and I put together some notes on how I managed to get a connector configured under Windoze 2000, am I likely to try and learn a complex DTD in order to submit it to the project, especially if I have a rather demanding day job? Probably not. Am I likely to download a program, learn it, and generate the right format? Probably not. Now if a few people on the list are willing to take text and/or HTML submissions and generate the approved format, then so much the better. Since I have now opened my mouth and made a suggestion on what *others* should do with their OSS time, I suppose I am more or less volunteering to help up in that regard. But my point was simple to caution against an over-engineered approach to documentation without a few people stepping forward to help own Tomcat documentation. Otherwise it will only lead to less documentation. In short, let us please continue and decide upon how to proceed. Regardless of Jon's off-topic confusion, I would really like to know how the community would like to see any documentation which I may contribute. Didn't you just say that you are going to do it in HTML and declare victory no matter what? Actually, what I said was that I would declare it a task adequately completed. =) What I meant to imply was that let's not make generating documentation a class project. Like most non-critical software, at the end of the day it doesn't really matter how many bells and whistles the solution provides if no one has the inclination or the time to learn how to use a complex package. We are all programmers, and the easier the solution the more likely it is we will deign to actually bother with documentation. My delivery was admitedly a little pointed and unclear because I was having a little fun with Jon. But that's okay, he loves the abuse. =) - Christopher
Re: AW: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
On Tue, 3 Jul 2001, Jon Stevens wrote: It's just sad when an organization like Apache chooses to ignore existing standards and invent it's own DTD and transformation language to do the site. Once again Costin, you fail to impress me with your statements. You confuse Apache with some organization of people who are paid to work on stuff. Well, it's not my goal to impress you - and it doesn't matter if people are paid or not. It's a choice that every group should make - Apache made once the choice to strictly implement the HTTP spec, and it used to be a place where standards meant something. And the fact that apache site is built on top of an arbitrary xml DTD and transformation language when a stadard one exists is quite impressive for me. Is apache now a standard body, competing with W3C and oasis ? Having said that, you didn't come up with a solution and I personally think that the XSLT standards suck. I'm sure that plenty of other people who have spent enough time with XSLT will agree with me (for me, it took all of 5 minutes to figure out that XSLT's implementation sucks). So, I came up with a solution (Anakia) that beat the pants off of Stylebook in terms of speed and ease of use and now at least 10 different Jakarta projects have adopted it. Something must be acceptable about it. Sure - what's next ? HTTP sucks, and we implement our better version ? After all apache has many users, I'm sure people will find some extensions usefull. So whoever writes a DTD and a transformation language will have apache site converted to it, and all people will have to forget about anakia DTD and use the new DTD ( until another apache DTD is invented ) ? So, when you come up with something better and port everything over, I'm sure that we will all just love using it. Until then, I suggest that you keep your opinions to yourself as they are not helpful at all. I'm sure they're not helpful to you. But since the discussion is about switching tomcat documentation from HTML to an apache-specific tag set, I think people might find my opinion useful. And of course, I do hope the use of anakia tagset will happen _after_ a vote on tomcat_dev, as it should be. Costin
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:[TomcatDocumentation Redactors To Hire]
This is deja vu all over again. We should take one copy if this discussion (we had the same thing in Commons, and I am sure it happened everywhere else...), post it somewhere, and people can just submit article numbers or something rather than typing the same arguments over and over. Yes, I know you feel [21], but [17-19,28]. It would be so much quicker... Christopher Cain wrote: being bothered with this thread are both completely irrelevant, Ace. I have no interest in Anakia, and quite frankly, as has been pointed out very astutely by Costin, I have no interest in bothering with XML for the purposes of documentation. I will produce HTML docs with my favorite editor and call it a task adequately completed. Asking anything beyond that will more than likely be more time and effort than I am prepared to invest in simple documentation. Documentation is just as valuable as the software... In short, let us please continue and decide upon how to proceed. Regardless of Jon's off-topic confusion, I would really like to know how the community would like to see any documentation which I may contribute. Didn't you just say that you are going to do it in HTML and declare victory no matter what? geir -- Geir Magnusson Jr. [EMAIL PROTECTED] System and Software Consulting Developing for the web? See http://jakarta.apache.org/velocity/ You have a genius for suggesting things I've come a cropper with!
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
Brad Cox wrote: At 10:09 AM -0400 7/2/01, Rob S. wrote: 1) Developers don't write them in lieu of coding. 2) Users don't read them 3...) ? http://www.c2.com/cgi-bin/wiki has a novel way of getting at the problem. Not a panacea obviously, but what is? The one at that address is perl-based; I can provide a tomcat/mod_jk/servlet based one if there's interest. I don't have much wiki experience - however the one I am familiar with is a huge mud ball, contentwise. Would you describe the one above as a good example of wiki docs, or are there better ones? geir -- Geir Magnusson Jr. [EMAIL PROTECTED] System and Software Consulting Developing for the web? See http://jakarta.apache.org/velocity/ You have a genius for suggesting things I've come a cropper with!
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:[TomcatDocumentation Redactors To Hire]
Geir Magnusson Jr. at [EMAIL PROTECTED] wrote: Documentation is just as valuable as the software... Probably even more... It allows more dummies to install our software, more dummies = more bugs found, more bugs found = more fixes, more fixes = better software... Or that's right only in f**ked up mind? :) Pier
