Source Browser ?

1% language=us runpath=texruns:manuals/musings
2
3% \showfontkerns
4
5% \setupalign[granular]
6
7\startcomponent musings-manuals
8
9\environment musings-style
10
11\startchapter[title={About manuals}]
12
13\startsection[title={Introduction}]
14
15I'm 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. I'm also
17puzzled by some rants you can run into when searching the web. In the next few
18paragraphs I'll comment on this.
19
20\stopsection
21
22\startsection[title={Stability}]
23
24Say that you're 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 don't
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 don't check if there is more, and there is quite some more! Don't
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 don't publish much about specific \CONTEXT\ features
86and usage because it's 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 don't 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. We're often the only technically
103and|/|or affordable way out. It's a chicken|-|egg 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
113we've been part of the \TEX\ scenery for a while now. We just like that.
114
115It's 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 didn't 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 won't mention those on the mailing list
134who contribute with ideas, testing and support, but they can't 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 you're 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 I'm 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% \startsection[title={Stay away}]
163%
164% There are reasons why you won't find us (me) on some social media. First of all
165% we like using the mailing list. It puts some time between what one thinks or
166% wants to ask and actually getting it out in the open. After all, one might regret
167% a too spontaneous complain or even rant, so it sort of protects subscribers.
168%
169% It is not that hard to search the web (say Reddit) and find someone complaining
170% about something \TEX\ (or \CONTEXT) related, including \type {f**ck} kind of
171% wording. If you're in that category, please stay away from \CONTEXT\ or try to
172% constrain yourself. It won't trigger help. Why on earth does one rant about a
173% system that one doesn't like unless maybe one is enforced to use it. We prefer 10
174% out of 10000 \TEX\ users using \CONTEXT\ over 1000 of which 990 are unhappy: use
175% another macro package and be part of the possible unhappy crowd there. We're not
176% selling a product, we're sharing a potential useful tool! Also keep in mind that
177% (as I know a bit about \TEX\ and its ecosystem) it would be very easy for me to
178% counter you if I really wanted that; it might make you look ridiculous.
179%
180% That said, we see no benefit in being on Facebook. I never look for something
181% there myself I'm too unfamiliar with it, I have nothing to share and and don't
182% look forward to keeping something up to date. There is no need for an instant
183% news channel on Whatsapp, Instagram, Telegram, Tiktok or other media that are
184% driven by advertisements and filtering user data. We could post tutorials on
185% YouTube but don't. It is already bad enough that I have to endure advertisements
186% myself, let alone that users get bombarded by unrelated crap. We could have a
187% fancy website and try to sell \CONTEXT\ \quote {professional} or present some
188% \quote {plans}, but we like to keep it simple: the site is generated when we push
189% an update and has been for decades so little work is involved in that. We don't
190% keep statistics, let alone have trackers. I see no benefit in it and I don't
191% like to waste time on that either.
192%
193% We are not on Stack Exchange but other \CONTEXT\ developers post very nice
194% \CONTEXT\ answers there. Personally I just don't like a system with likes, votes,
195% counters and somewhat persistent old (sometimes confusing) stuff. But I'm
196% thankful for others who can deal with it.
197%
198% We could have a Patreon account but that's not how we work here and from seeing
199% how it is used it would make me feel uncomfortable anyway. In a similar fashion
200% we don't see benefits in commercializing the Github repository. Those who need
201% support or and want to support development can find us if they want to.
202%
203% We have always participated in \TEX\ meetings and publish in use group journals
204% about developments and such. We also have always been pretty active in the
205% community and like it there. Just stay away from it when ranting is all you can
206% contribute.
207%
208% \stopsection
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. It's also not easy in a time of instant communication, more and more
222confused by what is called artificial intelligent mumbling, but that's for
223another wrapup.
224
225\stopsection
226
227\startlines
228Hans Hagen
229Hasselt NL
230
231(uncorrected so there's something left to complain)
232\stoplines
233
234\stopchapter
235
236\stopcomponent
237