Debian Codegraph @

texmf-dist/doc/metapost/wordcloud/wordcloud-doc-en.tex

raw
1
2 % LTeX: language=en
3
4 % wordcloud : draw word cloud with MetaPost and Lua
5 %
6 % Originally written by Maxime Chupin <[email protected]>,
7 % 2025.
8 %
9
10 \documentclass[english]{ltxdoc}
11
12 \input{wordcloud-preamble}
13 \usepackage{wordcloud}
14 \usepackage[english]{babel}
15
16 \makeindex[title=Command Index, columns=2]
17
18
19
20 %\lstset{moredelim=*[s][\color{red}\rmfamily\itshape]{<}{>}}
21 %\lstset{moredelim=*[s][\color{blue}\rmfamily\itshape]{<<}{>>}}
22
23 \begin{document}
24
25 \title{{Wordcloud} : drawing wordclouds with \hologo{METAPOST} and Lua}
26 \author{Maxime Chupin, \url{[email protected]}}
27 \date{\today}
28
29 %% === Page de garde ===================================================
30 \thispagestyle{empty}
31 \begin{tikzpicture}[remember picture, overlay]
32 \node[below right, shift={(-4pt,4pt)}] at (current page.north west) {%
33 \includegraphics{fond.pdf}%
34 };
35 \end{tikzpicture}%
36
37 \noindent
38 {\Huge \texttt{wordcloud}}\par\bigskip
39 \noindent
40 {\Large drawing wordclouds \\[0.2cm]with \hologo{METAPOST} and Lua}\\[3cm]
41 \parbox{0.6\textwidth}{
42 \wordcloud[scale=2,rotate=0,margin=0.5pt,usecolor]{(Wordcloud,10);(\hologo{METAPOST},6);(\LaTeX,7);(Lua,4);(algorithm,3);(code,2);(mathematics,2);(CTAN,2);(mplib,4);(\hologo{LuaTeX},4);(latexmp,3);(graphism,2)}
43 }\hfill
44 \parbox{0.5\textwidth}{\Large\raggedleft
45 \textbf{Contributor}\\
46 Maxime \textsc{Chupin}\\
47 \url{[email protected]}
48 }
49 \vfill
50 \begin{center}
51 Version 0.3, 2025, Novembre, 16th \\
52 \url{https://github.com/chupinmaxime/wordcloud}
53 \end{center}
54 %% == Page de garde ====================================================
55 \newpage
56
57 %\maketitle
58
59 \begin{abstract}
60 These \hologo{METAPOST} and \hologo{LuaLaTeX} packages allows drawing
61 wordclouds from a list of words and weights. The algorithm is implemented with
62 \hologo{METAPOST} whereas Lua is used to parse \LaTeX{} commands, to build
63 the list of words and weights from a text file, and to generate
64 \hologo{METAPOST} code interpreted by \package{luamplib}.
65 \end{abstract}
66
67
68 \begin{center}
69 \url{https://plmlab.math.cnrs.fr/mchupin/wordcloud}
70 \url{https://github.com/chupinmaxime/wordcloud}
71 \end{center}
72
73 \tableofcontents
74
75 \bigskip
76
77 \begin{tcolorbox}[ arc=0pt,outer arc=0pt,
78 colback=darkred!3,
79 colframe=darkred,
80 breakable,
81 boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
82 3pt, toptitle=3pt,
83 boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
84 0pt, bottomrule at break = 0pt,]
85 \itshape
86 This package is in beta version---do not hesitate to report bugs, as well as
87 requests for improvement, or better: to help me to improve it.
88 \end{tcolorbox}
89
90 \section{Installation}
91
92 \wordcloudpkg is on \ctan{} and can also be installed via the package manager of your
93 distribution.
94
95 \begin{center}
96 \url{https://www.ctan.org/pkg/wordcloud}
97 \end{center}
98
99
100 \subsection{With \TeX live under Linux or macOS}
101
102 To install \wordcloudpkg with \TeX Live, you will have to create the directory
103 \lstinline+texmf+ in your \lstinline+home+.
104
105 \begin{commandshell}
106 mkdir ~/texmf
107 \end{commandshell}
108
109 Then, you will have to place the \lstinline+wordcloud.mp+ file in
110 \begin{center}
111 \verb+~/texmf/metapost/wordcloud/+
112 \end{center}
113
114
115 You will also have to place the \lstinline+wordcloud.lua+ file in
116 \begin{center}
117 \verb+~/texmf/scripts/wordcloud/+
118 \end{center}
119
120 And finally, you will have to place the \lstinline+wordcloud.sty+ file in
121 \begin{center}
122 \verb+~/texmf/tex/latex/wordcloud/+
123 \end{center}
124
125
126
127 Once this is done, \wordcloudpkg will be loaded with the classic \MP{}
128 input code
129 \begin{mpcode}
130 input wordcloud
131 \end{mpcode}
132
133 And for the \hologo{LuaLaTeX} side, \wordcloudpkg will be loaded with
134 \begin{latexcode}
135 \usepackage{wordcloud}
136 \end{latexcode}
137
138 \subsection{With Mik\TeX{} and Windows}
139
140 These two systems are unknown to the author of \wordcloudpkg, so we
141 refer you to the Mik\TeX documentation concerning the addition of local packages:
142 \begin{center}
143 \url{http://docs.miktex.org/manual/localadditions.html}
144 \end{center}
145
146
147
148 \subsection{Dependencies}
149
150
151 \wordcloudpkg depends, for the \MP side, of course on \MP~\cite{ctan-metapost},
152 but also on \package{metapost-colorbrewer}~\cite{ctan-metapost-colorbrewer} and the
153 \package{latexmp} package~\cite{ctan-latexmp}. For the \hologo{LuaLaTeX} side~\cite{ctan-lualatex-doc},
154 \wordcloudpkg depends on the \package{luamplib} package~\cite{ctan-luamplib}
155 and the \package{xcolor}~\cite{ctan-xcolor}.
156
157
158 \section{\hologo{METAPOST} side}
159
160 \subsection{Description of the algorithm}
161
162 Given a set of words and weights, we first use a
163 \emph{scale function} of the weights to scale the words. In this beta version of
164 \package{wordcloud}, we only provide a log-based function\footnote{Other scale
165 options could be provided in the next versions.}.
166
167 Then, we compute a spiral line starting at the center\footnote{There is variants
168 of the algorithm that use different line: squared spiral, etc.}.
169
170 Then the algorithm is quite simple:
171 \begin{algorithmic}[1]
172 \Require set of words $(W_i)_{i\in\{1,\dots,N}$ and corresponding weight
173 $(w_i)_{i\in\{1,\dots,N}$, and a spiral line $\mathcal{S}$
174 \ForAll{$i\in\{1, \dots,N\}$}
175 \State Place $W_i$ at the start of $\mathcal{S}$
176 \Repeat
177 \State Set $b_\text{draw}:=\text{true}$
178 \ForAll{$j\in{1,\dots,i}$}
179 \If{$W_i\cap W_j\neq\emptyset$}
180 \State Set $b_\text{draw}:=\text{false}$
181 \EndIf
182 \EndFor
183 \If{$b_\text{draw}==\text{true}$}
184 \State Draw $W_i$
185 \Else
186 \State Move $W_i$ along $\mathcal{S}$
187 \EndIf
188 \Until{$W_i$ is drawn}
189 \EndFor
190 \end{algorithmic}
191
192 The hard part is making it perform efficiently! According to Jonathan Feinberg,
193 Wordle\footnote{One of the first web application to build wordcloud.} uses a
194 combination of hierarchical bounding boxes and quadtrees to achieve reasonable
195 speeds. Here, with \hologo{METAPOST}, we compute intersections with the bounding
196 box of the word.
197
198 \begin{remark}
199 \begin{itemize}
200 \item
201 The words with \hologo{METAPOST} are built with the \lstinline+textext()+
202 function of \package{latexmp} or \package{luamplib}. We are trying to use the
203 bounding boxes of the letters when we get an intersection between ``global''
204 bounding boxes to allow placing words nearer of each other. Unfortunately,
205 this does not work for the moment. Any help is welcomed. \medskip
206
207 \item We first tried to compute intersections between words by decomposing the
208 letter using their contours and compute intersection of contours (with
209 \lstinline+intersectiontimes+). Unfortunately, this is much too slow.
210 \end{itemize}
211
212 \end{remark}
213
214 Some explanations can be found here:
215 \begin{center}
216 \url{https://www.jasondavies.com/wordcloud/about/}
217 \end{center}
218
219 \subsection{Main command}
220
221 The main command is
222
223 \commande|draw_wordcloud(«words», «weights»,«rotation»,«size»)|\smallskip\index{draw_wordcloud@\lstinline+draw_wordcloud+}
224
225 \begin{description}
226 \item[\meta{words}:] array of strings ;
227 \item[\meta{weights}:] array of numerics ;
228 \item[\meta{rotation}:] angle for wordcloud drawing;
229 \item[\meta{size}:] number of elements in arrays.
230 \end{description}
231
232 \begin{ExempleMP}
233 input wordcloud
234 beginfig(0);
235 string words[];
236 numeric weights[];
237 words[1]:="\LaTeX";
238 words[2]:="\hologo{METAPOST}";
239 words[3]:="Document";
240 words[4]:="Lua";
241 words[5]:="\TeX";
242 weights[1]:=5;
243 weights[2]:=4;
244 weights[3]:=3.5;
245 weights[4]:=3;
246 weights[5]:=3;
247 draw_wordcloud(words,weights,0,5);
248 endfig;
249 \end{ExempleMP}
250
251 \begin{remark}
252 The ``unity'' of weights is not important because internally,
253 \package{wordcloud} compute new weights to work
254 with the internal scaling function.
255 \end{remark}
256
257 \subsection{Parameters}
258
259 There are few parameters.
260
261 \subsubsection{Colors}\label{sec:colors}
262
263 You can use set of colors to draw the wordcloud. For that, you have to use the
264 following command:
265 \commande|wordcloud_use_color(«bool»)|\smallskip\index{wordcloud_use_color@\lstinline+wordcloud_use_color+}
266
267 \begin{description}
268 \item[\meta{bool}:] boolean \lstinline+true+ or \lstinline+false+ (default \lstinline+false+).
269 \end{description}
270
271 \package{wordcloud} provides a set of five colors using the \hologo{METAPOST}
272 package \package{metapost-colorbrewer}~\cite{ctan-metapost-colorbrewer}.
273 \package{wordcloud} defines an array of \lstinline+color+s and a
274 \lstinline+numeric+ to set the colors to use.\index{wordcloud_colors@\lstinline+wordcloud_colors+}\index{wordcloud_colors_number@\lstinline+wordcloud_colors_number+}
275 \begin{mpcode}
276 % default colors
277 wordcloud_colors[1]:=Reds[3][3];
278 wordcloud_colors[2]:=Greens[3][3];
279 wordcloud_colors[3]:=Blues[3][3];
280 wordcloud_colors[4]:=Oranges[3][3];
281 wordcloud_colors[5]:=black;
282 wordcloud_colors_number:=5;
283 \end{mpcode}
284 Feel free to modify that variables to customize the colors.
285
286 \subsubsection{Scaling}
287
288 You can globally scale the picture using the following command:
289 \commande|set_wordcloud_scale(«scale»)|\smallskip\index{set_wordcloud_scale@\lstinline+set_wordcloud_scale+}
290
291 \begin{description}
292 \item[\meta{scale}:] \lstinline+numeric+.
293 \end{description}
294
295 \subsubsection{Margins}
296
297 You can adjust the margins of the global bounding boxes of words using the
298 following command:
299 \commande|set_box_margin(«dim»)|\smallskip\index{set_box_margin@\lstinline+set_box_margin+}
300
301 \begin{description}
302 \item[\meta{dim}:] a dimension with units (default 0.3pt).
303 \end{description}
304
305
306
307 \section{\hologo{LuaLaTeX} side}
308
309 \package{wordcloud} provides a \hologo{LuaLaTeX} package. It uses the package
310 \package{luamplib} to interpret the \hologo{METAPOST} code produced by Lua.
311
312
313 \subsection{Main commands}
314
315 The first \LaTeX{} command provided by \wordcloudpkg is:
316
317 \commande|\wordcloud[«options»]{«list of words and weights»}|\smallskip\index{\wordcloud@\lstinline+\wordcloud+}
318
319 where
320 \begin{description}
321 \item[\meta{list of words and weights}:] is a list of couples of the form
322 \lstinline+(word1,weight1);(word2,weight2);(word3,weight3);...+
323 \end{description}
324
325 The second \LaTeX{} command allows to read a text file, to build the list of
326 words and weights and draw the wordcloud up to a certain number of words.
327
328 \commande|\wordcloudFile[«options»]{«text file»}{«number of words»}|\smallskip\index{\wordcloudFile@\lstinline+\wordcloudFile+}
329
330 where:
331 \begin{description}
332 \item[\meta{text file}:] is a text file to analyze and from which the
333 wordcloud is build ;
334 \item[\meta{number of words}:] is the number of words composing the wordcloud.
335 \end{description}
336
337 \subsubsection{Options}
338
339 Both of these functions (\lstinline+\wordcloud+ and \lstinline+\wordcloudFile+)
340 have the same options:
341
342 \begin{description}
343 \item[\texttt{scale=}\meta{value}:] to scale the picture\footnote{Beware
344 that scaling increases the computation time and the values manipulated by
345 \hologo{METAPOST}.} ;
346 \item[\texttt{margin=}\meta{value with units}:] to adjust the margins
347 (default \lstinline+0.3pt+) ;
348 \item[\texttt{rotate=}\meta{angle}:] to rotate (degrees) the words with
349 $\pm$\meta{angle} alternatively (default 0) ;
350 \item[\texttt{usecolor}:] to use color for word drawing (boolean, default
351 \lstinline+false+) as described in section~\ref{sec:colors} ;
352 \item[\texttt{colors=}\meta{list of colors}:] to define a new
353 set of colors as described in section~\ref{sec:colors}\footnote{This needs
354 \package{xcolor} because the colors are converted to rgb coding and then
355 transferred to \hologo{METAPOST}.}.
356 \end{description}
357
358
359 Here an example:
360 \begin{ExempleLaTeX}
361 \wordcloud[scale=1,rotate=45,margin=0.5pt,usecolor,colors={red!40,blue!40,green!20!black}]{(Wordcloud,10);(\hologo{METAPOST},6);(\LaTeX,7);(Lua,4);(algorithm,3);(code,2);(mathematics,2);(CTAN,2);(mplib,4);(\hologo{LuaTeX},4);(\texttt{latexmp},3);(graphism,2)}
362 \end{ExempleLaTeX}
363
364 Since version 0.2, you could use any \LaTeX{} code to define words for the
365 wordcloud. In the definition of the \LaTeX{} command, \wordcloudpkg{} uses
366 \lstinline+\luaescapestring+ to deals with commands. For example, as far as we
367 know, this \wordcloudpkg package is the only wordcloud tool that could build a
368 wordcloud of mathematical formulas.
369
370 \begin{remark}
371 \begin{itemize}
372 \item Because the \hologo{METAPOST} side uses \lstinline+textext+ command to build
373 words, \lstinline+\mplibtextextlabel{enable}+ is used to enable string labels
374 typeset via \lstinline+textext()+ instead of \emph{infont} operator.
375 \item The \lstinline+\wordcloud+ command build an \lstinline+mplibcode+
376 environment with \hologo{METAPOST} code. Each of the \lstinline+mplibcode+
377 environment use the \lstinline+luamplib+~\cite{ctan-luamplib} mechanism of
378 \emph{instance} named \lstinline+wordcloud+.
379 \end{itemize}
380 \end{remark}
381
382 \subsection{Add ignored words}
383
384 The Lua function that builds words and weights from a text file ignores some
385 words (and characters). For the moment, \package{wordcloud} only includes word
386 lists to ignore for English and French.
387
388 However, you can add a list of words to ignore with the following command:
389
390 \commande|\wordcloudIgnoreWords{«word list»}|\smallskip\index{\wordcloudIgnoreWords@\lstinline+\wordcloudIgnoreWords+}
391
392 \begin{description}
393 \item[\meta{word list}:] the list of words, separated with commas, to ignore
394 \lstinline+word1,word2,word3, etc.+
395 \end{description}
396
397 \subsection{\textsc{pdf} tagging}
398
399 Thanks to the demand of David Carlisle, the \hologo{LaTeX} commands generate
400 now, if the tagging in on with \hologo{LuaLaTeX}, alternative text to describe
401 the wordcloud produced. It uses the \lstinline+luamplib+ mechanism tot deal with
402 \textsc{pdf} tagging.
403
404 \section{With \texttt{pdftotext}}
405
406 Thanks to \package{wordcloud} and the program \texttt{pdftotext}\footnote{It
407 should be possible to parse a \pdf{} with \hologo{LuaTeX}, though. See \url{https://tex.stackexchange.com/questions/692930/recovering-the-textual-content-of-a-pdf-file-with-luatex}.} one can
408 easily produce the wordcloud of the current \pdf.
409
410 For that, you can produce the text file of the \pdf{}:
411 \begin{commandshell}
412 pdftotext wordcloud-doc-en.pdf
413 \end{commandshell}
414 and then, you can use the following code:
415 \begin{latexcode}
416 \wordcloudFile[usecolor]{wordcloud-doc-en.txt}{50}
417 \end{latexcode}
418
419 This produce the following wordcloud\footnote{Note that, because the wordcloud
420 production is slow, we used a separate file to only produce the \pdf{} of the
421 wordcloud, without any scaling, and we inserted the result scaling it with \package{graphicx}\cite{ctan-graphicx}.}
422 \begin{center}
423 \includegraphics[width=\linewidth]{doc-wc.pdf}
424 \end{center}
425
426 \section{To do}
427
428 Some things to do:
429 \begin{itemize}
430 \item Improve intersection of words by using the letters bounding boxes.
431 \item Work on speed of the algorithm.
432 \item Add supported languages (ignored words).
433 \item Improve text file analysis with Lua to build the set of words and
434 weights.
435 \item Build wordcloud inside a shape.
436 \item Add options for rotation of words.
437 \end{itemize}
438
439 \section{History}
440
441 \begin{description}
442 \item[v0.3 (11/2025):] Add \textsc{pdf} tagging for \LaTeX{} figures.
443 \item[v0.2 (09/2023):] Deal with \lstinline+\luaescapestring+ for list with
444 \lstinline+\wordcloud+. Typos in doc.
445 \item[v0.1 (08/2023):] First publication.
446 \end{description}
447 \printbibliography
448 \printindex
449 \newpage
450
451
452
453 \end{document}