1<TeXmacs|1.99.1>
2
3<style|tmdoc>
4
5<\body>
6  <tmdoc-title|The <TeXmacs> content model>
7
8  All <TeXmacs> documents or document fragments can be thought of as
9  <em|trees>, as explained in more detail in the chapter about the
10  <hlink|<TeXmacs> document format|../../format/basics/basics.en.tm>. Inside
11  <scheme> programs, there are two main ways to represent such trees,
12  depending on whether one manipulates active or passive documents:
13
14  <paragraph*|Passive documents and <scheme> trees><label|tree-passive>
15
16  Passive documents, like those which are processed by a<nbsp>conversion
17  tool, are usually represented by <em|scheme trees>. For instance, the
18  fraction
19
20  <\equation*>
21    <frac|a<rsup|2>|b+c>
22  </equation*>
23
24  is typically represented by
25
26  <\scm-code>
27    (frac (concat "a" (rsup "2")) "b+c")
28  </scm-code>
29
30  This representation is convenient in the sense that they can be manipulated
31  directly using standard <scheme> routines on lists.
32
33  <paragraph*|Active documents and C++ trees><label|tree-active>
34
35  Active documents, like ones which are visible in one of the editors
36  windows, are rather represented using the internal C++ type
37  <verbatim|tree>, which has been exported to <scheme> via the glue. When a
38  tree is part of a real document inside the editor, the tree is aware about
39  its position inside the document. Using routines from the tree API, you may
40  then make changes in the document simply by assigning new values to the
41  tree.
42
43  For instance, consider the following experiment: open two windows and start
44  a <scheme> session in each window. In the second window, enter the lines
45
46  <\session|scheme|default>
47    <\input|scheme] >
48      (use-modules (utils library tree))
49    </input>
50
51    <\input|scheme] >
52      (define t (buffer-tree))
53    </input>
54  </session>
55
56  In the first window, you may now modify the document in the second window
57  using commands like
58
59  <\session|scheme|default>
60    <\input|scheme] >
61      (tree-set! t (tree 'document (string-\<gtr\>tree "First line.")
62
63      \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ (string-\<gtr\>tree
64      "Second line.")))
65    </input>
66
67    <\input|scheme] >
68      (tree-set t 1 (string-\<gtr\>tree "New second line."))
69    </input>
70
71    <\input|scheme] >
72      (tree-set t 0 (tree 'strong (tree-ref t 0)))
73    </input>
74  </session>
75
76  <paragraph*|A common framework><label|tree-hybrid>
77
78  From the last three lines in above experiment, it becomes apparent that it
79  is quite cumbersome to manipulate trees using the standard tree
80  constructors. For this reason, <TeXmacs> provides a hybrid type
81  <verbatim|content> for manipulating scheme trees and C++ trees in a common
82  framework. For instance, the last three lines in the above experiment may
83  be replaced by
84
85  <\session|scheme|default>
86    <\input|scheme] >
87      (tree-set! t '(document "First line." "Second line."))
88    </input>
89
90    <\input|scheme] >
91      (tree-set t 1 "New second line.")
92    </input>
93
94    <\input|scheme] >
95      (tree-set t 0 `(strong ,(tree-ref t 0)))
96    </input>
97  </session>
98
99  More precisely, a scheme expression of the type <verbatim|content> is
100  either a string, a tree or a list whose first element is a symbol and whose
101  remaining elements are other expressions of type <verbatim|content>.
102  <TeXmacs> provides several routines (usually prefixed by <verbatim|tm->)
103  for basic operations on content, like <scm|tm-car>, <scm|tm-arity>,
104  <scm|tm-\<gtr\>list>, <scm|tm-equal?>, etc. Most higher level routines are
105  built on top of these routines, so as to accept arguments of type
106  <verbatim|content> whenever appropriate.
107
108  <paragraph*|Persistent positions inside trees>
109
110  Besides the fact that trees remember their <em|positions> inside the global
111  edit tree, it is also possible to create cursor positions inside the global
112  edit tree, which are naturally updated when modifications take place. This
113  technique is useful when you want to write an editing routine which does
114  not act locally at the cursor position. For instance, the following routine
115  can be used to insert content at the start of the current buffer in a
116  reliable way:
117
118  <\scm-code>
119    (define (insert-at-buffer-start t)
120
121    \ \ (with-cursor (path-start (root-tree) (buffer-path))
122
123    \ \ \ \ (insert t)))
124  </scm-code>
125
126  The <scm|with-cursor> macro temporarily changes the cursor position, while
127  storing the old cursor position in such a way that it will be updated
128  during changes of the document. The user may also use the more explicit
129  routines <scm|position-new>, <scm|position-delete>, <scm|position-set> and
130  <scm|position-get> to manage persistent positions.
131
132  <tmdoc-copyright|2005|Joris van der Hoeven>
133
134  <tmdoc-license|Permission is granted to copy, distribute and/or modify this
135  document under the terms of the GNU Free Documentation License, Version 1.1
136  or any later version published by the Free Software Foundation; with no
137  Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
138  Texts. A copy of the license is included in the section entitled "GNU Free
139  Documentation License".>
140</body>
141
142<initial|<\collection>
143</collection>>