mag-1101-mkiv.tex /size: 6677 b    last modification: 2023-12-21 09:43
1% language=us
2
3% author    : Hans Hagen
4% copyright : ConTeXt Development Team
5% license   : Creative Commons Attribution ShareAlike 4.0 International
6% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
7% origin    : the ConTeXt distribution
8%
9% comment   : Because this manual is distributed with TeX distributions it comes with a rather
10%             liberal license. We try to adapt these documents to upgrades in the (sub)systems
11%             that they describe. Using parts of the content otherwise can therefore conflict
12%             with existing functionality and we cannot be held responsible for that. Many of
13%             the manuals contain characteristic graphics and personal notes or examples that
14%             make no sense when used out-of-context.
15%
16% comment   : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt
17%             Group journal or otherwise. Thanks to the editors for corrections. Also thanks
18%             to users for testing, feedback and corrections.
19
20\usemodule[mag-01,abr-02,job-01]
21
22\startbuffer[abstract]
23    For a long time already \CONTEXT\ provides a way to organize your document(s)
24    in a structure that permits processing of components. This mechanism has been
25    upgraded a bit in \MKIV\ and here we will summarize the status quo.
26\stopbuffer
27
28\startdocument
29  [title={Project Structure},
30   author=Hans Hagen,
31   affiliation=PRAGMA ADE,
32   date=July 2011,
33   number=1101 \MKIV]
34
35A regular document has a simple structure. When we talk about structure here, we
36only refer to the overall document structure.
37
38\startscite[tex]
39% style specification
40
41\starttext
42  % the document content
43\stoptext
44\stopscite
45
46For practical reasons we delay initial font loading till the first \type
47{\starttext} so that one can overload the defaults. This means that when no
48bodyfont is specified, and {\starttext} is not given, there will be hardly any
49visible output.
50
51An example of a more elaborate structure is the following:
52
53% \enabletrackers[context.trace]
54
55\startscite[tex]
56\environment environment-1
57\environment environment-2
58
59\startproduct product-1
60
61  \component component-1.tex
62  \component component-2.mkiv
63  \component component-3.cld
64
65  \component component-1
66  \component component-2
67
68\stopproduct
69\stopscite
70
71Here we have a specific product, made up out of components and using a few
72environment files that specify the style. By default we assume tex files, but you
73can be specific and use known suffixes. A less abstract example is the following:
74
75\startscite[tex]
76\environment my-fonts
77\environment my-style
78\environment my-abbreviations
79\environment my-urls
80
81\startproduct manual
82
83  \component titlepage
84  \component contents
85
86  \component chapter-1
87  \component chapter-2
88  \component chapter-3
89
90  \component index
91
92\stopproduct
93\stopscite
94
95You can process components and products independently but be aware that you won't
96get cross document (or chapter) references then.
97
98There is one more level: projects.
99
100\startscite[tex]
101\environment my-fonts
102\environment my-style
103\environment my-abbreviations
104\environment my-urls
105
106\startproject documentation
107
108  \product manual
109  \product faqs
110
111\stopproject
112\stopscite
113
114This means that we can also define the manual as follows:
115
116\startscite[tex]
117\project documentation
118
119\startproduct manual
120
121  \component titlepage
122  \component contents
123
124  \component chapter-1
125  \component chapter-2
126  \component chapter-3
127
128  \component index
129
130\stopproduct
131\stopscite
132
133Environments are only loaded once and when you run a component or product that
134refers to environments or when environments are picked up from an encapsulating
135structure you need to be aware of the order of loading.
136
137The names given after the start command are not that important but the names
138after the simple commands refer to filenames, so in the next case there need to
139be a file called \type {index.tex}:
140
141\startscite[tex]
142\component index
143\stopscite
144
145Equally valid is:
146
147\startscite[tex]
148\component[index]
149\stopscite
150
151Subpaths are also permitted:
152
153\startscite[tex]
154\component manual/index
155\stopscite
156
157The meaning of the mentioned commands is not frozen but adapts itself to the
158current situation. A file can be processed many times, only once or never. The
159following table shows what will happen when:
160
161\ctxlua{moduledata.jobs.showprocessors()}
162
163When you load an environment or component, you can specify it to be a \LUA\ file
164by using the \type {lua} or \type {cld} suffix. In that case the file will be
165loaded in the right way. From the table you can deduce that the following is also
166valid:
167
168\startscite[tex]
169\environment mystyle
170
171\starttext
172  % the content
173\stoptext
174\stopscite
175
176combined with:
177
178\startscite[tex]
179\startenvironment mystyle
180  % the definitions
181\stopenvironment
182\stopscite
183
184This is about the simplest structure that you can use that still gives a bit of
185abstraction.
186
187In addition to files in a project structure, you can load predefined modules.
188
189\startscite[tex]
190\usemodule[mathml]
191\stopscite
192
193or more specific:
194
195\startscite[tex]
196\usemodule[x][mathml]
197\stopscite
198
199Which limits the lookup to the \type {x} namespace. The first match quits the
200search and the order of lookups is: \type {mkvi}, \type {mkiv}, \type {tex},
201\type {cld}, \type {lua}. It follows that modules can be \LUA\ files.
202
203When you use structure in the files you will find an overview in the log file.
204This looks as follows:
205
206\starttyping
207system          > structure > start used structure
208
209used structure  > text: product-1
210used structure  >   environment: environment-1
211used structure  >   environment: environment-2
212used structure  >   product: product-1
213used structure  >     component: component-1
214used structure  >     component: component-2
215used structure  >     component: component-1
216used structure  >     component: component-2
217
218system          > structure > stop used structure
219\stoptyping
220
221Some basic logging on the console can be enabled with:
222
223\startscite[tex]
224\enabletrackers[system.jobfiles]
225\stopscite
226
227A new command pair is the following:
228
229\starttyping
230\startdocument[settings]
231    structured content
232\stopdocument
233\stoptyping
234
235The settings are key|/|value pairs and the values can be retrieved using:
236
237\starttyping
238\documentvariable{key}
239\stoptyping
240
241You can set \type {before} and \type {after} parameters and by default these are
242set up as follows:
243
244\starttyping
245\setvariables
246  [document]
247  [before=\directsetup{document:start},
248   after=\directsetup{document:stop}]
249\stoptyping
250
251You can for instance define these setups to generate a title page (using document
252variables) and a colophon page. In the future more functionality might be added.
253
254\stopdocument
255