summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/sources/general/manuals/start/en/ma-cb-en-figures.tex
blob: 90f2493594892ff65ad31508782dd107fc078778 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
\startcomponent ma-cb-en-figures

\enablemode[**en-us]

\project ma-cb

\startchapter[reference=figures,title=Figures]

\index{figure}
\seeindex{picture}{figure}
\index{floating blocks}

\Command{\tex{placefigure}}
\Command{\tex{startfiguretext}}
\Command{\tex{setupfigures}}
\Command{\tex{startcombination}}
\Command{\tex{setupfloats}}
\Command{\tex{setupcaptions}}
\Command{\tex{externalfigure}}

Images can be placed in your document with the command \type{\externalfigure}.

\startbuffer
\externalfigure
  [cow.pdf]
  [width=.1\textwidth,
   frame=on,
   framecolor=gray,
   frameoffset=3pt,
   rulethickness=3pt,
   framecorner=round]
\stopbuffer

\typebuffer

Such an image will be placed on the location where you defined it \space \getbuffer
\space and can have some strange effects on the surrounding white space. By the way,
the cow image is always available for \CONTEXT\ users which is very convenient when
you are testing the figure related commands.

You can use the command \type{\placefigure} to influence the positioning of
images in your document.

\startbuffer
\placefigure
   [][fig:church]
   {Stephanus Church.}
   {\externalfigure[ma-cb-24][width=.4\textwidth]}
\stopbuffer

\typebuffer

After processing this will come out as \in{figure}[fig:church] at the first
available location.

\getbuffer

The command \type{\placefigure} handles numbering and vertical spacing before and
after your figure. Furthermore this command initializes a float mechanism, which
means that \CONTEXT\ looks whether there is enough space for your figure on the
page. If not, the figure will be placed at another location and the text carries
on, while the figure floats in your document until the optimal location is found.
You can influence this mechanism within the first bracket
pair.

The command \type{\placefigure} is a predefined example of:

\shortsetup{placefloat}

A number of basic options is described in \in{table}[tab:placefigure].

\placetable
  [here]
  [tab:placefigure]
  {Options in \type{\placefigure}.}
\starttable[|l|l|]
\HL
\NC \bf Option \NC \bf Meaning                             \NC\SR
\HL
\NC here       \NC put figure at this location if possible \NC\FR
\NC force      \NC force figure placement here             \NC\MR
\NC page       \NC put figure on its own page              \NC\MR
\NC top        \NC put the figure at the top of the page   \NC\MR
\NC bottom     \NC put the figure at the botom of the page \NC\MR
\NC left       \NC place figure at the left margin         \NC\MR
\NC right      \NC place figure at the right margin        \NC\MR
\NC margin     \NC place figure in the margin              \NC\MR
\NC none       \NC set no caption                          \NC\LR
\HL
\stoptable

The second bracket pair is used for cross-referencing. You can refer to this
particular figure by typing:

\starttyping
\in{figure}[fig:church]
\stoptyping

The first brace pair is used for the caption. You can type any text you want. The
figure labels are set up with \type{\setupcaptions} and the numbering is (re)set
by \type{\setupnumbering} (see \in{paragraph}[floatingblocks]).

The second brace pair is used for defining the figure and addressing the file
names of external figures.

In the next example you see how \inframed{Hasselt} is defined within
the last brace pair to show you the function of \type{\placefigure{}{}}.

\startbuffer
\placefigure
  {The boundaries of Hasselt.}
  {\framed{\tfd Hasselt}}
\stopbuffer

\typebuffer

This will produce:

\getbuffer

However, your images are often created using programs like Illustrator and photos
are --- after scanning --- improved in packages like PhotoShop. Then the images
are available as files. \CONTEXT\ supports image file types like \type {JPG},
\type {PNG} and (pages from) \type {PDF} files as well as \METAPOST\ output
(\type {MPS} files). Users normally can trust \CONTEXT\ to find the best possible
file type.

In \in{figure}[fig:canals] you see a photo and a graphic combined into one
figure.

\startbuffer
\placefigure
  [here,force]
  [fig:canals]
  {The Hasselt Canals.}
  {\startcombination[2*1]
    {\externalfigure[ma-cb-03][width=.4\textwidth]}{a bitmap picture}
    {\externalfigure[ma-cb-00][width=.4\textwidth]}{a vector graphic}
   \stopcombination}
\stopbuffer

\getbuffer

You can produce this figure by typing something like:

\typebuffer

In this figure two pictures are combined with:

\shortsetup{startcombination}

The \type{\start ...\stopcombination} pair is used for
combining two pictures in one figure. You can type the number of pictures within
the bracket pair. If you want to display one picture below the other you would
have typed \type{[1*2]}. You can imagine what happens when you combine 6~pictures
as \type{[3*2]} (\type{[rows*columns]}).

The examples shown above are enough for creating illustrated documents. Sometimes
however you want a more integrated layout of the picture and the text. For that
purpose you can use \type{\start ...\stopfiguretext} command pair.

\startbuffer
\startfiguretext
  [left,none]
  [fig:citizens]
  {}
  {\externalfigure[ma-cb-18][width=.5\makeupwidth]}
   Hasselt has always had a varying number of citizens due to
   economic events. For example the Dedemsvaart was dug around
   1810. This canal runs through Hasselt and therefore trade
   flourished. This led to a population growth of almost 40\%
   within 10~years. Nowadays the Dedemsvaart has no commercial
   value anymore and the canals have become a tourist
   attraction. But reminders of these prosperous times can be
   found everywhere.
\stopfiguretext
\stopbuffer

The effect of:

\typebuffer

is shown in the figure below.

\start
\setuptolerance[verytolerant]
\getbuffer
\stop


\startbuffer[marginpicture]
\inmargin
  {\externalfigure
     [ma-cb-23]
     [width=.7\marginwidth]}
\stopbuffer

As you have seen you in the examples above you can summon a figure with the
command:

\shortsetup{externalfigure}

The command \type{\externalfigure} has two bracket pairs. The first is used for
the exact file name without extension, the second for file formats and
dimensions. It is not difficult to guess what happens if you
type:\getbuffer[marginpicture]

\typebuffer[marginpicture]

You can set up the layout of figures with:

\shortsetup{setupfloats}

You can set up the numbering and the labels with:

\shortsetup{setupcaptions}

\startbuffer[figuresetups]
\setupfloat
  [figure]
  [default=right,
   spacebefore=none]

\setupcaptions
  [location=bottom,
   style=boldslanted]
\stopbuffer

\startbuffer[figuredefinition]
\placefigure
  {A characteristic view on Hasselt.}
  {\externalfigure[ma-cb-12][width=6cm]}
\stopbuffer

\start
\getbuffer[figuresetups]
\getbuffer[figuredefinition]
\stop

These commands are typed in the set up area of your input file and have a global
effect on all floating blocks.

\typebuffer[figuresetups,figuredefinition]

For figure management there are commands like \crlf
\type{\setupexternalfigure}.

Please refer to the \goto {\CONTEXTWIKI} [
url(http://wiki.contextgarden.net/Command/defineexternalfigure) ] for practical
applications of these commands.

If you want to work with a \XML\ based figure database please see the \goto
{Figures} [ url (manual:figures) ]
manual.

\stopchapter

\stopcomponent