Source Browser ?

1% language=us runpath=texruns:manuals/cld
2
3% maybe this will become a section instead
4
5\startcomponent cld-logging
6
7\environment cld-environment
8
9\startchapter[title={Logging}]
10
11Logging and localized messages have always been rather standardized in \CONTEXT,
12so upgrading the related mechanism had been quite doable. In \MKIV\ for a while
13we had two systems in parallel: the old one, mostly targeted at messages at the
14\TEX\ end, and a new one used at the \LUA\ end. But when more and more hybrid
15code showed up, integrating both systems made sense.
16
17Most logging concerns tracing and can be turned on and off on demand. This kind
18of control is now possible for all messages. Given that the right interfaces are
19used, you can turn off all messages:
20
21\starttyping
22context --silent
23\stoptyping
24
25This was already possible in \MKII, but there \TEX's own messages still were
26visible. More important is that we have control:
27
28\starttyping
29context --silent=structure*,resolve*,font*
30\stoptyping
31
32This will disable all reporting for these three categories. It is also possible
33to only disable messages to the console:
34
35\starttyping
36context --noconsole
37\stoptyping
38
39In \CONTEXT\ you can use directives:
40
41\starttyping
42\enabledirectives[logs.blocked=structure*,resolve*,font*]
43\enabledirectives[logs.target=file]
44\stoptyping
45
46As all logging is under \LUA\ control and because this (and other) kind of
47control has to kick in early in the initialization the code might look somewhat
48tricky. Users won't notice this because they only deal with the formal interface.
49Here we will only discuss the \LUA\ interfaces.
50
51Messages related to tracing are done as follows:
52
53\starttyping
54local report_whatever = logs.reporter("modules","whatever")
55
56report_whatever("not found: %s","this or that")
57\stoptyping
58
59The first line defined a logger in the category \type {modules}. You can give a
60second argument as well, the subcategory. Both will be shown as part of the
61message, of which an example is given in the second line.
62
63These messages are shown directly, that is, when the function is called. However,
64when you generate \TEX\ code, as we discuss in this document, you need to make
65sure that the message is synchronized with that code. This can be done with a
66messenger instead of a reporter.
67
68\starttyping
69local report_numbers = logs.reporter("numbers","check")
70local status_numbers = logs.messenger("numbers","check")
71
72status_numbers("number 1: %s, number 2: %s",123,456)
73report_numbers("number 1: %s, number 2: %s",456,123)
74\stoptyping
75
76Both reporters and messages are localized when the pattern given as first
77argument can be found in the \type {patterns} subtable of the interface messages.
78Categories and subcategories are also translated, but these are looked up in the
79\type {translations} subtable. So in the case of
80
81\starttyping
82report_whatever("found: %s",filename)
83report_whatever("not found: %s",filename)
84\stoptyping
85
86you should not be surprised if it gets translated. Of course the category and
87subcategory provide some contextual information.
88
89\stopchapter
90
91\stopcomponent
92