crossley 2003/06/14 20:24:57
Modified: src/documentation/xdocs introduction.xml Log: Use more formal phrasing. Fix some typos. Submitted by: Glen Mazza <glenmazza.AT.yahoo.com> Bug: 20775 Revision Changes Path 1.2 +35 -35 cocoon-2.0/src/documentation/xdocs/introduction.xml Index: introduction.xml =================================================================== RCS file: /home/cvs/cocoon-2.0/src/documentation/xdocs/introduction.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- introduction.xml 9 Mar 2003 00:00:49 -0000 1.1 +++ introduction.xml 15 Jun 2003 03:24:57 -0000 1.2 @@ -22,9 +22,9 @@ <p> Should you care about it? Given the amount of hype, you can't afford to -go around ignoring the argument, would be like ignoring the world wide -web 10 years ago: a clear mistake. But why is this so for XML? What is -this "magic" that XML seems to have to solve my problems? Isn't this +go around ignoring XML, for that would be like ignoring the World Wide +Web 10 years ago: a clear mistake. But why is this so for XML? What is +this "magic" that XML seems to have in solving your problems? Isn't this another hype to change once again the IT infrastructure that you spent so much time implementing and fixing in the last few years? Isn't another way to spill money out of your pockets? @@ -32,7 +32,7 @@ <p> If you ever asked yourself one of the above questions, this paper is for -you. You won't find singing-and-dancing marketing crap, you won't find +you. You won't find singing-and-dancing marketing hype, you won't find boring and useless feature lists, you won't find the usual acronym bombing or those good looking vaporware schemas that connect your databases to your coffee machines via CORBA or stuff like that. @@ -50,10 +50,10 @@ <p> It was frustrating to see the best and most clever information -technology ever invented (the web) ruined by the lack of engineering +technology ever invented--the Web--ruined by the lack of engineering practices, tortured by those "let's-reinvent-the-wheel-once-again" -craftmen that were great at doing their jobs as individuals but that -couldn't scale and imposed a growth saturation to the whole project. +craftsmen who were great at doing their jobs as individuals but +could not scale within teams, imposing a growth saturation to their projects. </p> <p> @@ -67,7 +67,7 @@ <p> In 1998, Stefano Mazzocchi volunteered to create the documentation infrastructure for -the java.apache.org project, which is composed by a bunch of different +the java.apache.org project, which is composed of a bunch of different codebases, maintained by a bunch of different people, with different skills, different geographical locations and different degree of will and time to dedicate to the documentation effort. @@ -75,10 +75,10 @@ <p> But pretty soon he realized that no matter how great and well designed the -system was, HTML was a problem: it was *not* designed for those kind of -things. Looking at the main page (<link href="http://java.apache.org/";>http://java.apache.org/</link>) from the -browser and you could clearly identify the areas of the screen: sidebar, -topbar, news, status. But if you opened the HTML, boom: a nightmare or +system was, HTML was a problem: it was *not* designed for those kinds of +things. By looking at the main page (<link href="http://java.apache.org/";>http://java.apache.org/</link>) from the +browser, you can clearly identify the areas of the screen: sidebar, +topbar, news, status. But if you viewed the underlying HTML, boom: a nightmare of table tags and nesting and small little tricks to make the HTML appear the same on every browser. </p> @@ -99,13 +99,13 @@ </p> <p> -How can you tell your web server to "extract" the information from the -sitebar? How can you have the news feeds out of a complex HTML page? +How can you tell your web server to extract the information contained within the +sidebar? How can you tell it to find the news articles within a complex HTML page? </p> <p> -Damn, it's easy for a human reader: just look at the page and it's very -easy to distinguish between a sidebar, a banner, a news and a stock +It's certainly easy for a human reader: just look at the page and you should have +no problem distinguishing between a sidebar, a banner, a news and a stock quote. Why is it so hard for a machine? </p> @@ -117,12 +117,12 @@ HTML is a language that tells your browser how to "draw" things on its window. An image here, a letter there, a color down here. Nothing more. The browser doesn't have the "higher level" notion of "sidebar": it -lacks the ability to perform "semantic analysis" on the HTML content. +lacks the ability to perform "semantic analysis" of the HTML content. </p> <p> Semantic analysis? Yeah, it's the kind of thing the human brain is -simply great at doing, while computer programs simply suck big time. +simply great at doing, while computer programs simply fail at big time. </p> <p> @@ -158,12 +158,12 @@ </ul> <p> -Suppose you are a chinese guy that doesn't understand our alphabet, try +Suppose you are a Chinese guy that doesn't understand our alphabet, try to answer the following question: </p> <p> - who wrote the page? +Who wrote the page? </p> <p> @@ -192,7 +192,7 @@ ]]></source> <p> -can you tell me who wrote the page? easy, you say, "sflkjoiuer" did. Good, but later +Can you now tell me who wrote the page? Easy, you say, "sflkjoiuer" did. Good, but later you receive: </p> @@ -206,7 +206,7 @@ ]]></source> <p> -now, who wrote the page? You could guess by comparing the structure, +Now, who wrote the page? You could guess by comparing the structure, but how do you know the two structures reflect the same semantic information? </p> @@ -221,7 +221,7 @@ </p> <p> -At this point, clearly not so, rather the opposite. +At this point, clearly not, rather the opposite. </p> <p> @@ -293,12 +293,12 @@ </p> <p> -And having a documentation that nobody can browse is totally useless. +And having documentation that nobody can browse is totally useless. </p> <p> The turning point was the creation of the XSL specification which -included a way to "transform" an XML page into something else. (it's +included a way to "transform" an XML page into something else. (It's more complex than this, but, again, I'll skip the technical details). </p> @@ -371,7 +371,7 @@ <p> For a web publishing system, the Cocoon project uses what we call the -<em>pyramid of contacts</em> which outlines four major concern areas and five +<em>pyramid of contracts</em> which outlines four major concern areas and five contracts between them. Here is the picture: </p> @@ -383,7 +383,7 @@ Cocoon is <em>engineered</em> to provide you a way to isolate these four concern areas using just those 5 contracts, removing the contract between style and logic that has been bugging web site development since -the beginning of the web. +the beginning of the Web. </p> <p> @@ -435,8 +435,8 @@ </p> <p> -As long as these contract don't change, the three areas can work in a -completely parallel way without saturating the human resources used to +As long as these contracts don't change, the three areas can work in a +completely parallel way without overwhelming the human resources used to manage them: costs decrease because time to market is reduced and maintenance costs is decreased because errors do not propagate out of the concern areas. @@ -444,8 +444,8 @@ <p> For example, you can tell your designers to come up with a "Xmas look" -for your web site, without even telling the other people: just switch -the XMas transformation rules at XMas morning and you're done.... just +for your web site, without even telling the other people: just switch to +the Xmas transformation rules on Xmas morning and you're done.... just imagine how painful it would be to do this on your web site today. </p> @@ -458,13 +458,13 @@ <s1 title="Here we go"> <p> -If you reached this far by reading all sections, you should have grasped the -value of the Cocoon Project and distinguish most of the marketing +If you've reached this far in my text, you should be able to grasp the +value of the Cocoon Project as well as distinguish most of the marketing hype that surrounds XML and friends. </p> <p> -Just like you shouldn't care if somebody offers you a software that is +Just like you shouldn't care if somebody offers you software that is "ASCII compliant" or "ASCII based", you shouldn't care about "XML compliant" or "XML based": it doesn't mean anything. </p> @@ -472,7 +472,7 @@ <p> Cocoon uses XML as a core piece of its framework, but improves the model to give you the tools you need and is designed to be flexible enough to -follow your needs as well as paradigm shifts that will happen in the +follow your current needs as well as paradigm shifts that may happen in the future. </p>
