documentation - new titles of examples + list of examples

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

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.

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 ?

--
best regards
Tomek Kaczanowski
http://kaczanowscy.pl/tomek



---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email