Re: documentation - new titles of examples + list of examples

tkaczano@... 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

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.

I like this idea a lot.

 Any suggestions on how to make it 
better ?

  

Send us a patch :)

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

  

---

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

    http://xircles.codehaus.org/manage_email