1
2
3
4
5
6
7\startcomponent musingsmanuals
8
9\environment musingsstyle
10
11\startchapter[title={About manuals}]
12
13\startsection[title={Introduction}]
14
15Im always puzzled when I read that someone wonders if \CONTEXT\ is still up to
16date or maintained because some manual has a timestamp of a decade ago. Im also
17puzzled by some rants you can run into when searching the web. In the next few
18paragraphs Ill comment on this.
19
20\stopsection
21
22\startsection[title={Stability}]
23
24Say that youre an enthusiastic user of console commands like \type {ls} (\type
25{dir}), \type {cp} (\type {copy}) or maybe \type {ssh}, \type {rsync}, \type
26{curl}. How often do you consult a manual on how they evolve? And say that you,
27for some reason, do consult a manual, there is a good change that it is
28pretty old. Does that mean that the commands are obsolete? The binaries probably
29get fixed for bugs but the interface stays the same, which is what you expect.
30Every time we generate a zip for the \CONTEXT\ distribution, the related website
31also gets generated, using a bunch of \XML\ files that get transformed to \HTML\
32using \XSLT\ and a pretty ancient version of \type {xsltproc} (why should I
33update). I never check for a new manual as it keeps doing the job. And additional
34manuals and reports get added.
35
36So, once some functionality is stable, and a lot of macro code in \CONTEXT\ is
37just that, there is no need to update a manual! Putting a new time stamp on it is
38basically fake updating. And often the more introductionary kind of manuals dont
39need to be updated at all, apart from maybe cultural changes that demand a
40(political correct) update. Them being a bit old and not being updated is
41actually a good thing as it signals stability.
42
43It is worth mentioning that the \CONTEXT\ distribution is not the only source of
44information. There are manuals written by others and there is the Wiki. All is
45the work of volunteers and updating all that depends on how much time one can
46allocate.
47
48\stopsection
49
50\startsection[title={Excuses}]
51
52It is a fact that \CONTEXT\ evolves. New functionality gets added and some
53mechanism get extended. Often these are described in dedicated manuals or
54articles that end up in collections, and there are plenty of them in the
55distribution. For some reason those complaining about a beginners manual with an
56old time stamp dont check if there is more, and there is quite some more! Dont
57only look at the \CONTEXT\ garden (the wiki) but also keep an eye on what gets
58distributed. Some users are very good in track of what gets added, because
59sometimes I get fixes for typos send within a few hours after uploading a zip.
60
61We appreciate that other users point out that writing manuals takes time and that
62indeed our time is not without limits. If I could sit down and write manuals
63whole day, and it would get paid, I might do it. But it is a fact that
64development of \CONTEXT\ is not paid for at all. I can work on it in company time
65but much happens in spare time. Most development is a gamble on future use or
66done because we want to be complete or because code can be improved. So, writing
67a manual then closely relates to what we like doing: it determines the topics and
68priorities. If something gets explored and ends up in new functionality then that
69gets documented in the process. It is the fun factor that drives it. The same is
70true for \LUATEX\ development.
71
72So, we have as valid excuse that new manuals relate to (new) functionality and
73old ones stay as they are. Don Knuth remarks somewhere that writing a manual as
74part of the development is a good thing. We fully agree with that.
75
76\stopsection
77
78\startsection[title={Cutting edge}]
79
80Does an old manual indicate that nothing happens? Definitely not. Over a decade
81of \LUATEX\ development is closely related to \CONTEXT\ and there is plenty of
82reporting about that. Does that mean that we need to rewrite manuals? No,
83existing functionality remains. And of course users are free to come up with
84more detailed manuals (which they seldom do). Some developments get published
85in user group journals but we dont publish much about specific \CONTEXT\ features
86and usage because its hard to do that for a diverse audience.
87
88Currently we have what is called \CONTEXT\ \MKXL\ (aka \LMTX), but we also have
89the prelude to that, \MKIV, and the frozen predecessor \MKII. Apart from changes in
90technology (most noticeably fonts and encodings) the functionality is accumulative:
91most old manuals (unless they are specialized into old school fonts for instance)
92apply to the latest greatest version.
93
94It is a misunderstanding that the development of \CONTEXT, \LUATEX\ and
95\LUAMETATEX\ is somehow funded by projects that we do. This is not true. We can
96apply both in projects but as we charge by the hour (or day) no customer ever
97sees development on the bill. Of course during a project we can gain on
98efficiency (so then development pays back) and because we know the system style
99writing is efficient too. In fact, in most cases our customers dont know or care
100what tool we use because tools are expected to be part of the deal. Most projects
101we can (and could) only do because we can use \CONTEXT\ and that is a side effect
102of the fact that we do develop beforehand. Were often the only technically
103andor affordable way out. Its a chickenegg issue: we have a tool and
104therefore get a project. We never get a projects where we can develop a tool. No
105one pays for \TEX\ development or at least no one ever came to us with specific
106\TEX\ related demands. It looks like the world takes it for granted that \TEX\ is
107just there. \footnote {There are a few subcomponents of \CONTEXT\ that were
108partially sponsored by users and we do have some support contracts that permit
109experiments and development.}
110
111The reason for \CONTEXT\ being cutting edge (in terms of \TEX) is that we like
112challenges, that users demand features that are interesting to explore and that
113weve been part of the \TEX\ scenery for a while now. We just like that.
114
115Its good to know that \CONTEXT\ was and is developed as a toolkit. We started
116long ago because we needed a way to quickly create and update reports of meetings
117that we chaired. Next we needed a way to efficiently produce high quality
118education materials (of various kind) and support maintenance of sets of related
119(quality assurance) manuals. We could have used wordstar, wordperfect or msword
120but liked the \TEX\ way much more. As said, most customers didnt even know or
121care what tool was used because the (often highly interactive \PDF) outcome
122mattered most. In fact, we would not be interested in this kind of work if we
123were forced to use clumsy tools, but for sure a lot can be done with those as
124well.
125
126\stopsection
127
128\startsection[title={Continuity}]
129
130Most development happens at \PRAGMA\ by me (Hans) with help from my two
131colleagues (Ton and Kees) and the community (Aditya, Alan, Mikael, Mojca, Luigi,
132Hraban, Taco, Thomas, Tomas, Willi, Wolfgang, and others). \footnote {More names
133could be here as I write this in 2022.} I wont mention those on the mailing list
134who contribute with ideas, testing and support, but they cant be missed. The
135biggest danger for continuity is a polluted code base where everyone just pushed
136code into a repository. So this is closely guarded. A user patch might work well
137for that user but can break something else.
138
139With \TEX\ you need to keep in mind that once a solution works there is no need
140to update code or manuals. As long as there is a working \LUATEX\ (\LUAMETATEX)
141binary youre fine. Maybe if some specific fonts are used, a filename might need
142to be adapted.
143
144An example. When we added a new \XML\ subsystem to \CONTEXT\ \MKIV\ we knew that
145some day we could use it. We now uses it in a few projects and Im pretty sure
146that we would not do these projects otherwise as it would demand writing quite
147complex \XSLT\ style sheets that then would have to be applied to thousands of
148files per run. To some extend what is available in \CONTEXT\ sort of drives the
149kind of work you look for. That said: if you consider using \CONTEXT\ for simple
150or complex documents, either of not in a collection, either or not using \TEX\ or
151\XML\ input you can be assured that this will work (and might even get better)
152because we use it ourselves.
153
154If you want to get an idea about development, just look at the (five) documents
155that describe the development of \LUATEX\ (\LUAMETATEX). Locating them in the
156distribution is a good opportunity to explore the documents. They will show you
157what happened the last decade(s) and give you some trust in \CONTEXT. Or come to
158a \CONTEXT\ meeting and meet those involved.
159
160\stopsection
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\startsection[title={Closing remark}]
211
212So next time someone asks if \CONTEXT\ is maintained because some old manual
213stays around, return the question if frequently updated manuals are a sign of
214stability. Also ask if someone looked a bit in the documentation tree. The oldest
215manual in the \TEX\ world is the \TEX book that describes the oldest stable set
216of macros: plain \TEX. There are happy users out there who love that stability.
217If it were not for the wonderful personality of Don Knuth this program would
218already been forgotten. I think that long term stability and unchanged code and
219manuals are something that we need to cherish and get accustomed to, which is not
220easy in a time when a phone and its operating system are outdated as soon as you
221unbox it. Its also not easy in a time of instant communication, more and more
222confused by what is called artificial intelligent mumbling, but thats for
223another wrapup.
224
225\stopsection
226
227\startlines
228Hans Hagen
229Hasselt NL
230
231(uncorrected so theres something left to complain)
232\stoplines
233
234\stopchapter
235
236\stopcomponent
237 |