Debian Codegraph @

texmf-dist/doc/metapost/mpkiviat/mpkiviat-doc.tex

raw
1 % LTeX: language=en
2
3 \documentclass[a4paper,english]{article}
4
5 \usepackage{xcharter-otf}
6 \usepackage[left=4cm]{geometry}
7 \usepackage{xspace}
8 \usepackage[svgnames]{xcolor}
9 \usepackage{multicol}
10 \usepackage{hologo}
11 \usepackage{listings}
12 \usepackage{showexpl} % examples
13 \usepackage{mflogo}
14 \usepackage{babel}
15 \usepackage{tikz}
16 \usepackage{url}
17 \usepackage{tikz}
18 \usepackage{luamplib}
19 \usepackage{siunitx}
20 \usepackage{accsupp}
21 \usepackage{pdflscape}
22 \usepackage{fancyvrb,xparse,xargs}
23 \usepackage[colorlinks]{hyperref}
24 \setmonofont{FiraCode-Regular}[
25 BoldFont=FiraCode-Bold,
26 Contextuals=Alternate, % Activate the calt feature
27 Scale=MatchLowercase
28 ]
29 \usepackage{biblatex}
30 \usepackage{imakeidx}
31 \makeindex[title=Index, columns=2]
32 \usepackage[verbatim]{lstfiracode} % Activate ligatures in verbatim
33 \usepackage[most]{tcolorbox}
34 \tcbuselibrary{listings,breakable}
35 \addbibresource{ctan.bib}
36 \newcommand\package[1]{\href{https://ctan.org/pkg/#1}{#1}}
37 \newcommand{\ctan}{\textsc{ctan}}
38 \newtcolorbox{colourband}[1][]{%
39 arc=0pt,outer arc=0pt,enhanced, breakable, spread sidewards, left*=0pt, right*=0pt, boxrule=0pt, colback=LightSteelBlue!10, #1}
40
41
42 \definecolor{hellgelb}{rgb}{1,1,0.85}
43 \definecolor{colKeys}{rgb}{0,0,1}
44 \definecolor{colIdentifier}{rgb}{0,0,0}
45 \definecolor{colComments}{rgb}{0.3,0.7,0.3}
46 \definecolor{colString}{rgb}{0,0.5,0}
47 \definecolor{mpcode}{rgb}{0.5,0.1,0.1}
48
49 \lstset{%
50 language=metapost,%
51 float=hbp,%
52 basicstyle=\ttfamily, %
53 identifierstyle=\color{DarkSlateGrey}, %
54 keywordstyle=\color{DarkBlue}\itshape, %
55 stringstyle=\color{Green}, %
56 commentstyle=\color{LightSlateGrey}\itshape, %
57 columns=flexible, %
58 tabsize=4, %
59 extendedchars=true, %
60 showspaces=false, %
61 showstringspaces=false, %
62 numbers=left,
63 numbersep=1em,
64 numberstyle=\tiny\color{gray}, %
65 breaklines=true, %
66 breakautoindent=true,
67 captionpos=b,
68 xleftmargin=0em,
69 sensitive=true,
70 morekeywords=[10]{},
71 keywordstyle=[10]\color{Salmon},
72 morekeywords=[7]{draw_axis,
73 draw_grad,
74 draw_legends,
75 draw_line,
76 set_axis_color,
77 set_axis_legends,
78 set_kiviat_unit,
79 set_lattice_color,
80 set_lattice_grid, set_line_mark,
81 set_line_mark_scale,
82 set_line_mark_type,
83 filldraw_line,
84 set_axis,},
85 keywordstyle=[7]\color{FireBrick},
86 morekeywords=[8]{},
87 keywordstyle=[8]\color{Sienna},
88 morekeywords=[9]{},
89 keywordstyle=[9]\color{Olive}
90 }
91 \lstset{explpreset={pos=t,wide=false,rframe={},preset=\centering}}
92 \lstdefinestyle{syntax}{backgroundcolor=\color{blue!15},numbers=none,xleftmargin=0pt,xrightmargin=0pt,
93 frame=single}
94 \lstdefinestyle{code}{backgroundcolor=\color{red!15},%numbers=left,
95 xleftmargin=0pt,xrightmargin=0pt,
96 frame=single}
97
98 \newtcblisting{mpcode}{
99 arc=0pt,outer arc=0pt,
100 colback=mpcode!3,
101 breakable,
102 boxsep=0pt,left=2pt,right=2pt,top=0pt,bottom=0pt, bottomtitle =
103 3pt, toptitle=3pt,
104 boxrule=0pt,bottomrule=0.pt,toprule=0.pt, toprule at break =
105 0pt, bottomrule at break = 0pt,
106 listing only,boxsep=0pt,listing
107 options={breaklines}
108 }
109
110
111 \newtcblisting{commandshell}{colback=black,colupper=white,colframe=black,
112 arc=0pt,
113 listing only,boxsep=0pt,listing
114 options={style=tcblatex,language=sh},
115 every listing line={\BeginAccSupp{ActualText={}}\textcolor{red}{\small\ttfamily\bfseries user \$> }}\EndAccSupp{}}
116
117 \makeatletter
118 \tcbset{%
119 listing metapost/.code={%
120 \def\tcbuselistingtext@input{\begin{mplibcode}
121 background:=(.988,.976,.976); input \jobname.listing;
122 \end{mplibcode}}%
123 }
124 }
125 \makeatother
126 \newtcblisting[auto counter,]{ExempleMP}[1][]{%
127 arc=0pt,outer arc=0pt,
128 colback=FireBrick!3,
129 colframe=FireBrick,
130 breakable,fontupper=\small,
131 boxsep=0pt,left=2pt,right=2pt,top=0pt,bottom=2pt, bottomtitle =
132 3pt, toptitle=3pt, lefttitle=5pt,
133 boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
134 0pt, bottomrule at break = 0pt,
135 listing side text,
136 listing metapost,
137 title={\bfseries\sffamily Exemple~\thetcbcounter},
138 listing options={breaklines},#1
139 }
140
141
142 \newcommand\mpkiviat{\texttt{mpkiviat}\xspace}
143 \newcommand\fichier[1]{\texttt{#1}}
144 \newcommand\variableGDD[1]{\texttt{\color{Sienna}#1}}
145 \newcommand\typeMP[1]{\texttt{\color{Tomato}#1}}
146 \newcommand\typeGDD[1]{\texttt{\color{Sienna}#1}}
147 \newcommand\foncGDD[1]{\texttt{\color{Sienna}#1}}
148
149 \newenvironment{Note}{
150 \noindent\textbf{Note~---~}}
151 {}
152
153
154
155 %
156 \colorlet{code}{blue!80!black}
157 \newcommand\cmd{\texttt}
158 \newcommand\code[1]{\texorpdfstring{\texttt{\color{code}#1}}{#1}}
159 \newcommand*\cs[1]{\code{\textbackslash #1}}
160 \newcommand*\macro{\par\bigskip\noindent\hspace{-30pt}%
161 \SaveVerb[aftersave={%
162 \UseVerb{Vitem}%
163 }%
164 ]{Vitem}%
165 % \bigskip
166 }
167 \newcommand\vitem[1][]{\SaveVerb[%
168 aftersave={\item[\textnormal{\UseVerb[#1]{vsave}}]}]{vsave}}
169 \newcommand*\textme[1]{\textcolor{black}{\rmfamily\textit{#1}}}
170 \newcommand*\meta[1]{% % meta
171 \textme{\ensuremath{\langle}#1\ensuremath{\rangle}}%
172 }
173 \newcommand*\optstar{% % optional star
174 \meta{\ensuremath{*}}\xspace
175 }
176 \DefineShortVerb{\|}
177 \setlength{\fboxsep}{2pt}
178 \fvset{%
179 codes={\catcode`\«\active \catcode`\×\active },
180 defineactive={\makefancyog\makefancytimes},
181 formatcom=\color{FireBrick},
182 frame=single
183 }
184 % rendre «...» équivalent à \meta{...}
185 {\catcode`\«\active
186 \newcommandx\makefancyog[0][addprefix=\global]{%
187 \def«##1»{\meta{##1}}}}
188 % rendre × équivalent à \optstar
189 {\catcode`\×\active
190 \newcommandx\makefancytimes[0][addprefix=\global]{%
191 \def×{\optstar{}}}}
192
193 \NewDocumentEnvironment{Macro}{ov}{%
194 \Verb+#2+
195 }{%
196 }
197 \newcommand{\return}[1]{~$\rightarrow$~#1}
198 \newcommand{\indication}[1]{\hfill(\itshape #1)}
199
200 \newcommand{\R}{\mathbf{R}}
201
202 \begin{document}
203 %% === Page de garde ===================================================
204 \thispagestyle{empty}
205 \begin{tikzpicture}[remember picture, overlay]
206 \node[below right, shift={(-4pt,4pt)}] at (current page.north west) {%
207 \includegraphics{fond.pdf}%
208 };
209 \end{tikzpicture}%
210
211 \noindent
212 {\Huge \bfseries \mpkiviat}\\
213 {\large Package \MP{} to draw Kiviat diagrams}\\[1cm]
214 \parbox{0.6\textwidth}{
215 \includegraphics[scale=0.86]{test-2.pdf}
216 }\hfill
217 \parbox{0.4\textwidth}{\Large\raggedleft
218 \textbf{Contributors}\\
219 Maxime \textsc{Chupin}\\
220 \url{[email protected]}
221 }
222 \vfill
223 \begin{center}
224 Version 0.1, 22th of may 2024\\
225 \url{https://gitlab.gutenberg-asso.fr/mchupin/mpkiviat}
226 \end{center}
227 %% == Page de garde ====================================================
228 \newpage
229
230 \begin{abstract}
231 This \hologo{METAPOST} package allows to draw Kiviat diagram (or radar chart,
232 web chart, spider chart, etc.).
233 \end{abstract}
234
235 \tableofcontents
236
237
238 \section{Introduction}
239
240 \mpkiviat is a package to draw Kiviat diagram (web chart, spider chart, spider
241 graph, spider web chart, star chart, star plot, cobweb chart, irregular polygon,or
242 polar chart) with \MP~\cite{ctan-metapost}.
243
244 \section{Installation}
245
246 \mpkiviat is on \ctan{} and can also be installed via the package manager of
247 your distribution.
248
249 \begin{center}
250 \url{https://www.ctan.org/pkg/mpkiviat}
251 \end{center}
252
253
254 \subsection{With \TeX live under Linux or macOS}
255
256 To install \mpkiviat with \TeX Live, you will have to create the directory
257 \lstinline+texmf+ in your \lstinline+home+.
258
259 \begin{commandshell}
260 mkdir ~/texmf
261 \end{commandshell}
262
263 Then, you will have to place the \lstinline+mpkiviat.mp+ file in
264 \begin{center}
265 \lstinline+~/texmf/metapost/mpkiviat/+
266 \end{center}
267
268
269 Once this is done, \mpkiviat will be loaded with the classic \MP{}
270 input code
271 \begin{mpcode}
272 input mpkiviat
273 \end{mpcode}
274
275 \subsection{With Mik\TeX{} and Windows}
276
277 These two systems are unknown to the author of \mpkiviat, so we
278 refer you to the Mik\TeX documentation concerning the addition of local packages:
279 \begin{center}
280 \url{http://docs.miktex.org/manual/localadditions.html}
281 \end{center}
282
283
284
285 \subsection{Dependencies}
286
287
288 \mpkiviat depends, of course on \MP~\cite{ctan-metapost}, as well as the
289 packages and---if \mpkiviat is not used with
290 \hologo{LuaLaTeX}~\cite{ctan-lualatex-doc,ctan-luatex} and the
291 \package{luamplib} or \package{minim-mp}~\cite{ctan-luamplib,ctan-minim-mp}
292 packages---the \package{latexmp}~\cite{ctan-latexmp} package.
293
294
295 \section{Axis and lattice}
296
297 \begin{colourband}
298 \macro|set_axis(«list of axis names»)|
299 \medskip
300
301 The \meta{list of axis names} is a list delimited by commas with the names of
302 the different axis as \typeMP{string} (e.g.
303 \lstinline+"Légumes","Fruits","Produits laitiers"+).
304 \index{set_axis@\lstinline+set_axis+}
305 \end{colourband}
306
307 The command to draw the Kiviat background is the following:
308
309
310 \begin{colourband}
311 \macro|draw_axis|
312 \index{draw_axis@\lstinline+draw_axis+}
313 \end{colourband}
314
315 The combinaison of these two commands produces, for example:
316 \begin{ExempleMP}[sidebyside=false]
317 input mpkiviat;
318 beginfig(1);
319 set_axis("Légumes","Viande","Lait","Pain","Poissons");
320 draw_axis;
321 endfig;
322 \end{ExempleMP}
323
324 By default, legend of each axis are written, but you can avoid that using the
325 following command:
326
327 \begin{colourband}
328 \macro|set_axis_legends(«boolean»)|
329 \medskip
330
331 \begin{description}
332 \item[\meta{boolean}:] \typeMP{true} or \typeMP{false}
333 \end{description}
334 \index{set_axis_legends@\lstinline+set_axis_legends+}
335 \end{colourband}
336
337
338 Default value for each axis is 10, and there is 10 steps for the lattice. You
339 can redefine that with the following command that \emph{should be set before the
340 drawing command} :
341 \begin{colourband}
342 \macro|set_lattice_grid(«unit»,«max»)|
343 \medskip
344
345 \begin{description}
346 \item[\meta{unit}:] (\typeMP{numeric}) is the interval between two lines of the lattice;
347 \item[\meta{max}:] (\typeMP{numeric}) is the maximum value for each axis.
348 \end{description}
349 \index{set_lattice_grid@\lstinline+set_lattice_grid+}
350 \end{colourband}
351
352 You can print the graduations for the lattice with the following command:
353 \begin{colourband}
354 \macro|draw_grad(«prefix»,«suffix»,«axis number»)|
355 \medskip
356
357 \begin{description}
358 \item[\meta{prefix}:] (\typeMP{string}) is a string to add before each graduation;
359 \item[\meta{suffix}:] (\typeMP{suffix}) is a string to add after each graduation;
360 \item[\meta{axis number}:] (\typeMP{numeric}) is an integer to choose the axis
361 used for printing the graduations.
362 \end{description}
363 \index{draw_grad@\lstinline+draw_grad+}
364 \end{colourband}
365
366 \mpkiviat defines a unit that can be modified to scale the entire graph with the
367 following command (that must be used before the command \lstinline+set_axis+).
368
369 \begin{colourband}
370 \macro|set_kiviat_unit(«unit»)|
371 \medskip
372
373 \begin{description}
374 \item[\meta{unit}:] (\typeMP{string}, default \SI{0.3}{cm}) is the unit to
375 draw the graph.
376 \end{description}
377 \index{set_kiviat_unit@\lstinline+set_kiviat_unit+}
378 \end{colourband}
379
380 One can set colors for the axis and the lattice with the two following commands.
381
382
383 \begin{colourband}
384 \macro|set_axis_color(«color»)|
385 \medskip
386
387 \begin{description}
388 \item[\meta{color}:] (\typeMP{color}) is the color for drawing the axis arrows.
389 \end{description}
390 \index{set_axis_color@\lstinline+set_axis_color+}
391 \end{colourband}
392
393
394 \begin{colourband}
395 \macro|set_lattice_color(«color»)|
396 \medskip
397
398 \begin{description}
399 \item[\meta{color}:] (\typeMP{color}) is the color for drawing the lattice.
400 \end{description}
401 \index{set_lattice_color@\lstinline+set_lattice_color+}
402 \end{colourband}
403
404
405
406 The following example illustrates some of the previous commands.
407
408 \begin{ExempleMP}[sidebyside=false]
409 input mpkiviat;
410 beginfig(1);
411 set_kiviat_unit(0.4cm);
412 set_axis("Légumes","Viande","Lait","Pain","Poissons");
413 set_axis_color((0.7,0.1,0.1));
414 set_lattice_color((0.5,0.5,0.9));
415 set_lattice_grid(100,600);
416 draw_axis;
417 draw_grad("","~€",3);
418 endfig;
419 \end{ExempleMP}
420
421
422 \section{Add lines}
423
424 Once you have drawn the background, you can add lines for your Kiviat diagram.
425 The basic command to do that is the following:
426
427 \begin{colourband}
428 \macro|draw_line(«list of values»)(«color»)|
429 \medskip
430
431 \begin{description}
432 \item[\meta{list of value}:] (list of \typeMP{string}) values for the
433 different axis of the Kiviat diagram (e.g. \lstinline+"9","2","3"+). The
434 values must match the settings of the lattice.
435 \item[\meta{color}:] (\typeMP{color}) is the color for drawing the line.
436 \end{description}
437 \index{draw_line@\lstinline+draw_line+}
438 \end{colourband}
439
440 You can also draw and fill a Kiviat line with the following command:
441
442 \begin{colourband}
443 \macro|filldraw_line(«list of values»)(«color»)|
444 \medskip
445
446 \begin{description}
447 \item[\meta{list of value}:] (list of \typeMP{string}) values for the
448 different axis of the Kiviat diagram (e.g. \lstinline+"9","2","3"+). The
449 values must match the settings of the lattice.
450 \item[\meta{color}:] (\typeMP{color}) is the color for drawing the line. The
451 filling color is transparent\footnote{Thanks to Anthony Phan \MP{} code : \url{http://www-math.univ-poitiers.fr/~phan/metalpha.html}.}
452 \end{description}
453 \index{filldraw_line@\lstinline+filldraw_line+}
454 \end{colourband}
455
456 By default, there is mark on a Kiviat line. You can remove marks with the
457 following command, setting the booelan argument to \lstinline+false+.
458
459
460
461 \begin{colourband}
462 \macro|set_line_mark(«boolean»)|
463 \medskip
464
465
466 \begin{description}
467 \item[\meta{boolean}:] \typeMP{true} or \typeMP{false}
468 \end{description}
469 \index{set_line_mark@\lstinline+set_line_mark+}
470 \end{colourband}
471
472 You can also choose the type of mark. \mpkiviat provides three types :
473 \lstinline+"square"+, by default, \lstinline+"circle"+ and \lstinline+"custom"+.
474 To choose one of them, you have to use the following command:
475 \begin{colourband}
476 \macro|set_line_mark_type(«type»)|
477 \medskip
478
479
480 \begin{description}
481 \item[\meta{type}:] (\typeMP{string}) \lstinline+"square"+, by default,
482 \lstinline+"circle"+ and \lstinline+"custom"+.
483 \end{description}
484 \index{set_line_mark_type@\lstinline+set_line_mark_type+}
485 \end{colourband}
486
487 If you choose \lstinline+custom+, you will have to define a macro
488 \lstinline+line_mark_custom+ that take a \typeMP{pair} as argument and that
489 define a cycled path shifted around the \typeMP{pair}. For instance, the
490 \lstinline+line_mark_square+ command is defined as:
491 \begin{mpcode}
492 def line_mark_square(expr p)=
493 (((-1,-1)--(1,-1)--(1,1)--(-1,1)--cycle scaled _line_mark_scale) shifted p)
494 enddef;
495 \end{mpcode}
496
497 You can adjust the size of the marks using the following scaling macro:
498 \begin{colourband}
499 \macro|set_line_mark_scale(«scaling factor»)|
500 \medskip
501
502
503 \begin{description}
504 \item[\meta{scaling factor}:] is a \typeMP{numeric} that is, by default, 1.
505 \end{description}
506 \index{set_line_mark_scale@\lstinline+set_line_mark_scale+}
507 \end{colourband}
508
509 Here is an example that illustrates some of the previous commands.
510
511 \begin{ExempleMP}[sidebyside=false]
512 input mpkiviat;
513 beginfig(1);
514 set_lattice_grid(100,500);
515 set_kiviat_unit(0.4cm);
516 set_axis("McCabe","LOC","Live Variables","Halstead N","Variablenspanne");
517 draw_axis;
518
519 filldraw_line(400,300,380,200,250)(red);
520 set_line_mark_type("circle");
521 filldraw_line(300,320,180,400,150)(blue);
522 set_line_mark_type("square");
523 set_line_mark_scale(2);
524 filldraw_line(100,420,280,200,50)(green);
525 endfig;
526 \end{ExempleMP}
527
528 \section{Legends}
529
530 \mpkiviat provides the following command to add legends to a Kiviat diagram:
531
532 \begin{colourband}
533 \macro|draw_legends.«place»(«list of names»)|
534 \medskip
535
536
537 \begin{description}
538 \item[\meta{place}:] is one of the standard \MP{} suffixes :
539 empty, \lstinline+lft+, \lstinline+rt+, \lstinline+top+,
540 \lstinline+bot+, \lstinline+ulft+, \lstinline+urt+, \lstinline+llft+ and
541 \lstinline+lrt+. The legend is placed at the given place of the bounding box
542 of the complete Kiviat diagram (without the legend). If it is empty, the
543 default place is \lstinline+rt+.
544 \item[\meta{list of names}:] is the list of \typeMP{string} of names for the
545 different lines in the order of the construction.
546 \end{description}
547 \index{draw_legends@\lstinline+draw_legends+}
548 \end{colourband}
549
550 \begin{ExempleMP}[sidebyside=false]
551 input mpkiviat;
552 beginfig(1);
553 set_lattice_grid(100,500);
554 set_kiviat_unit(0.4cm);
555 set_axis("McCabe","LOC","Live Variables","Halstead N","Variablenspanne");
556 draw_axis;
557
558 filldraw_line(400,300,380,200,250)(red);
559 set_line_mark_type("circle");
560 filldraw_line(300,320,180,400,150)(blue);
561 set_line_mark_type("square");
562 set_line_mark_scale(2);
563 filldraw_line(100,420,280,200,50)(green);
564 draw_legends.lrt("Première", "Deuxième", "Troisième");
565 endfig;
566 \end{ExempleMP}
567
568 \printbibliography
569 \printindex
570
571 \end{document}