cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: Documentation: short alternative to @docname@?
Date Wed, 24 Oct 2001 08:31:09 GMT
Ovidiu Predescu wrote:

> You can then define <term:cocoon/> to expand to "Cocoon", and <term:acocoon/>
> to "Apache Cocoon".

Ehm, you guys, let me ask you one single question: why do you think
@xxx@ macro substitution was implemented in Ant? (by me, in case you
didn't know).

For things like @date@ or @version@ or @location@ which are dynamic and
found in many different locations.

Then, for build file portability (I had to write the build files for all
the xml.apache.org projects back then), I decided to make the project
name also expandable to save time in the README files which were very
much equal in all projects.

But I didn't thought of extensive abuse of this feature as you guys are
proposing right now.

Ask yourself: are you going to reuse the same exact documentation for
another project? or is Cocoon going to change its name anytime soon? or
is the version (which is dynamic) always required in @docname@?

Gianugo, let's cut the crap and think straight: there is no need for
@acocoon@ or @cocoon@ or even for <term:cocoon/> then and xslt
transformed (god!).

Rule: when you write something that *MUST* remain the same, don't make
it easy for people to change it and mess it up.

We are never going to reuse our documentation for other projects. And
even if we did so, all editors have search/replace capabilities anyway.

I would understand if the macro represented a big chunk of text that
could be easily mispelled (say, a license) but gosh <term:cocoon/> is,
in fact, longer than simply Cocoon and easier to mispell.

But this is my personal opinion and in order to have a resolution we
need some vote so: 

 would you like to remove all references to macro expansions that
*DON'T  EVER* change across the Cocoon build environment?

I do. +1 to remove all unnecessary @xxx@ placeholders (which leaves
almost only @version@, @years@, @date@ and a few others).

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<stefano@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------



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


Mime
View raw message