Debian Codegraph @

texmf-dist/doc/latex/tkz-elements/TKZdoc-elements-convention.tex

raw
1 \newpage
2
3 \section{Writing Convention, best practices and common mistakes}
4 \subsection{Assigning a Name to an Object}
5
6 \textbf{Note:} Certain variables such as \tkzname{z}, \tkzname{L}, \tkzname{T}, etc. are reserved for storing geometric objects.
7 Reassigning one of them (e.g., \tkzname{L = 4}) will overwrite its content and disrupt the system.
8
9 Points are a special case: they must be stored in the table \tkzname{z}.
10 For all other geometric objects, it is strongly recommended to follow the predefined variable names.
11 Avoid mixing naming conventions or inventing your own identifiers, as this may lead to unpredictable behavior.
12
13 \vspace{1em}
14 \tkzRHand{\textcolor{red}{Warning}}: Do not reuse names such as \texttt{point}, \texttt{line}, \texttt{circle}, \texttt{path}, \texttt{triangle}, etc., as variable names.
15 These identifiers are reserved internally by \tkzNamePack{tkz-elements} to represent object constructors.
16
17 \vspace{1em}
18 Below is the list of reserved classes and the default variable names associated with them:
19 \label{list of reserved classes}
20
21 \vspace{1em}
22 \textcolor{red}{\directlua{
23 local variables = {"A", "C", "CO", "F", "PF", "L", "LP", "M", "O", "P", "PA", "z", "Q", "R", "RP", "S", "T", "V"}
24 local modules = {"angle", "circle", "conic", "fct", "pfct", "line", "list\\_point", "matrix", "occs", "parallelogram", "path", "point", "quadrilateral", "rectangle", "regular\\_polygon", "square", "triangle", "vector"}
25 for i = 1, utils.table_getn(modules) do
26 local class = modules[i]
27 local var = variables[i]
28 tex.sprint( class.. " --> ".. var.."\\\\")
29 end
30 } }
31
32 \subsection{Best practices}
33
34 It is preferable to use methods—or better yet, object attributes—rather than standalone functions.
35
36 For example, to determine the midpoint of a segment $AB$, it was previously possible to write:
37
38 |z.m = midpoint(z.A, z.B)|. This is now considered incorrect: you must use
39
40 |z.m = tkz.midpoint(z.A, z.B)|.
41
42 However, the recommended approach is to define the segment first with:
43
44 |L.AB = line(z.A, z.B)|, and then use the attribute:
45
46 |z.m = L.AB.mid|. If you don't reuse the line, a one-liner like |z.m = line(z.A, z.B).mid| is acceptable.
47
48 \vspace{12pt}
49 Similarly, it may have been tempting to write |L.bi = tkz.bisector(z.A, z.B, z.C)| to obtain the angle bisector at vertex $A$. As in the previous example, this is no longer valid. You must now use:
50
51 |L.bi = tkz.bisector(z.A, z.B, z.C)|, as all standalone functions have been grouped under the |tkz| module.
52
53 A better practice is to define the triangle $ABC$ using:
54
55 |T.ABC = triangle(z.A, z.B, z.C)| and then access the bisector via:
56
57 |L.bi = T.ABC:bisector(z.A)| or directly:
58
59 |L.bi = triangle(z.A, z.B, z.C):bisector(z.A)|.
60
61 \subsection{Common mistakes and best practices}
62
63 \vspace{1em}
64 \tkzRHand{\textcolor{red}{Second Warning}}: Let's examine the consequences of incorrect assignments. The following example is very simple: we define two points, the line passing through them, and a line orthogonal to the first at one of the points. To define these objects, we use two tables (or classes): \tkzname{z} and \tkzname{L}.
65
66 Here is the correct code:
67 \begin{mybox}{}
68 \begin{tkzexample}[latex=.5\textwidth]
69 \directlua{
70 z.A = point(1, 2)
71 z.B = point(3, -1)
72 L.AB = line(z.A, z.B)
73 -- blunders
74 L.ortho = L.AB:ortho_from(z.B)
75 z.C = L.ortho.pb
76 }
77 \begin{tikzpicture}[scale = .75]
78 \tkzGetNodes
79 \tkzDrawLines(A,B B,C)
80 \tkzDrawPoints(A,B)
81 \end{tikzpicture}
82 \end{tkzexample}
83 \end{mybox}
84
85 \begin{itemize}
86 \item \textbf{First blunder:} \tkzname{z = nil} or \tkzname{z = 4}. You've reassigned the \tkzname{z} variable. It no longer refers to a table, but to a number. Its type has changed, and the system can no longer access the points.
87 \item \tkzname{z.A = 4} is equally problematic: you’ve overwritten point $A$. If your intention is to remove point $A$, then use \tkzname{z.A = nil} instead.
88 \item \tkzname{L = 4}. This might seem convenient to store a length, but doing so will erase the entire table of lines.
89 \item \tkzname{L.ortho = ortho}. A more subtle mistake: if \tkzname{ortho} is not defined, you lose your line. If it is defined but of the wrong type, an error will occur.
90 \item For objects other than points, incorrect assignments at the end of the process may not affect the figure. It is possible to clean up tables before plotting. However, the \tkzname{z} table must not be altered. Only points not used for plotting should be deleted.
91 \end{itemize}
92
93 These precautions help ensure consistency in the system and prevent unpredictable behavior.
94
95 \vspace{1em}
96 We’ll now explain how to assign variable names for each type of object.
97
98
99 \subsection{Assigning a Name to a Point}
100
101 Points must be stored in the table \tkzname{z} if you intend to use them
102 later in \tkzNamePack{\TIKZ} or \tkzNamePack{tkz-euclide}.
103 In \tkzNamePack{tkz-elements}, all points follow the convention
104 \tkzname{z.name}, where \tkzname{name} is the intended node label.
105
106 \medskip
107 When transferring points to \TIKZ{} using \tkzcname{tkzGetNodes},
108 each entry \code{z.name} produces the corresponding coordinate:
109
110 \begin{mybox}
111 \verb|\coordinate (name) at (x,y);|
112 \end{mybox}
113
114 Some naming cases require attention, particularly those involving primes.
115
116 \paragraph{Prime notation.}
117
118 The macro \tkzcname{tkzGetNodes} converts certain terminal patterns in
119 Lua names into prime or double-prime notation in \TIKZ.
120
121 \begin{itemize}
122 \item A name ending in \code{p} becomes a single prime:
123 \begin{mybox}
124 \verb|z.Bp = point(...)| → node \verb|(B')|
125 \end{mybox}
126
127 \item A name ending in \code{pp} becomes a double prime:
128 \begin{mybox}
129 \verb|z.Bpp = point(...)| → node \verb|(B'')|
130 \end{mybox}
131 \end{itemize}
132
133 This convention is convenient for geometric constructions but may lead to
134 unexpected renaming if the final \code{p} or \code{pp} is not intended
135 as prime notation.
136
137 \begin{tcolorbox}[colback=red!7,colframe=red!60!black,title=Warning]
138 Avoid names ending with \code{p} or \code{pp} unless you explicitly want
139 prime or double-prime notation in \TIKZ.
140 \end{tcolorbox}
141
142 \medskip
143 You can work with all these names in the \code{lua} section, but an error will occur when transferring points to nodes with the \verb|\tkzGetNodes| macro. To avoid errors, use one of the solutions in the following paragraph. For \code{z.p}, simply using \code{z.P} is sufficient. The lowercase letter can be retrieved with \TIKZ{}.
144
145 \paragraph{Intermediate names.}
146
147 For readability or when working with long or descriptive names in Lua,
148 you may use an intermediate variable and optionally assign a short label
149 for the drawing.
150
151 For instance:
152
153 \begin{mybox}
154 \verb|local euler = point(...)|
155 \verb|z.E = euler|
156 \end{mybox}
157
158 Here, the point is internally stored under the clear name \code{euler},
159 but it appears as node \code{(E)} in \TIKZ.
160
161 If you prefer to keep the long name in both Lua and \TIKZ, simply write:
162
163 \begin{mybox}
164 \verb|z.euler = point(...)|
165 \end{mybox}
166
167 Alternatively, you may assign an alias at the \TIKZ{} level:
168
169 \begin{mybox}
170 \verb|\pgfnodealias{E}{euler}|
171 \end{mybox}
172
173 Possible also, Before the transfer, we use an accepted name such as \code{A} and remove the point \code{z.apollonius} with \verb|z.apollonius = nil|.
174
175 \begin{mybox}
176 \verb|z.A = z.apollonius|
177 \verb|z.apollonius = nil|
178 \end{mybox}
179
180
181
182 \paragraph{Valid examples.}\mbox{}
183
184 \begin{mybox}
185 \begin{itemize}
186 \item \verb|z.A = point(1,2)| → node \verb|(A)|
187 \item \verb|z.Bp = point(3,4)| → node \verb|(B')|
188 \item \verb|z.Cpp = point(5,1)| → node \verb|(C'')|
189 \item \verb|z.H_a = T.ABC:altitude()| → node \verb|(H_a)|
190 \item \verb|z.euler = T.ABC.eulercenter| → node \verb|(euler)|
191 \end{itemize}
192 \end{mybox}
193
194 Names may contain letters, digits, and “\_”.
195 Other characters should be avoided because they may not form valid TikZ
196 node names.
197
198 \paragraph{Lua reminder.}
199
200 Fields of the table \tkzname{z} may be accessed as:
201
202 \begin{itemize}
203 \item \verb|z.A| (sugar syntax), or
204 \item \verb|z["A"]|
205 \end{itemize}
206
207 Assigning \verb|z.A = nil| removes the point entirely.
208
209
210 \subsection{Assigning a Name to Other Objects}
211 For all geometric objects other than points, you are free to choose names. However, adopting consistent conventions greatly improves code readability and maintainability. To be more precise, each Lua code block is usually preceded by the call to the function \tkzFct{package}{init\_elements()}, whose role is to clear and reset the various tables (such as \tkzname{L}, \tkzname{C}, etc.).
212 If you choose to use custom variable names or structures, you are free to do so — but in that case, you are responsible for managing and cleaning your variables and tables manually to avoid conflicts or unintended behavior.
213
214 In this documentation, the following naming strategy is used:
215
216
217 Objects are stored in dedicated tables, each associated with a specific class.
218 These tables are represented by variables such as:
219 \begin{itemize}
220
221 \item \tkzname{L} for lines and segments
222 \item \tkzname{C} for circles
223 \item \tkzname{T} for triangles
224 \item \tkzname{CO} for conics (including ellipses, hyperbolas, and parabolas)
225
226 \item etc. See the list of reserved words [\ref{list of reserved classes}]
227 \end{itemize}
228
229 Here are some examples of naming conventions used:
230
231 \begin{itemize}
232 \item Lines (L):\\
233 The name reflects the two points defining the line.
234
235 Example: |L.AB = line(z.A, z.B)| -- line through A and B
236
237 \item Circle (C)\\
238 You can name a circle based on its defining points or its purpose.
239 Examples:
240 \begin{itemize}
241 \item C.AB --> Circle centered at A, passing through B
242 \item C.euler --> Euler circle
243 \item C.external --> External circle
244 \end{itemize}
245
246 \item Triangles (T)\\
247 Use vertex labels, or descriptive names when appropriate. Examples:
248
249 \begin{itemize}
250 \item T.ABC --> Triangle with vertices A, B, C
251 \item T.feuerbach --> Feuerbach triangle
252
253 \end{itemize}
254
255
256
257 \item Conics (CO)\\
258 The table CO can store various conics; use meaningful keys to indicate type and role.
259
260
261 \end{itemize}
262
263 Note: \emph{While you may choose other variable names or formats, following these conventions ensures that your code remains clear and easy to follow, especially when working with more complex figures.}
264
265 \subsection{Writing conventions for attributes, methods.}
266 \label{sub:writing_conventions_for_attributes_methods_and_functions}
267
268 You must follow standard Lua conventions when accessing attributes or invoking methods:
269
270 \begin{itemize}
271 \item \textbf{Attributes} are accessed using the dot notation: \verb|object.attribute|.
272 \begin{itemize}
273 \item For example, to access the coordinates of point \verb|A|, use \verb|z.A.re| for the abscissa and \verb|z.A.im| for the ordinate.
274 \item To get the type of the object, write \verb|z.A.type|.
275 \item To retrieve the south pole of the circle \verb|C.OA|, write \verb|C.OA.south|.
276 \end{itemize}
277
278 \item \textbf{Methods} are invoked using the colon notation: \verb|object:method()|.
279 \begin{itemize}
280 \item For example, to compute the incircle of triangle \verb|ABC|, use: \verb|C.incircle = T.ABC:in_circle()|.
281 \item If a method requires a parameter, include it in parentheses. For instance, to compute the distance from point \verb|C| to the line \verb|(AB)|: \verb|d = L.AB:distance(z.C)|.
282 \end{itemize}
283
284 \item \textbf{Discarding results}: If a function returns multiple values and you only need one, use \verb|_| to ignore the rest.
285 \begin{itemize}
286 \item For example, to retrieve only the second point of intersection between a line and a circle:
287
288 \verb|_, z.J = intersection(L.AB, C.OC)|.
289 \end{itemize}
290 \end{itemize}
291
292 \subsection{Miscellaneous}
293 \label{sub:miscellanous}
294 \begin{itemize}
295 \item \texttt{Units and coordinates:} As in \tkzNamePack{tkz-euclide}, the default unit is the centimeter. All points are placed in an orthonormal Cartesian coordinate system.
296
297 \item \texttt{Numerical variables:} Real numbers follow the standard Lua conventions for notation.
298
299 \item \texttt{Complex numbers:} Similar to real numbers, but you must define them using the point constructor. For example:
300 \begin{verbatim}
301 za = point(1, 2)
302 \end{verbatim}
303 This corresponds mathematically to \(1 + 2i\). You can print the complex number using:
304 \begin{verbatim}
305 tex.print(tostring(za))
306 \end{verbatim}
307
308 \item \texttt{Boolean values:}
309 \begin{itemize}
310 \item In Lua: \verb|bool = true| or \verb|bool = false|
311 \item You can use the following \tkzname{Lua} code:
312 \begin{verbatim}
313 if bool == true then ... else ... end
314 \end{verbatim}
315 \item In LaTeX, after loading the \tkzNamePack{ifthen} package, you can write:
316 \begin{verbatim}
317 \ifthenelse{\equal{\tkzUseLua{bool}}{true}}{<true code>}{<false code>}
318 \end{verbatim}
319 \end{itemize}
320
321 \item \texttt{Strings:}
322 \begin{itemize}
323 \item Example in Lua: \verb|st = "Euler's formula"|
324 \item In LaTeX: \verb|\tkzUseLua{st}| will display \texttt{Euler's formula}
325 \end{itemize}
326 \end{itemize}
327 \endinput