On May 27, 2009, at 11:04 PM, [email protected] wrote:
Hi,
I've a suggestion regarding examples included in documentation.
Downsides of current approach:
a) uninformative titles of examples ("build.gradle", "Output of
gradle -q
hello")
b) because of this there is no way to create "list of
examples" (because we
have ~50 examples with the same title - "build.gradle")
c) numbers of examples suggest that outputs are separate from
sourcefile
which is rarely true
I agree.
Please take a look at attached picture to see how the new proposal
differs.
The picture presents the idea - there is still room for visual
improvements
via CSS etc.
Upsides of proposed approach:
a) titles are meaningful, and you can choose them as you like
b) it is possible to create a useful list of examples (yes !)
c) sourcefile and output are grouped together which is more logical
d) the new code is backward-compatible - if you don't add a title,
you will
get the filename (i.e. "build.gradle") as title.
Excellent.
Downsides of proposed approach:
a) someone has to add titles for all examples (not necessarily -
keep on
reading)
I have written a patch that does all of it. The only change for
documentation
creators, is that you will be kindly asked to add a new attribute to
sample
tag - "title". But as I said previously - you don't have to. For
example:
<sample id="upper" dir="userguide/tutorial/upper"
title="Simple Gradle
tasks">
<sourcefile file="build.gradle"/>
<output args="-q upper"/>
</sample>
I wanted to ask you if you like this idea. Any suggestions on how to
make it
better ?
I like this idea very much. This is excellent stuff. I would wait
until Adam is back (next week). He has done all the LaTeX2Docbook
transformation. I would like him to have a look at it before applying
the patch. And it would be really cool to have an additional appendix
with the new expressive example names.
Thanks
- Hans
--
Hans Dockter
Gradle Project Manager
http://www.gradle.org
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
