Re: 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 ?