← Back to branch summary

~ubuntu-branches/ubuntu/trusty/gnome-doc-utils/trusty-proposed

« back to all changes in this revision

Viewing changes to doc/mallard/C/mal_block_tree.page

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-02-23 15:55:38 UTC
  • mfrom: (1.1.29 upstream)
  • Revision ID: james.westby@ubuntu.com-20100223155538-odq0bbr5tl0p2lpv
Tags: 0.19.5-0ubuntu1
* New upstream release:
  - Updated the Mallard RNG schema (Shaun McCance)
  - Bold userinput inside programlisting (Shaun McCance)
  - Updated translations
* debian/control.in:
  - bump Standards-Version

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/mallard/C/mal_block_tree.page
1
 
<page xmlns="http://projectmallard.org/1.0/"
2
 
      type="topic"
3
 
      id="mal_block_tree">
4
 
 
5
 
<info>
6
 
  <revision version="0.1" date="2009-05-25" status="review"/>
7
 
 
8
 
  <credit type="author">
9
 
    <name>Shaun McCance</name>
10
 
    <email>shaunm@gnome.org</email>
11
 
    <years>2008-2009</years>
12
 
  </credit>
13
 
 
14
 
  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
15
 
 
16
 
  <desc>Create simple trees to show heirarchical structures.</desc>
17
 
</info>
18
 
 
19
 
<title>Tree Lists</title>
20
 
 
21
 
<synopsis><code mime="application/relax-ng-compact-syntax">
22
 
mal_block_tree = element tree {
23
 
  attribute style { xsd:NMTOKENS } ?,
24
 
  attribute * - (mal:* | local:*) { text } *,
25
 
 
26
 
  <link xref="mal_block_title">mal_block_title</link> ?,
27
 
  mal_tree_item +
28
 
}
29
 
mal_tree_item = element item {
30
 
  attribute style { xsd:NMTOKENS } ?,
31
 
  attribute * - (mal:* | local:*) { text } *,
32
 
 
33
 
  <link xref="mal_inline">mal_inline</link>,
34
 
  mal_tree_item *
35
 
}
36
 
</code></synopsis>
37
 
 
38
 
<p>Use the <code>tree</code> element to create a heirarchical tree.  While
39
 
conceptually similar to nested <code xref="mal_block_list">list</code>
40
 
elements, trees offer a simple way to display common heirarchies such as
41
 
class inheritance or directory layouts.</p>
42
 
 
43
 
 
44
 
<!-- BEGIN notes -->
45
 
<section id="notes">
46
 
  <title>Notes</title>
47
 
  <list>
48
 
    <item><p>The <code>tree</code> element can contain an optional
49
 
    <code xref="mal_block_title">title</code> element followed by one or more
50
 
    <code>item</code> elements.  Each child <code>item</code> element can
51
 
    contain a mixture of text and any
52
 
    <link xref="mal_inline">general inline elements</link>, followed by
53
 
    zero or more nested <code>item</code> elements.</p></item>
54
 
 
55
 
    <item><p>The <code>tree</code> element can occur in any
56
 
    general block context, including inside
57
 
    <link xref="mal_page">pages</link>, <link xref="mal_section">sections</link>,
58
 
    and certain <link xref="mal_block">block elements</link>.</p></item>
59
 
 
60
 
    <item><p>The <code>style</code> attribute takes a space-separated list of
61
 
    style hints.  Processing tools should adjust their behavior according to
62
 
    those style hints they understand.</p></item>
63
 
 
64
 
    <item>
65
 
      <p>The following style hints are recommended:</p>
66
 
      <table rules="rows">
67
 
        <tr>
68
 
          <td><p><code>lines</code></p></td>
69
 
          <td><p>draw lines to show the hierarchy</p></td>
70
 
        </tr>
71
 
      </table>
72
 
    </item>
73
 
 
74
 
    <item><p>The <code>tree</code> element can have attributes from external
75
 
    namespaces.  See <link xref="mal_external"/> for more information
76
 
    on external-namespace attributes.</p></item>
77
 
  </list>
78
 
</section>
79
 
<!-- END notes -->
80
 
 
81
 
 
82
 
<!-- BEGIN examples -->
83
 
<section id="examples">
84
 
  <title>Examples</title>
85
 
 
86
 
  <p>Use a tree to outline a class heirarchy inside a
87
 
  <code xref="mal_block_synopsis">>synopsis</code> element:</p>
88
 
 
89
 
  <example>
90
 
    <code><![CDATA[
91
 
<synopsis>
92
 
  <tree>
93
 
    <item>
94
 
      <code>GtkBin</code>
95
 
      <item>
96
 
        <code>GtkButton</code>
97
 
        <item><code>GtkToggleButton</code></item>
98
 
        <item><code>GtkColorButton</code></item>
99
 
        <item><code>GtkFontButton</code></item>
100
 
        <item><code>GtkLinkButton</code></item>
101
 
        <item><code>GtkOptionMenu</code></item>
102
 
        <item><code>GtkScaleButton</code></item>
103
 
      </item>
104
 
    </item>
105
 
  </tree>
106
 
</synopsis>]]></code>
107
 
    <synopsis>
108
 
      <tree>
109
 
        <item>
110
 
          <code>GtkBin</code>
111
 
          <item>
112
 
            <code>GtkButton</code>
113
 
            <item><code>GtkToggleButton</code></item>
114
 
            <item><code>GtkColorButton</code></item>
115
 
            <item><code>GtkFontButton</code></item>
116
 
            <item><code>GtkLinkButton</code></item>
117
 
            <item><code>GtkOptionMenu</code></item>
118
 
            <item><code>GtkScaleButton</code></item>
119
 
          </item>
120
 
        </item>
121
 
      </tree>
122
 
    </synopsis>
123
 
  </example>
124
 
 
125
 
  <p>Use the <code>lines</code> style hint to visually show the tree structure:</p>
126
 
 
127
 
  <example>
128
 
    <code><![CDATA[
129
 
<tree style="lines">
130
 
  <item>
131
 
    Anatinae (dabbling ducks)
132
 
    <item>
133
 
      Anas
134
 
      <item>Baikal Teal</item>
135
 
      <item>Wigeons</item>
136
 
      <item>Mallard</item>
137
 
    </item>
138
 
    <item>Lophonetta</item>
139
 
    <item>Speculanas</item>
140
 
  </item>
141
 
  <item>
142
 
    Anthyinae (diving ducks)
143
 
    <item>Aythya</item>
144
 
    <item>Netta</item>
145
 
  </item>
146
 
  <item>Dendrocygninae (whistling ducks)</item>
147
 
</tree>]]></code>
148
 
    <tree style="lines">
149
 
      <item>
150
 
        Anatinae (dabbling ducks)
151
 
        <item>
152
 
          Anas
153
 
          <item>Baikal Teal</item>
154
 
          <item>Wigeons</item>
155
 
          <item>Mallard</item>
156
 
        </item>
157
 
        <item>Lophonetta</item>
158
 
        <item>Speculanas</item>
159
 
      </item>
160
 
      <item>
161
 
        Anthyinae (diving ducks)
162
 
        <item>Aythya</item>
163
 
        <item>Netta</item>
164
 
      </item>
165
 
      <item>Dendrocygninae (whistling ducks)</item>
166
 
    </tree>
167
 
  </example>
168
 
</section>
169
 
<!-- END examples -->
170
 
 
171
 
 
172
 
<!-- BEGIN processing -->
173
 
<section id="processing">
174
 
  <title>Processing Expectations</title>
175
 
 
176
 
  <p>Tree lists are display as block elements.  Each child <code>item</code>
177
 
  has its leading inline content displayed in a single block and any nested
178
 
  <code>item</code> elements displayed as blocks in turn.  Successive levels
179
 
  of nesting should yield more indentation, though this may vary based on
180
 
  style hints or other factors.  By default, there should be little vertical
181
 
  spacing between items; trees are compact.  No bullets, icons, or other marks
182
 
  are expected to precede items, although they may be used for certain style
183
 
  hints.</p>
184
 
</section>
185
 
<!-- END processing -->
186
 
 
187
 
</page>