You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Gianugo Rabellino <gi...@rabellino.it> on 2001/10/23 19:43:51 UTC
Documentation: short alternative to @docname@?
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? :)
Ciao,
--
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 :)
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
RE: Documentation: short alternative to @docname@?
Posted by Carsten Ziegeler <cz...@sundn.de>.
Gianugo Rabellino wrote:
>
> > instead of "Apache Cocoon". So a simple solution would be to
> > mention "Apache Cocoon" once in each document (anywhere at the top)
> > and from that on simply use "Cocoon".
>
> Absolutely reasonable and effective. :)
>
> > Although I introduced @docname@, @doctitle@ etc, I'm not happy with
> > them. According to the recent decision not to use the version number
> > when mentioning Apache Cocoon, I think we can and should simply
> > remove all these placeholders and write directly what we mean.
>
> Again, even though my vote desn't count, I totally agree on this. What's
> the next step? :)
>
We should remove all occurences of @docname@ and @doctitle@ in the xdocs
and replace them with either Apache Cocoon, Cocoon or Apache Cocoon 2.
I will to this today.
Carsten
> Ciao,
>
> --
> Gianugo Rabellino
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation: short alternative to @docname@?
Posted by Gianugo Rabellino <gi...@rabellino.it>.
> instead of "Apache Cocoon". So a simple solution would be to
> mention "Apache Cocoon" once in each document (anywhere at the top)
> and from that on simply use "Cocoon".
Absolutely reasonable and effective. :)
> Although I introduced @docname@, @doctitle@ etc, I'm not happy with
> them. According to the recent decision not to use the version number
> when mentioning Apache Cocoon, I think we can and should simply
> remove all these placeholders and write directly what we mean.
Again, even though my vote desn't count, I totally agree on this. What's
the next step? :)
Ciao,
--
Gianugo Rabellino
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
RE: Documentation: short alternative to @docname@?
Posted by Carsten Ziegeler <cz...@sundn.de>.
Some months ago, we decided to everywhere use "Apache Cocoon" instead
of simply Cocoon due to another project called "Cocoon".
I agree, that the docs look much better if you simply use Cocoon
instead of "Apache Cocoon". So a simple solution would be to
mention "Apache Cocoon" once in each document (anywhere at the top)
and from that on simply use "Cocoon".
Although I introduced @docname@, @doctitle@ etc, I'm not happy with
them. According to the recent decision not to use the version number
when mentioning Apache Cocoon, I think we can and should simply
remove all these placeholders and write directly what we mean.
This makes the documentation useable with any stylesheet which
can transform the documentation format, no need for Ant, another
transformer etc.
Carsten
Gianugo Rabellino 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? :)
>
> Ciao,
>
> --
> 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 :)
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org