cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@indexgeo.com.au>
Subject Re: Documentation: short alternative to @docname@?
Date Wed, 24 Oct 2001 04:55:27 GMT
Good one Bernhard - i was just working up my own
reply when yours came in. Yes, entities are an obvious
choice for any such XML replacement. Ideally these are
defined in the DTD. Perhaps they can instead be defined
in the "entity catalog" - i am not yet sure.

Some other notes ...

*) "Samples - Entity catalogs" has an example. &note; is
declared in the XML instance and resolves to Note:

*) Use of Ant expansions to replace @docname@ etc. tags.
This is currently working. However, the XML documents
are then application specific - not true XML. Ditto for the
stylesheet solution. I believe that it is the job of the parser
and entity resolver to do such replacement at the beginning
of the generated XML stream.

*) There was a decision on this list a few months (?) ago
to consistently call the product "Apache Cocoon" always
in full. Does that decision still stand? Perhaps it is up to
document authors to use the tags carefully. For example:
"Apache Cocoon has three basic configuration points ..."
could rather be ...
"There are three basic configuration points ..."
-- David

Bernhard Huber wrote:
> Hi
> another idea, what about using xml-entities,
> defining an xml-entity for each shortcut?
> This way the xml-parser would replace the shurt cuts
> already.
> 
> ----- Originalnachricht -----
> Von: Ovidiu Predescu <ovidiu@cup.hp.com>
> Datum: Dienstag, Oktober 23, 2001 10:36 pm
> Betreff: Re: Documentation: short alternative to @docname@? 
> 
> > On Tue, 23 Oct 2001 19:43:51 +0200, "Gianugo Rabellino" 
> > <gianugo@rabellino.it> 
> > wrote:
> > 
> > > Ciao team,
> > > 
> > > while writing the user documentation I came across quite often 
> > to the
> > > need of writing "Cocoon" instead than "Apache Cocoon" for 
> > fluency and
> > > readability. Since I'm stricly sticking to the use of @docname@ and
> > > @doctitle@, I'm unwilling to write the "Cocoon" term directly in the
> > > phrase: couldn't it be the case to have another macro that 
> > expands to
> > > "Cocoon" only ("shortname" or "appname" maybe)?
> > > 
> > > As an example, consider the following paragraph I wrote (I'm 
> > starting> some general documentation about Cocoon configuration):
> > > 
> > > "Every application needs to be configured, and Apache Cocoon is no
> > > exception to the rule. Apache Cocoon has three basic configuration
> > > points: the first one is of course the sitemap, which is 
> > responsible for
> > > making decisions about how the processing takes place given a 
> > requested> resource; the second one is Apache Cocoon's own 
> > configuration, where the
> > > Apache Cocoon components are declared and configured; finally 
> > there is a
> > > configuration file mostly intended for hard-core developers 
> > willing to
> > > play with the Avalon configuration of Apache Cocoon".
> > > 
> > > Well... I think that the above paragraph sounds much better 
> > using only
> > > "Cocoon" instead  of the whole "Apache Cocoon". Am I the only 
> > one? :)
> > 
> > In the XML documents I write, I use simple XML elements, which I 
> > transform to
> > the right content using a stylesheet. The example you give would 
> > look something
> > like this:
> > 
> > "Every application needs to be configured, and <term:acocoon/> is 
> > no exception
> > to the rule. <term:cocoon/> has three basic configuration points: 
> > the first one
> > is of course the sitemap, which is responsible for making 
> > decisions about how
> > the processing takes place given a requested resource; the second 
> > one is
> > <term:cocoon/>'s own configuration, where the <term:cocoon> 
> > components are
> > declared and configured; finally there is a configuration file 
> > mostly intended
> > for hard-core developers willing to play with the Avalon 
> > configuration of
> > <term:cocoon/>".
> > 
> > You can then define <term:cocoon/> to expand to "Cocoon", and 
> > <term:acocoon/>to "Apache Cocoon".
> > 
> > > --
> > > Gianugo (who had not the time to discover where and how the 
> > macro are
> > > expanded... please bear with my ignorance, in any case I'm 
> > volunteering> to implement that :)
> > 
> > @docname@ is replaced by Ant during the build process. The trick I 
> > describedabove would require instead a new transformer in the 
> > pipeline.
> > Regards,
> > -- 
> > Ovidiu Predescu <ovidiu@cup.hp.com>
> > http://orion.rgv.hp.com/ (inside HP's firewall only)
> > http://sourceforge.net/users/ovidiu/ (my SourceForge page)
> > http://www.geocities.com/SiliconValley/Monitor/7464/ (GNU, Emacs, 
> > other stuff)
> > 
> > 
> > 
> > -------------------------------------------------------------------
> > --
> > To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> > For additional commands, email: cocoon-dev-help@xml.apache.org
> > 
> > 
> 

----------------------------------------
Content-Type: text/x-vcard; charset="us-ascii"; name="bh22351.vcf"
Content-Transfer-Encoding: 7bit
Content-Description: Card for <bh22351@i-one.at>
----------------------------------------

----------------------------------------
Content-Type: text/plain; charset="us-ascii"; name="Attachment: 2"
Content-Transfer-Encoding: 7bit
Content-Description: 
----------------------------------------

---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message