Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-dev@xml.apache.org
Message-Id: <200110232036.f9NKawf26900@orion.rgv.hp.com>
From: Ovidiu Predescu <ovidiu@cup.hp.com>
To: "Gianugo Rabellino" <gianugo@rabellino.it>
Cc: cocoon-dev@xml.apache.org
Subject: Re: Documentation: short alternative to @docname@? 
In-Reply-To: Your message of "Tue, 23 Oct 2001 19:43:51 +0200."
             <01c801c15bea$47b84ca0$642a2a0a@ADINA>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Date: Tue, 23 Oct 2001 13:36:58 -0700
Sender: ovidiu@orion.rgv.hp.com

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 described
above 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