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 Thu, 25 Oct 2001 09:18:26 GMT
Hold on to your hats everyone! Once we resolve this stuff then
let us add it to documentation/xdocs/IMPORTANT
There are some real good reasons for keeping some type of
term substitution. Here is my big one - consistent speling.
Hey, i seem to type "Coccon" often - we had best not let that
slip through to production. Entity replacement prevents it.

Also, i think that we need to be clearer about what we are
voting on in this thread - there are some interwoven issues.
--David Croslsey

Stefano wrote:
> 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