Re: [Docutils-develop] "Tree" construct?

[Adam C. <ad...@ch...>]

On Tue, 02 Jul 2002 21:48:20 -0400 David Goodger
<go...@us...> wrote:

> Adam Chodorowski wrote:
> > Is there any plan for adding a "tree" construct to reST? It would be
> > very useful for many things, for example displaying directory
> > trees. You could use the following syntax (if it isn't ambigous, I
> > don't know...):
> > 
> > + Root
> >   +- Child 1
> >   |  +- Grandchild 1.1
> >   |  +- Grandchild 1.2
> >   +- Child 2
> 
> No plans; this is the first request I've seen.  The syntax as given
> *is* ambiguous: the "+" looks like a bullet.  It could easily be made
> unambiguous though (for example, use "+-" throughout).
> 
> What's the difference between a tree and a nested list?  You could
> simply represent it like this:

[example]

> The list has a little more vertical space, but contains the same
> information.

Yes, conceptually nested lists and a tree are basically the same. One problem
with the former is exactly the extra whitespace, which makes it impractical to
really use for larger trees. 

The other part is mostly about presentation: nested lists are presented quite
differently from how I would like trees to be (like my example with lines and
such (which is IMHO actually useful for people reading the document)). Also,
it would be quite easy to detect "interior nodes" and "leafe nodes", and you
could vary the output accordingly (eg. put a directory icon before the
interior ones, file icon before leaves). 

> Literal blocks (ASCII art) would be an easy way to get started.
> Depending on what processing ought to be done to the tree, this
> may be an adequate solution.

Perhaps a directive followed by nested lists would be enough. The directive
could simply wrap the lists with "this is really a tree", so it is possible to
make the output look different (eg. the HTML writer could wrap it in <div
class="tree"> so you could use the stylesheet to reduce vertical spacing etc)
from regular nested lists (which you might want to use for other things). Eg.:

.. tree::

   Root

   + Child 1 
     
     + Grandchild 1.1
     + Grandchild 1.2
 
   + Child 2
 
> Some preliminary questions to answer:  What's the internal/XML
> representation to be?  What should output look like (HTML, for
> example)?  Do you know of any precedent or useful references?

Apart from how common file managers present directory structures, no. 
I am not aware if such special constructs are available in other languages
(although it wouldn't suprise me if DocBook has); people seem to do this
mostly with lower-level (hackish, if you will) drawing constructs to get the
result they want.  
 
> If it is important to you, I'd say start with a directive.  I'd be
> glad to help you get started.

It's not extremely important, but I do have a document in HTML which uses
tables and icons to present and example directory tree very neatly which I
will be converting into reST. Basically, I want the reST output look just as
good as the HTML, so I don't get any complaints. ;-) 

---
Adam Chodorowski <ad...@ch...>

Chapter 1
    The story so far:
    In the beginning the Universe was created. This has made a lot of
    people very angry and been widely regarded as a bad move.