You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by "Henning P. Schmiedehausen" <hp...@intermeta.de> on 2007/04/26 02:23:37 UTC
Velocity User Guide
Hi,
a first draft (which is basically a version before the 1.5 release +
some amends) is now available from
http://people.apache.org/~henning/docbook/. I intend to add the
changes that went into the guide around the 1.5 release but that is
about it. Please take a look, comments welcome.
Best regards
Henning
--
Henning P. Schmiedehausen -- hps@intermeta.de | J2EE, Linux, |gls
91054 Buckenhof, Germany -- +49 9131 506540 | Apache person |eau
Open Source Consulting, Development, Design | Velocity - Turbine guy |rwc
|m k
INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB 7350 |a s
Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning Schmiedehausen |n
"Save the cheerleader. Save the world."
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org
Re: Velocity User Guide
Posted by "Henning P. Schmiedehausen" <hp...@intermeta.de>.
"Will Glass-Husain" <wg...@gmail.com> writes:
>------=_Part_44942_25826166.1178464703263
>Content-Type: text/plain; charset=ISO-8859-1; format=flowed
>Content-Transfer-Encoding: 7bit
>Content-Disposition: inline
>Hi Henning,
>I like the new icons much better.
Ok. They are SVGs, so they scale much nicer. It is also the move from
FOP 0.20.5 to 0.93 in the docbook framework that increases
readability. I will CfV for DBF 1.1 soon.
>By the way, wouldn't it make more sense to include the source for this in
>the Velocity Engine distro so that it can be on the same release cycle as
>the code base?
Why? I'd agree that we should include a copy of the PDF at some point
but one thing that tends to hold us up is that the release cycles for
the software should not dictate the release cycles for the docs. The
releases should have a snapshot of the docs but I do not think, that
a Velocity Engine release must contain the sources to generate the
docs for this. It should contain the docs itself, not its sources.
I am not at all convinced that having doc sources in the distribution
is a good thing. They tend to be outdated and prone to errors. As we
have no "documentation team", they are not really kept up to date
until a release draws near.
The ideal amount of docs for the Velocity distribution would (IMHO) a
short intro README which points to the web site for more information
and two PDFs: User Guide and Developer guide. The whole idea of maven
generated docs leads to a vast number of web pages with little or no
real documentation on it. Which is frustrating to most users.
Especially with my experiences from Velocity, I'd say that the best
approach to up-to-date documentation would be a well-kept Wiki
(Confluence; our current wiki is a PITA) and a developers blog. And
having a doc team that distills stable pages / documentation from
these sources into a printable form (i.e. docbook and then PDF).
For the time being, I'd say that having the doc sources on SVN with
regular updates on the web site is fine. Doc patches tend to be "in
paragraph three on page 47 is a typo" reports, not patches to the XML
files. If anyone is able to submit patches to the XML, they are also
able to check out /velocity/docs from the SVN.
1.5.1/1.6 is IMHO scheduled to have at least the PDF users guide; I
still hope that anyone wants to pick up the dev guide (I will help but
not lead here) but for me it is coding time, not documentation time.
Best regards
Henning
--
Henning P. Schmiedehausen -- hps@intermeta.de | J2EE, Linux, |gls
91054 Buckenhof, Germany -- +49 9131 506540 | Apache person |eau
Open Source Consulting, Development, Design | Velocity - Turbine guy |rwc
|m k
INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB 7350 |a s
Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning Schmiedehausen |n
"Save the cheerleader. Save the world."
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org
Re: Velocity User Guide
Posted by Will Glass-Husain <wg...@gmail.com>.
Hi Henning,
I like the new icons much better.
I'm going to print out the user's guide today and proof-read in detail. I
didn't see anything on a casual reading.
By the way, wouldn't it make more sense to include the source for this in
the Velocity Engine distro so that it can be on the same release cycle as
the code base?
WILL
On 4/28/07, Henning P. Schmiedehausen <hp...@intermeta.de> wrote:
>
> "Will Glass-Husain" <wg...@gmail.com> writes:
>
> >Incidentally, I really like the annotations on the examples. (numbers,
> >etc). Makes things much clearer.
>
> If we go docbook, we can as well use its features. That was the main
> intention.
>
> >The examples are nice too. Good to get a fresh set.
>
> >One other comment... the big icons in the PDF ("Warning") look pretty
> >terrible. Is it possible to substitute a higher-quality (or vector)
> image?
>
> Hm. That is actually a good comment. There are SVGs in the docbook-xsl
> distribution, but I never bothered to try them out. Let me check...
>
> ... ok, so they are monochrome but they do scale nicely. I updated the
> version on people.apache.org, please check out.
>
> Best regards
> Henning
>
>
>
> >WILL
>
> >On 4/25/07, Henning P. Schmiedehausen <hp...@intermeta.de> wrote:
> >>
> >> Hi,
> >>
> >> a first draft (which is basically a version before the 1.5 release +
> >> some amends) is now available from
> >> http://people.apache.org/~henning/docbook/. I intend to add the
> >> changes that went into the guide around the 1.5 release but that is
> >> about it. Please take a look, comments welcome.
> >>
> >> Best regards
> >> Henning
> >>
> >>
> >> --
> >> Henning P. Schmiedehausen -- hps@intermeta.de | J2EE,
> >> Linux, |gls
> >> 91054 Buckenhof, Germany -- +49 9131 506540 | Apache
> >> person |eau
> >> Open Source Consulting, Development, Design | Velocity - Turbine
> >> guy |rwc
> >>
> |m
> >> k
> >> INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB
> >> 7350 |a s
> >> Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning
> >> Schmiedehausen |n
> >>
> >> "Save the cheerleader. Save the world."
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
> >> For additional commands, e-mail: dev-help@velocity.apache.org
> >>
> >>
>
>
> >--
> >Forio Business Simulations
>
> >Will Glass-Husain
> >wglass@forio.com
> >www.forio.com
>
> >------=_Part_227021_19355613.1177601368762--
>
> --
> Henning P. Schmiedehausen -- hps@intermeta.de | J2EE,
> Linux, |gls
> 91054 Buckenhof, Germany -- +49 9131 506540 | Apache
> person |eau
> Open Source Consulting, Development, Design | Velocity - Turbine
> guy |rwc
> |m
> k
> INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB
> 7350 |a s
> Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning
> Schmiedehausen |n
>
> "Save the cheerleader. Save the world."
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
> For additional commands, e-mail: dev-help@velocity.apache.org
>
>
--
Forio Business Simulations
Will Glass-Husain
wglass@forio.com
www.forio.com
Re: Velocity User Guide
Posted by "Henning P. Schmiedehausen" <hp...@intermeta.de>.
"Will Glass-Husain" <wg...@gmail.com> writes:
>Incidentally, I really like the annotations on the examples. (numbers,
>etc). Makes things much clearer.
If we go docbook, we can as well use its features. That was the main intention.
>The examples are nice too. Good to get a fresh set.
>One other comment... the big icons in the PDF ("Warning") look pretty
>terrible. Is it possible to substitute a higher-quality (or vector) image?
Hm. That is actually a good comment. There are SVGs in the docbook-xsl
distribution, but I never bothered to try them out. Let me check...
... ok, so they are monochrome but they do scale nicely. I updated the
version on people.apache.org, please check out.
Best regards
Henning
>WILL
>On 4/25/07, Henning P. Schmiedehausen <hp...@intermeta.de> wrote:
>>
>> Hi,
>>
>> a first draft (which is basically a version before the 1.5 release +
>> some amends) is now available from
>> http://people.apache.org/~henning/docbook/. I intend to add the
>> changes that went into the guide around the 1.5 release but that is
>> about it. Please take a look, comments welcome.
>>
>> Best regards
>> Henning
>>
>>
>> --
>> Henning P. Schmiedehausen -- hps@intermeta.de | J2EE,
>> Linux, |gls
>> 91054 Buckenhof, Germany -- +49 9131 506540 | Apache
>> person |eau
>> Open Source Consulting, Development, Design | Velocity - Turbine
>> guy |rwc
>> |m
>> k
>> INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB
>> 7350 |a s
>> Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning
>> Schmiedehausen |n
>>
>> "Save the cheerleader. Save the world."
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
>> For additional commands, e-mail: dev-help@velocity.apache.org
>>
>>
>--
>Forio Business Simulations
>Will Glass-Husain
>wglass@forio.com
>www.forio.com
>------=_Part_227021_19355613.1177601368762--
--
Henning P. Schmiedehausen -- hps@intermeta.de | J2EE, Linux, |gls
91054 Buckenhof, Germany -- +49 9131 506540 | Apache person |eau
Open Source Consulting, Development, Design | Velocity - Turbine guy |rwc
|m k
INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB 7350 |a s
Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning Schmiedehausen |n
"Save the cheerleader. Save the world."
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org
Re: Velocity User Guide
Posted by Will Glass-Husain <wg...@gmail.com>.
Incidentally, I really like the annotations on the examples. (numbers,
etc). Makes things much clearer.
The examples are nice too. Good to get a fresh set.
One other comment... the big icons in the PDF ("Warning") look pretty
terrible. Is it possible to substitute a higher-quality (or vector) image?
WILL
On 4/25/07, Henning P. Schmiedehausen <hp...@intermeta.de> wrote:
>
> Hi,
>
> a first draft (which is basically a version before the 1.5 release +
> some amends) is now available from
> http://people.apache.org/~henning/docbook/. I intend to add the
> changes that went into the guide around the 1.5 release but that is
> about it. Please take a look, comments welcome.
>
> Best regards
> Henning
>
>
> --
> Henning P. Schmiedehausen -- hps@intermeta.de | J2EE,
> Linux, |gls
> 91054 Buckenhof, Germany -- +49 9131 506540 | Apache
> person |eau
> Open Source Consulting, Development, Design | Velocity - Turbine
> guy |rwc
> |m
> k
> INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB
> 7350 |a s
> Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning
> Schmiedehausen |n
>
> "Save the cheerleader. Save the world."
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
> For additional commands, e-mail: dev-help@velocity.apache.org
>
>
--
Forio Business Simulations
Will Glass-Husain
wglass@forio.com
www.forio.com
Re: Velocity User Guide
Posted by "Henning P. Schmiedehausen" <hp...@intermeta.de>.
"Malcolm Edgar" <ma...@gmail.com> writes:
>Hi Henning,
>The new version looks good. I see the Mud store got replace by a Fruit store.
Yeah. Some of the more infantile things in the users guide always
bothered me (also the various Clinton references). This is something
that is intended to transfer knowledge to readers so I prefer a more
mature approach.
Best regards
Henning
>regards Malcolm Edgar
>On 4/26/07, Henning P. Schmiedehausen <hp...@intermeta.de> wrote:
>> Hi,
>>
>> a first draft (which is basically a version before the 1.5 release +
>> some amends) is now available from
>> http://people.apache.org/~henning/docbook/. I intend to add the
>> changes that went into the guide around the 1.5 release but that is
>> about it. Please take a look, comments welcome.
>>
>> Best regards
>> Henning
>>
>>
>> --
>> Henning P. Schmiedehausen -- hps@intermeta.de | J2EE, Linux, |gls
>> 91054 Buckenhof, Germany -- +49 9131 506540 | Apache person |eau
>> Open Source Consulting, Development, Design | Velocity - Turbine guy |rwc
>> |m k
>> INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB 7350 |a s
>> Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning Schmiedehausen |n
>>
>> "Save the cheerleader. Save the world."
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
>> For additional commands, e-mail: dev-help@velocity.apache.org
>>
>>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
>For additional commands, e-mail: dev-help@velocity.apache.org
--
Henning P. Schmiedehausen -- hps@intermeta.de | J2EE, Linux, |gls
91054 Buckenhof, Germany -- +49 9131 506540 | Apache person |eau
Open Source Consulting, Development, Design | Velocity - Turbine guy |rwc
|m k
INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB 7350 |a s
Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning Schmiedehausen |n
"Save the cheerleader. Save the world."
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org
Re: Velocity User Guide
Posted by Malcolm Edgar <ma...@gmail.com>.
Hi Henning,
The new version looks good. I see the Mud store got replace by a Fruit store.
regards Malcolm Edgar
On 4/26/07, Henning P. Schmiedehausen <hp...@intermeta.de> wrote:
> Hi,
>
> a first draft (which is basically a version before the 1.5 release +
> some amends) is now available from
> http://people.apache.org/~henning/docbook/. I intend to add the
> changes that went into the guide around the 1.5 release but that is
> about it. Please take a look, comments welcome.
>
> Best regards
> Henning
>
>
> --
> Henning P. Schmiedehausen -- hps@intermeta.de | J2EE, Linux, |gls
> 91054 Buckenhof, Germany -- +49 9131 506540 | Apache person |eau
> Open Source Consulting, Development, Design | Velocity - Turbine guy |rwc
> |m k
> INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB 7350 |a s
> Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning Schmiedehausen |n
>
> "Save the cheerleader. Save the world."
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
> For additional commands, e-mail: dev-help@velocity.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org
Re: Velocity User Guide
Posted by "Henning P. Schmiedehausen" <hp...@intermeta.de>.
"Will Glass-Husain" <wg...@gmail.com> writes:
>------=_Part_226985_28845285.1177601197510
>Content-Type: text/plain; charset=ISO-8859-1; format=flowed
>Content-Transfer-Encoding: 7bit
>Content-Disposition: inline
>Terrific!
>Is the source in svn? I want to fix a typo.
Sure. https://svn.apache.org/repos/asf/velocity/docs/src/docbook/userguide/VelocityUsersGuide.xml
If you want to build it yourself, check out https://svn.apache.org/repos/asf/velocity/docs
Please read the instructions in docbook/README.FIRST.
Best regards
Henning
>WILL
>On 4/25/07, Henning P. Schmiedehausen <hp...@intermeta.de> wrote:
>>
>> Hi,
>>
>> a first draft (which is basically a version before the 1.5 release +
>> some amends) is now available from
>> http://people.apache.org/~henning/docbook/. I intend to add the
>> changes that went into the guide around the 1.5 release but that is
>> about it. Please take a look, comments welcome.
>>
>> Best regards
>> Henning
>>
>>
>> --
>> Henning P. Schmiedehausen -- hps@intermeta.de | J2EE,
>> Linux, |gls
>> 91054 Buckenhof, Germany -- +49 9131 506540 | Apache
>> person |eau
>> Open Source Consulting, Development, Design | Velocity - Turbine
>> guy |rwc
>> |m
>> k
>> INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB
>> 7350 |a s
>> Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning
>> Schmiedehausen |n
>>
>> "Save the cheerleader. Save the world."
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
>> For additional commands, e-mail: dev-help@velocity.apache.org
>>
>>
>--
>Forio Business Simulations
>Will Glass-Husain
>wglass@forio.com
>www.forio.com
>------=_Part_226985_28845285.1177601197510--
--
Henning P. Schmiedehausen -- hps@intermeta.de | J2EE, Linux, |gls
91054 Buckenhof, Germany -- +49 9131 506540 | Apache person |eau
Open Source Consulting, Development, Design | Velocity - Turbine guy |rwc
|m k
INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB 7350 |a s
Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning Schmiedehausen |n
"Save the cheerleader. Save the world."
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
For additional commands, e-mail: dev-help@velocity.apache.org
Re: Velocity User Guide
Posted by Will Glass-Husain <wg...@gmail.com>.
Terrific!
Is the source in svn? I want to fix a typo.
WILL
On 4/25/07, Henning P. Schmiedehausen <hp...@intermeta.de> wrote:
>
> Hi,
>
> a first draft (which is basically a version before the 1.5 release +
> some amends) is now available from
> http://people.apache.org/~henning/docbook/. I intend to add the
> changes that went into the guide around the 1.5 release but that is
> about it. Please take a look, comments welcome.
>
> Best regards
> Henning
>
>
> --
> Henning P. Schmiedehausen -- hps@intermeta.de | J2EE,
> Linux, |gls
> 91054 Buckenhof, Germany -- +49 9131 506540 | Apache
> person |eau
> Open Source Consulting, Development, Design | Velocity - Turbine
> guy |rwc
> |m
> k
> INTERMETA - Gesellschaft fuer Mehrwertdienste mbH - RG Fuerth, HRB
> 7350 |a s
> Sitz der Gesellschaft: Buckenhof. Geschaeftsfuehrer: Henning
> Schmiedehausen |n
>
> "Save the cheerleader. Save the world."
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@velocity.apache.org
> For additional commands, e-mail: dev-help@velocity.apache.org
>
>
--
Forio Business Simulations
Will Glass-Husain
wglass@forio.com
www.forio.com