Debian Codegraph @

texmf-dist/doc/latex/figput/figput-manual/figput-manual.tex

raw
1
2 \documentclass[10pt]{article}
3
4 % Allows various tweaks to itemize as optional arguments.
5 \usepackage{enumitem}
6
7 % Gives the proof environment, with a box for QED.
8 \usepackage{amsthm}
9
10 % Needed for things like pmatrix.
11 \usepackage{amsmath}
12
13 % This allows footnotes from within array environment.
14 \usepackage{footnote}
15 \makesavenoteenv{array}
16
17 % To adjust font sizes more easily.
18 \usepackage{relsize}
19
20 % This allows \verb in footnotes
21 \usepackage{fancyvrb}
22
23 % This allows me to say
24 % \begin{figure}[H]
25 % to mean ``here, and don't argue.'' Note the captial 'H'.
26 \usepackage{float}
27
28 % This is the modern thing to do, but the manual is 1300 pages!
29 \usepackage{tikz}
30 \usepackage{pgfplots}
31
32
33 \begin{document}
34
35 % Need this for fancyvrb to work.
36 \VerbatimFootnotes
37
38 % So that I don't have to type this all the time.
39 \newcommand{\figput}{\textsc{FigPut}}
40
41
42 \begin{center}
43 {\Large \figput}
44
45 Interactive Figures for \LaTeX
46
47 \verb=https://github.com/rsfairman/figput=
48
49 Randall Fairman
50
51 Version 0.90, July 21, 2022
52 \end{center}
53
54 \vskip 0.2cm
55
56 The \textsc{FigPut} system allows \LaTeX\ to produce interactive
57 figures. The system produces a static PDF file, as usual; in addition,
58 the document can be viewed with an Internet browser and the figures
59 become interactive. See the prototype in {\tt example/example.tex}
60 to clarify what follows.\footnote{The version available on CTAN
61 includes only what is strictly necessary to rebuild the document from
62 scratch: {\tt example.tex} and {\tt exteernalcode.js}. The repository at {\tt
63 github} includes all the files that result from the build process,
64 and are necessary to view the PDF in either static or interactive
65 form.} To view this example in its fully interactive form, see
66 \verb=rsfairman.github.io/figput-example/=.
67
68 % For some reason \textsc doesn't work within \section
69 \section{Why \normalfont\scshape{FigPut}}
70
71 There are many ways to produce figures in \LaTeX: MetaPost, TikZ,
72 PSTricks, XY-pic, {\tt graphics}, {\tt picture}, and more. Creating
73 technical figures is often an exercise in programming, and none of
74 these is based on a commonly used programming
75 language. \textsc{FigPut} is based on JavaScript (JS), which is
76 probably the most widely used language today. Moreover,
77 \figput\ allows figures to be animated and/or interactive.
78
79 Aside from the fact that figures are specified with
80 JavaScript, the system is normal \LaTeX. An important feature is that
81 the two forms of the document -- static PDF and interactive -- look
82 identical, with the same pagination and formatting. The reader can
83 move between the printed version and the interactive version without
84 needing to reorient.
85
86 % For some reason \textsc doesn't work within \section
87 \section{Using \normalfont\scshape{FigPut}}
88
89 Here's a list of all the commands available in \figput:
90 \begin{verbatim}
91 \begin{figput} ... \end{figput}
92 \FigPut
93 \SetInnerMargin
94 \SetOuterMargin
95 \NeverSkip
96 \AllowSkip
97 \LoadFigureCode
98 \end{verbatim}
99
100 \subsection{The \LaTeX\ Side}
101
102 Interactive figures are specified with the {\tt figput}
103 environment or the \verb=\FigPut= command. The full form of the
104 environment specification is
105 \vskip 0.2cm
106
107 \noindent\verb=\begin{figput}{<fig_name>,<fig_ht>}[=\emph{optional arguments}\verb=]=
108
109 \noindent\verb= <JavaScript code>=
110
111 \noindent\verb=\end{figput}=
112 \vskip 0.2cm
113
114 \noindent There are two mandatory arguments: \verb=<fig_name>= and
115 \verb=<fig_ht>=. Every figure must have a unique name. This name is
116 unrelated to any \verb=\label= or other identifier used for
117 the figure. The \verb=<fig_ht>= is the height of the figure, expressed
118 like other \LaTeX\ lengths in {\tt pt}, {\tt cm}, \emph{etc}. The
119 figure is allocated this much vertical space on the page. The
120 remaining optional arguments are discussed below.
121
122 The {\tt <JavaScript code>} is used to draw the figure, and the only
123 requirement is that it be given as
124 \begin{verbatim}
125 function <fig_name>(ctx) {
126 ...
127 }
128 \end{verbatim}
129 The name of the JS function must match the figure name given to the
130 {\tt figput} environment -- that's how the browser finds the correct
131 JS function to draw a particular figure. The {\tt ctx} argument
132 is required; it's the ``rendering context'' used for
133 drawing.\footnote{\label{page-ctx} A variable of this type is commonly obtained in
134 JavaScript by something like \vspace{-1.5mm}
135 \begin{verbatim}
136 let canvas = document.getElementById('where-drawing-happens');
137 let ctx = canvas.getContext('2d');
138 \end{verbatim}
139 \vspace{-1.5mm} The full name for this type is {\tt
140 CanvasRenderingContext2D}.}
141
142 All of the JS functions for the various figures share the same
143 name-space, and it is perfectly acceptable to share functions between
144 figures or to define helper functions within a figure's
145 environment. If many figures use the same {\tt drawDoodad()}
146 function, then that function should appear with only a single figure, and
147 it will be available to all of them.
148
149 Use \verb=\SetInnerMargin= and \verb=\SetOuterMargin= to set the inner and outer
150 margins (which may differ in a book that has left and right
151 pages). The figure will be rendered within a rectangle that is set in
152 from the left margin by the given amount. For example, you might say
153 \begin{verbatim}
154 \SetInnerMargin{150pt}
155 \SetOuterMargin{150pt}
156 \end{verbatim}
157 so that the left edge of the figure is {\tt 150pt} from the left edge
158 of the paper. These values can be changed before every figure, if that
159 is appropriate.
160
161 The coordinate system used within the JS code is based on big points ({\tt
162 bp}), with the origin at the lower-left corner of the
163 figure. The $y$-coordinate increases as you move \emph{up} the page.
164 The $y$-axis is offset from the edge of the page by the
165 value given to \verb=\SetInnerMargin= or \verb=\SetOuterMargin=.
166
167 There is no need to begin the drawing by erasing the drawing
168 area. That's done automatically.
169
170 \subsubsection*{Optional Arguments}
171
172 The arguments to {\tt figput} in {\tt []}, are optional. The first two
173 of these arguments are \label{ht-above-below}
174 \begin{verbatim}
175 ht_above, ht_below
176 \end{verbatim}
177 If these arguments appear, then they must both appear, they must be
178 the first two arguments, and they must be given in that order (above,
179 then below); furthermore, they must include a unit specification, like {\tt
180 bp}. An interactive figure may need a bit of extra clearance
181 for an animation or space for widgets that aren't part of the
182 figure itself. The static version of the document always uses
183 \verb=<fig_ht>= for the figure height, while the interactive form adds
184 this optional amount of space above and below the figure. If
185 \verb=ht_below= is non-zero, then the $y$-axis is \verb=ht_below=
186 above the bottom of the figure when drawn interactively.
187
188 The remaining optional arguments may appear in any order and function
189 as boolean flags:
190
191 \begin{itemize}[itemsep=-1pt,leftmargin=2cm]
192 \item[{\tt nostatic}] Use this when the figure is to be shown only
193 when the document is viewed interactively. No figure will appear
194 in the PDF. Almost certainly, the mandatory \verb=fig_ht= argument
195 should be zero. The sum of \verb=ht_above= and \verb=ht_below= is
196 used for the height of the interactive figure.
197 \item[{\tt done}] indicates to the browser that the {\tt .tikz}
198 should not be updated.
199 \item[{\tt skip}] TikZ files can be large and take a long time to
200 process. When this is set, the TikZ file won't be loaded and the
201 figure will appear with a default ``not available'' message.
202 \end{itemize}
203
204 When the composition of a figure is complete, it often makes sense to
205 turn on the {\tt done} and {\tt skip} flags. Using {\tt skip} saves
206 time, and {\tt done} prevents inadvertent overwriting of a {\tt .tikz}
207 file that you're happy with. However, to see the complete output, with
208 your figures, you would have to go back and tediously remove all of
209 the {\tt skip} flags. Use \verb=\NeverSkip= to avoid that tedium and
210 disable all the {\tt skip}
211 flags that occur until the next \verb=\AllowSkip=.
212
213 \subsection*{The {\tt \textbackslash FigPut} Command}
214
215 \verb=\FigPut= takes exactly the same arguments as the {\tt figput}
216 environment, but the JS code must appear in an external file. The
217 location of this external file is indicated with
218 \verb=\LoadFigureCode=. If the code is found in {\tt mydrawcode.js},
219 then
220 \begin{verbatim}
221 \LoadFigureCode{mydrawcode.js}
222 \end{verbatim}
223 must appear somewhere in the {\tt .tex} file.
224
225 It is often easier to use an external file to consolidate the drawing
226 code in fewer files (or a single file). Not only
227 does it make the {\tt .tex} file shorter and easier to navigate, but it
228 allows the use of programming tools tailored to JS. For instance,
229 the code could be written in TypeScript and compiled to JS. On the other
230 hand, if the code for the figures is brief, then it may be clearer and more
231 direct to use the {\tt figput} environment so that the code is in the
232 {\tt .tex} file.
233
234 \subsubsection*{Additional Remarks}
235
236 There is no explicit provision in \textsc{FigPut} for changing the
237 body of the text based on whether the document is to be viewed statically
238 or interactively. This is intentional. The aim is for the text and its
239 layout to be \emph{identical} in the two scenarios. However, it would
240 be relatively straightforward to set up a couple of commands like
241 \begin{verbatim}
242 \newcommand{\statictext}[1]{#1}
243 \newcommand{\intereactivetext}[1]{ }
244 \end{verbatim}
245 In the above example, anything that appears in \verb=\statictext{}=
246 will pass through to the \LaTeX\ document, while everything in
247 \verb=\interactivetext{}= will be ignored. Swap these two definitions
248 depending on whether the document is being compiled for interactive or
249 static reading.
250
251 \subsection{Workflow}
252
253 There are several phases to composing and releasing a document. The
254 first phase is a loop through writing the \LaTeX, compiling it, viewing
255 the output in a browser and generating TikZ, until the document is
256 done. Everything in the first phase is local to your machine. The
257 second phase is posting the result to a public-facing website. The
258 first phase is discussed here; see Section \ref{sec-distributing} for
259 the second phase.
260
261 \subsubsection*{Setup}
262
263 The functionality of \figput\ is given by {\tt figput.sty}. It
264 requires the following packages: {\tt zref}, {\tt xsim}, {\tt tikz}
265 and {\tt verbatim}.
266
267 A typical arrangement is to have a {\tt javascript}
268 directory with the files for the browser side of the framework, and a
269 \LaTeX\ directory where the document is written in the usual way. The {\tt
270 javascript} directory contains the JS files and the one HTML file needed
271 to provide the browser front-end, and you'll also find {\tt server.py}.
272 This Python script runs a local server so that your browser can
273 open and view the document being written.\footnote{This requires
274 Python 3 -- although that's probably obvious these days.} In principle, it's no
275 different than a normal web-server, but it is tailored in several
276 ways to the task at hand. To invoke this server, use the command-line
277 to go to the {\tt javascript} directory and type
278 \begin{verbatim}
279 python server.py directory/nameof.pdf [port_num]
280 \end{verbatim}
281 The {\tt directory/nameof.pdf} argument is required and should be the
282 path from the current ({\tt javascript}) directory to the PDF being
283 generated by \LaTeX. Often, this will be something like
284 \begin{verbatim}
285 ../../latex_area/num_theory/hairy_math.pdf
286 \end{verbatim}
287 The optional \verb=port_num= argument indicates the TCP/IP port on which the
288 server will listen. It defaults to 8000. In principle, any integer in
289 the range $[0,2^{16})$ could appear here, but certain values are
290 restricted and others may already be in use. Stick to values
291 in the range 8000-8100, and you should be safe.\footnote{See
292 \verb=en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers=}
293
294 By using different port numbers, it's possible to run several servers
295 at once, so that multiple documents can be viewed and edited at the
296 same time. Once the server is running, point your browser to
297 \verb=localhost:8000= (or whatever \verb=port_num= you've chosen) to
298 load the document.
299
300 As stated, {\tt server.py} differs from a normal web-server in certain
301 ways. This is done to make it easier to work with a document while it
302 is being written. Once the document is complete, it can be served by a
303 normal web-server.
304
305 \subsubsection*{Additional Files}
306
307 There are two additional directories in the {\tt javascript} directory:
308 {\tt development} and {\tt release}. \figput\ was written in
309 TypeScript, and the {\tt .ts} files are in {\tt development}. Even if
310 you don't want to modify the system, the TypeScript files are easier
311 to follow than the JavaScript files, and are the first place to look to
312 clarify how the system works internally. There are four files:
313 \begin{itemize}[itemsep=-1pt,leftmargin=1cm]
314 \item{\tt main.ts} is the main entry-point for the program. This is
315 unlikely to interest anyone who wants to simply use \figput.
316 \item{\tt layout.ts} handles page layout -- also uninteresting to most people.
317 \item{\tt widgets.ts} has the code for the various widgets. If widgets
318 aren't acting the way you expect, then look here.
319 \item{\tt tikz.ts} handles lower-level geometry, and conversion from
320 JS to TikZ. Look here for details about the {\tt Point2D} and
321 {\tt FPath} classes.
322 \end{itemize}
323
324 Two files found in the {\tt javascript} directory are {\tt
325 pdf.worker.min.js} and {\tt pdf.js}. These are the source files for
326 Mozilla's pdf.js library. The complete project can be found at
327 \verb=github.com/mozilla/pdf.js=. The files are included here because,
328 when developing a \LaTeX\ document on your local machine, it would be
329 pointless (and slow) to download these files every time an updated
330 version of your document is loaded.
331
332 The {\tt release} directory contains the files to be used when the
333 document is released to a public-facing website. As noted above, {\tt
334 server.py} works differently than a normal web-server. The release
335 process is discussed in more detail in Section \ref{sec-distributing}.
336
337 \subsubsection*{From JavaScript to TikZ}
338
339 Once the server is running, a browser can view documents created with
340 \figput, but the figures will not be visible in
341 the PDF document until a TikZ file is provided. The \emph{Get TikZ}
342 button in the browser window generates the TikZ files. The server
343 will save these files to the same directory as the PDF file. Note that
344 a TikZ file will only be generated if the figure has been scrolled
345 into view (or nearly into view) since the document was loaded.
346
347 Because TikZ files can take time to load, it's often useful to
348 compose the figures one (or a few) at a time. Apply the optional
349 {\tt done} argument for any figures that are complete, and the
350 \emph{Get TikZ} button will not generate TikZ files for them. You may
351 want a particular frame from an animation; once you have the right
352 frame, it would be frustrating to accidentally overwrite it in the course of
353 working on some other figure. Using {\tt done} prevents that from happening.
354
355 \subsection{JavaScript Drawing}
356
357 In most respects, any JS code can be used with FigPut, but it must be
358 possible to translate the JS drawing commands to TikZ, and that leads
359 to certain requirements. In a nutshell, all drawing must be done using a
360 class that is very similar to JS's built-in {\tt Path2D} class.
361
362 If this is too restrictive, then it is possible to side-step the
363 requirement with a bit of extra effort. If you use JS drawing commands
364 that are off-limits, like {\tt drawImage()}, then the interactive version
365 will work fine, but you'll have to find some other way to generate the
366 figure for inclusion in the static PDF. Any of the usual methods of
367 generating figures for \LaTeX\ documents will work, but now the two
368 versions, interactive and static, are generated from different
369 source-code.
370
371 Earlier, in a footnote on p. \pageref{page-ctx}, it was a stated that
372 the {\tt ctx} argument to your drawing function has the standard JS type, {\tt
373 CanvasRenderingContext2D}. That's not always true. Any drawing
374 done \emph{to the browser} is \emph{precisely} an object of this
375 type. If you only care about seeing your document within the browser
376 framework, and you don't care about generating figures for a
377 standalone {\tt .pdf} file, then that's all you need to know. Draw
378 with JS however you like.
379
380 To produce TikZ output, the built-in {\tt CanvasRenderingContext2D}
381 must be ``spoofed.'' All of the drawing commands that normally go to
382 the built-in JS browser code go to \figput's {\tt CTX} class
383 instead, where they are converted to TikZ output.
384 This class implements a sub-set of the full list of drawing
385 commands normally available. The permitted commands are
386 \begin{verbatim}
387 ctx.fill()
388 ctx.stroke()
389 ctx.lineWidth
390 \end{verbatim}
391 These work almost as they normally do. The {\tt lineWidth} is the
392 thickness of any paths, and can be thought of as being in \TeX's {\tt
393 bp} units. The {\tt fill()} and {\tt stroke()} commands normally
394 take a JS {\tt Path2D} object, but you should pass an object of type
395 {\tt FPath} instead.
396
397 The methods of {\tt FPath} listed below are exactly like those found
398 in {\tt Path2D}. They add a new segment to an existing {\tt FPath},
399 obtained with {\tt new}. See any JS resource for an explanation.
400 \begin{itemize}[itemsep=-1pt,leftmargin=*]
401 \item {\tt closePath()}
402 \item {\tt moveTo()}
403 \item {\tt lineTo()}
404 \item {\tt bezierCurveTo()}
405 \item {\tt ellipse()}
406 \end{itemize}
407 And these methods of {\tt FPath} are new -- they have no counterpart
408 in {\tt Path2D}.
409 \begin{itemize}[itemsep=-1pt,leftmargin=*]
410 \item {\tt addPath(p)} appends the {\tt FPath}, {\tt p}, to an
411 existing {\tt FPath}.
412 \item {\tt translate(p)} translates an {\tt FPath} by the given {\tt Point2D}.
413 \item {\tt rotate(angle)} rotates an {\tt FPath} by the given angle,
414 in radians.
415 \item {\tt scale(s)} scales an {\tt FPath} by the given factor
416 (relative to the origin).
417 \item {\tt reflectX()} reflects an {\tt FPath} across the $x$-axis.
418 \item {\tt reflectXY()} reflects an {\tt FPath} across the $x$ and $y$-axis.
419 \item {\tt rotateAbout(angle,p)} rotates a given {\tt FPath} about the
420 given {\tt Point2D} by the given angle.
421
422 The methods above apply to an existing {\tt FPath} and return a new {\tt FPath}.
423 \item {\tt parametricToBezier(f,t0,t1,n)} converts a parametric
424 function, {\tt f(t)}, to a path consisting of {\tt n} B\'ezier
425 curves as {\tt t} runs from {\tt t0} to {\tt t1}. The function
426 must be defined to return {\tt Point2D} objects.
427
428 This is a static method, so it returns a new {\tt FPath} that is unrelated to any existing {\tt FPath} objects.
429 \end{itemize}
430 There are several additional methods in {\tt FPath} that may be
431 useful, but they haven't yet been tested well enough to mention
432 here (and they may change in the future). See the source code if
433 you're adventurous.
434
435 Several of the methods above mention the {\tt Point2D} class, and it's what you would expect. Use
436 \begin{verbatim}
437 new Point2D(x,y);
438 \end{verbatim}
439 to create these objects. There's a long list of methods defined in the
440 class: {\tt translate()}, {\tt rotate()}, {\tt length()},
441 \emph{etc}. See the source code for a complete list.
442
443 Text is drawn in a way that is further from how it's normally done in
444 JS. Instead of calling {\tt ctx.fillText()}, there are three top-level
445 functions (not part of any class) for drawing text:
446 \begin{verbatim}
447 drawText(ctx,txt,x,y,dx,dy);
448 drawTextBrowserOnly(ctx,txt,x,y,dx,dy);
449 drawTextTikZOnly(ctx,txt,x,y,dx,dy);
450 \end{verbatim}
451 The arguments are the same in the three cases, but the first function will draw
452 text to both the browser window and the TikZ, while the other two will
453 draw the text to only one destination or the other. The {\tt ctx} is
454 the same as the argument to your drawing function, {\tt txt} is the
455 string to be drawn, {\tt x,y} is the location of the text \emph{for
456 the browser}, relative to the lower-left corner of the
457 bounding-box. When the text is drawn to TikZ, it is drawn at {\tt
458 x+dx,y+dy}. Because the fonts used in the browser and in TikZ differ
459 slightly, sometimes it's necessary to tweak the TikZ placement. Setting
460 \begin{verbatim}
461 ctx.font = '10px san-serif';
462 \end{verbatim}
463 sets the browser font to something very close the default font used
464 by TikZ, but it's not a perfect match. The {\tt dx} and {\tt dy}
465 arguments are optional and default to {\tt 0}.
466
467 As a bonus, the static method, {\tt Numerical.newton()}, can be used to
468 solve $f(x) = y$ for $x$, given $y$. It's a naive implementation of Newton-Raphson.
469
470 \subsection{JavaScript Widgets}
471
472 The foregoing framework could be used an an alternative to TikZ,
473 PSTricks, MetaPost, \emph{etc.}, if your aim is strictly static
474 output. To make the figures interactive, there must be some means to
475 accept user input -- widgets.
476
477 All widgets have a static {\tt register()} method. Do not use {\tt
478 new} to create widgets! Registering a widget has the effect of
479 making it available for user input, and drawing it too (with one
480 exception). The arguments to these {\tt register()} methods vary with
481 the widget, but the first argument is always the {\tt ctx} known to
482 the drawing function, and the last argument is always a {\tt name} (a
483 string). One drawing could have several widgets of the same kind and
484 {\tt name} is used to distinguish
485 them. So, if a particular drawing has three buttons, then they could
486 be created/registered with
487 \begin{verbatim}
488 let b1 = ButtonWidget.register(ctx,...,"first");
489 let b2 = ButtonWidget.register(ctx,...,"second");
490 let b3 = ButtonWidget.register(ctx,...,"third");
491 \end{verbatim}
492 These names only need to be unique within a single drawing and one
493 type of widget. So, in the example above, two {\tt
494 DraggableDotWidget}s could be registered in the same drawing as
495 the {\tt ButtonWidget}s with
496 \begin{verbatim}
497 let dd1 = DraggableDotWidget.register(ctx,...,"first");
498 let dd2 = DraggableDotWidget.register(ctx,...,"second");
499 \end{verbatim}
500
501 \subsubsection{\tt ButtonWidget}
502
503 These are registered with
504 \begin{verbatim}
505 ButtonWidget.register(ctx,x,y,text,name);
506 \end{verbatim}
507 The {\tt x,y} argument is the location of the button, relative to the
508 lower-left corner. The {\tt text} is what is shown as the message
509 within the button. Buttons work by calling back to your drawing code
510 whenever they are clicked. Every time the button is clicked, the
511 entire drawing function is executed.
512
513 There are two useful fields of {\tt ButtonWidget}. If {\tt b} is a
514 {\tt ButtonWidget}, then {\tt b.clickState} toggles between {\tt true} and {\tt
515 false} with every click of the button, while {\tt b.resetState} is
516 set to {\tt true} whenever the button is clicked -- and remains {\tt
517 true} until your drawing code resets it.
518
519 \subsubsection{\tt NumberInputWidget}
520
521 This is similar to {\tt ButtonWidget}, and is used to input single
522 numbers. It's registered with
523 \begin{verbatim}
524 NumberInputWidget.register(ctx,x,y,v,name);
525 \end{verbatim}
526 The {\tt v} argument is the initial numerical value shown in the
527 widget. Whenever the user changes this value, the widget calls back
528 and executes the entire drawing function. To obtain this value, call
529 {\tt getValue()} on the relevant widget. Because this widget relies
530 on HTML, {\tt getValue()} returns a string. It may be necessary to
531 call the JS {\tt parseFloat()} or {\tt parseInt()} functions on this
532 value.
533
534 \subsubsection{\tt DraggableDotWidget}
535
536 A ``draggable dot'' is a small dot that can be grabbed by the mouse
537 and moved around. They're registered with
538 \begin{verbatim}
539 DraggableDotWidget.register(ctx,x,y,name);
540 \end{verbatim}
541 To determine where the user has moved a dot, refer to the widget's
542 {\tt widgetX} and {\tt widgetY} fields.
543
544 Most widgets are used ``off to the side'' and wouldn't normally
545 interfere with the way the figure is drawn, but these dots are typically
546 used as part of the drawing itself. The order in which dots are drawn
547 may matter. Sometimes a dot should be drawn first, so that other
548 elements of the figure may be drawn over it; and sometimes a dot
549 should be drawn last so that nothing can obscure it. For this
550 reason, unlike other widgets, registering the widget does not also
551 draw the widget. An explicit call to the widget's {\tt
552 draw(ctx)} method must be made to draw the dot.
553
554 \subsubsection{\tt DraggableDrawWidget}
555
556 This is similar to {\tt DraggableDotWidget}, but it has no default
557 drawing behavior. The user must provide functions to specify what is
558 to be drawn. So it can also be a draggable polygon, or a draggable
559 anything-you-can-draw. Register these with
560 \begin{verbatim}
561 DraggableDrawWidget.register(ctx,x,y,
562 drawFcn,drawSelFcn,testPosFcn,
563 name);
564 \end{verbatim}
565 The {\tt drawFcn} must be defined to take the {\tt ctx} as the sole
566 argument. It can draw whatever it wants, noting that the origin is
567 shifted so that drawing should typically take place relative to {\tt
568 (0,0)}, not {\tt (widgetX,widgetY)}. In most cases, this means
569 that the drawing code is independent of where the item is on the
570 page. {\tt drawFcn} must return an {\tt FPath} object to indicate
571 the ``clickable area'' for the item. For example, if what is being
572 drawn is a small square, then the function might be defined as
573 \begin{verbatim}
574 function drawSquare(ctx) {
575 let p = new FPath();
576 // p.lineTo, moveTo, etc., to make a square.
577 ctx.fillPath(p);
578 return p;
579 }
580 \end{verbatim}
581 The value returned is noted, and any click in the interior of the path
582 -- as determined by the JS function {\tt isPointInPath()} --
583 is taken to be a valid click on the object, to select it and drag it around.
584
585 The {\tt drawSelFcn} argument to {\tt register} is identical to the
586 {\tt drawFcn} argument, but it is called to draw the item when it is
587 ``selected.'' Often, the only difference between the two functions
588 will be the color used to draw the item.
589
590 The {\tt testPosFcn} argument is used to determine whether a
591 particular location for the item is acceptable. For example, an item
592 could be limited to a particular region. This is called every time the
593 mouse is moved, after the item has been selected, up until the mouse
594 button is released. The function takes five arguments and returns a
595 boolean. The five arguments are the proposed {\tt x,y} position (the
596 mouse location), followed by the width of the drawing area, then the
597 height above and below the $x$-axis, where the width is equal to the
598 text width. Return {\tt true} if the
599 proposed {\tt x,y} is acceptable; {\tt false} otherwise. At a minimum,
600 the function should typically check that {\tt x,y} is inside the
601 figure rectangle.
602
603 \subsubsection{\tt LoopAnimWidget}
604
605 This widget and the next one ({\tt OpenAnimWidget}) are for
606 animations, and work similarly. A {\tt LoopAnimWidget} is used for
607 animations that run in a repeating loop. There are many arguments to
608 register them.
609 \begin{verbatim}
610 LoopAnimWidget.register(ctx,x,y,scale,visWidget,
611 steps,start,timeStep,
612 visSteps,visFastSlow,visPauseRun,visCircle,triGrab,
613 name);
614 \end{verbatim}
615 The {\tt x,y} values are the location of the center of the circle that
616 is the primary element of the widget. The widget can be made larger or
617 smaller by changing the {\tt scale} -- a value of {\tt 1.0} makes the
618 circle 40~{\tt bp} in radius. The {\tt visWidget} argument is a
619 boolean; set it to {\tt false} to run an animation without
620 showing the user this widget.
621
622 {\tt steps} is the integral number of steps that make up one loop of
623 the animation. {\tt start} is the step on which the animation
624 starts -- so that the animation starts with the {\tt start}-th
625 frame. {\tt timeStep} is the number of milliseconds between
626 frames. Unless the machine is \emph{very} fast, anything less than
627 {\tt 10} for {\tt timeStep} is probably pointless, and a setting of
628 {\tt 50} or {\tt 75} is more reasonable considering the human eye.
629
630 The next group of arguments -- {\tt visSteps} through {\tt triGrab} -- are
631 all booleans. They determine whether certain parts of the widget are
632 visible. {\tt visSteps} shows or hides an area above the circle that
633 can be used to change the number of steps taken per frame. The user
634 can use this control to skip frames of the animation. {\tt
635 visFastSlow} is for some ``sideways chevrons,'' in an area below the circle,
636 that allow the user to change the number of milliseconds per
637 frame. {\tt vsPauseRun} is for a pause/run control below the
638 circle. {\tt visCircle} is for the entire circle. The circle has a
639 small grabable triangle to indicate which frame is being shown; use
640 {\tt triGrab} to show or hide the triangle.
641
642 To draw a particular frame from your drawing function, refer to the
643 {\tt curStep} field of the object. This will be a value in the range
644 from 0 to the {\tt steps} argument to {\tt register()}.
645
646 \subsubsection{\tt OpenAnimWidget}
647
648 This widget is for open-ended animations that don't run in a loop,
649 but continue ``forever.'' Whereas {\tt LoopAnimWidget} indicates the
650 frame being viewed relative to a circle, {\tt OpenAnimWidget} uses a
651 bar, something like a scroll-bar. Registration is similar to
652 {\tt LoopAnimWidget}:
653 \begin{verbatim}
654 OpenAnimWidget.register(ctx,x,y,scale,width,visWidget,
655 timeStep,decay,
656 visSteps,visFastSlow,visPauseRun,visBar,barGrab,
657 name);
658 \end{verbatim}
659 The {\tt ctx}, {\tt x}, {\tt y}, {\tt scale} and {\tt visWidget}
660 arguments are as for {\tt LoopAnimWidget}. {\tt width} sets the width
661 of the bar, in {\tt bp}.
662
663 {\tt timeStep} is in milliseconds, as for {\tt LoopAnimWidget}. The
664 {\tt decay} is used to adjust the rate of travel of the ``thumb'' along the
665 bar as the animation progresses. Since the animation is potentially
666 infinite, the thumb moves quickly early in the animation, then moves
667 more and more slowly, so that it never quite reaches the end of the
668 bar. The position of the thumb is given by
669 $$1 - {1\over (1+{\tt decay})^s},$$
670 expressed as a fraction of the bar's total length, where $s$ is the
671 frame count (\emph{i.e.}, {\tt curStep}). A reasonable setting for {\tt
672 decay} is something in the range of $10^3$ to $10^6$, although it
673 will depend on the animation.
674
675 The arguments from {\tt visSteps} to {\tt barGrab} are all boolean and
676 control which controls that make up the widget are visible. They're
677 like their counterparts in {\tt LoopAnimWidget}, except that {\tt
678 OpenAnimWidget} uses a bar instead of a circle.
679
680 \section{Distributing a Complete Document}
681 \label{sec-distributing}
682
683 The PDF document is no different than any other PDF, and can be
684 distributed in the usual ways. When moving the document in interactive
685 form to a public-facing website, a few steps are necessary.
686
687 See the {\tt javascript/release} directory. It has two files: {\tt
688 figput.html} and {\tt figput.js}. The {\tt .js} file is just the
689 four files used for the local version ({\tt main.js}, \emph{etc}.),
690 consolidated to a single file and minified. These two files must
691 appear on the web-server in the same directory as the various files
692 that make up your document.
693
694 {\tt figput.html} is only a few lines long, and there are two
695 important changes that must be made. See the line that reads
696 \vskip 0.2cm
697 \noindent\verb!<body onload="doOpenDocument('unknown1',unknowny)" id="mainbody">!
698 \vskip 0.2cm
699 \noindent Change {\tt unknown1} to your document's name, \emph{without} the
700 {\tt .pdf} suffix. If the document was generated from {\tt
701 example.tex}, then {\tt unknown1} should be changed to {\tt example}.
702 Second, change {\tt unknowny} to {\tt 0}. When the document is
703 opened, this is the vertical position, in {\tt bp}, at which the document is
704 opened. Setting {\tt unknonwy} to {\tt 0} means that the document
705 will open at the top of the first page. Of course, it's possible
706 that you want the document to open at some other location, in which
707 case use some other value for {\tt unknowny}.
708
709 The server needs {\tt figput.html} (after the modifications
710 above), {\tt figput.js}, and the files that make up your
711 document. These files consist of the {\tt .pdf} file, the {\tt .fig.aux}
712 file, any {\tt .js} files referred to by \verb=\LoadFigureCode=, plus
713 any {\tt .fjs} files generated by your document. The server does not
714 need the {\tt .tikz} files.
715
716 \section{Code Internals}
717
718 An understanding of this section isn't necessary to use \figput; it's
719 here to provide a bit of background for anyone who wants to improve
720 or modify the framework. Most of \figput\ is in TypeScript, which
721 should make it easier to follow.
722
723 Throughout the various files that make up the system are
724 {\tt BUG} annotations. These are not bugs \emph{per se}, but are more
725 like infelicities, opportunities for improvement, or to draw attention
726 to something confusing or problematic. If you want to contribute to
727 \figput, then these are a good place to start.
728
729 \subsection{\tt figput.sty}
730
731 The {\tt .sty} file is well-commented and should be
732 self-explanatory. However, I am far from an expert in \LaTeX3
733 programming. Here is a high-level list of ways in which it might be
734 possible to improve things.
735
736 \begin{itemize}[itemsep=-1pt,leftmargin=*]
737 \item {\tt figput.sty} is written for \LaTeX3. The entire thing might
738 be simpler if it were in Lua\TeX.
739 \item The ability to explicitly specify the inner and outer margins
740 used by \figput\ (with \verb=\SetInnerMargin= and
741 \verb=SetOuterMargin=) is useful, but it would often suffice to
742 default to the margins used by \LaTeX. How can those values be
743 obtained?
744 \item Someone who is more expert in \LaTeX3 could improve the code's
745 clarity and brevity.
746 \item It would be nice if \figput\ could create figures within a {\tt
747 minipage}, but that would require extensive changes to both the
748 \LaTeX\ and browser code.
749 \end{itemize}
750
751 \subsubsection*{A Quirk}
752
753 \LaTeX\ on Windows has a quirk. \TeX\ will not write to a
754 file whose type is executable. Thus, it won't write to
755 a {\tt .pl} file (Perl), {\tt .py} (Python) file, \emph{etc.},
756 depending on how the machine is set up. \figput\ creates
757 JavaScript files, which are typically saved as {\tt .js} files, and
758 these may be seen as executable by Windows. Fortunately,
759 browsers doesn't care what the suffix is, so \figput\ uses
760 {\tt .jfs} as the suffix.
761
762 This limitation on the file name suffix applies to \verb=\write=, but
763 not to \verb=\write18=. \TeX\ is limited in this way to prevent
764 accidental errors and for security. One solution might be to have the
765 package write files using an acceptable suffix, then change the
766 suffix with \verb=\write18=, which does not have this
767 limitation. However, to use \verb=\write18= this way, \LaTeX\ would
768 have to be invoked with something like
769 \begin{verbatim}
770 pdflatex -shell-escape
771 \end{verbatim}
772 which would be annoying.
773
774 \subsection{\tt server.py}
775
776 The server is a simple thing, so there's not much to say. It
777 would be nice if it were written in a compiled language so
778 that the user doesn't need to install Python.
779
780 \subsection{Browser Code}
781
782 This part is written in TypeScript (TS), which is essentially JS with
783 type annotations. It must be translated
784 to JS for the browser to run it, but TS code is easier to follow, and
785 the type information heads off many programming errors.
786
787 Although the program is (to my knowledge!) bug-free in the usual
788 sense, there are plenty of {\tt BUG} annotations to draw attention to
789 places where the code could be improved. Some of the higher-level
790 possibilities for improvement are noted below.
791 \begin{itemize}[itemsep=-1pt,leftmargin=*]
792 \item \figput\ relies on the {\tt pdf.js} library for rendering
793 PDFs. The result is not as crisp as I would like. It's unclear
794 whether the problem is with the library itself, or how it is being
795 used. Someone who knows that library well may be able to improve the
796 output. Maybe a different library would work better.
797 \item Most of the widgets do not rely on the DOM, but {\tt
798 NumberInputWidget} and {\tt ButtonWidget} are based on the built-in
799 DOM elements. It would be nice if these didn't use the DOM.
800 \item Many additional widgets could be created.
801 \item Adjust the font used for figures in the browser to make it more
802 nearly identical to what appears in the PDF.
803 \item Color is entirely neglected on the \LaTeX\ end of \figput. Browser output
804 can be colored arbitrarily (with {\tt ctx.fillStyle} or {\tt
805 ctx.strokeStyle}, as usual), but the TikZ output is limited to
806 black and white.
807 \item Double-buffer everything. Animations seem to run fine,
808 without any noticeable flicker, but double-buffering \emph{all}
809 drawing would put an end to any concerns about flicker.
810 \item Animations should be turned off and stop generating events when
811 they are scrolled out of view. This would save CPU cycles, which may
812 matter for documents with many animations.
813 \end{itemize}
814
815 \noindent And some items that are more ambitious...
816 \begin{itemize}[itemsep=-1pt,leftmargin=*]
817 \item Allow figures to be set within a {\tt minipage} (mentioned above).
818 \item Double-clicking a figure (or something) could enlarge the figure
819 to give more room for interaction.
820 \item Come up with a scheme so that the code that draws a figure could
821 be made part of the document. For certain topics, the code that
822 draws a figure can be as instructive as the figure itself.
823 \item Extend the framework somehow so that it can be used within an
824 IDE. Code that's mathematically-oriented is difficult to
825 document within source code using simple text. It would be easier to
826 understand if it's explained as \LaTeX\ output that appears
827 in the source code, rather than in a separate document.
828 \item Extend the framework to allow inclusion of snippets of
829 \LaTeX\ output in standard HTML documents. Things like KaTeX and
830 MathJax are convenient, but incomplete relative to \LaTeX.
831 \end{itemize}
832
833 \newpage
834
835 \subsection*{Version History}
836
837 \begin{itemize}[itemsep = -3pt]
838 \item{0.90} -- July 21, 2022. I've been using this, privately, for
839 several months. Numerous improvements and extensions are possible,
840 but it definitely works.
841 \end{itemize}
842
843
844 \vskip 0.3cm
845 \hrule
846 \vskip 0.3cm
847
848
849 Thanks to Dan Pratt for insights regarding TypeScript, and
850 improvements to the code.
851
852 Several people on {\tt tex.stackexchange} very
853 patiently answered numerous questions. Thank you.
854
855
856
857 \end{document}