summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/barracuda/doc/barracuda.tex
blob: 0fc6fbac28dde6f261d2ec06cfd4eb4d46b90470 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
% !TeX program = LuaLaTeX
% Copyright (C) 2020 Roberto Giacomelli
% Barracuda manual, main TeX source file

\documentclass[11pt,a4paper]{article}
\usepackage{fontspec}
\usepackage{geometry}
\usepackage{fancyvrb}
\usepackage{graphicx}
\usepackage{hyperref}

% special macro for manual typesetting
\input{barracuda-manual-tool}

\hypersetup{
hidelinks,
linktoc = all,
pdfinfo={
    Title={the Barracuda manual},
    Subject={Barcode printing package},
    Author={Roberto Giacomelli},
    Keywords={Barcode EAN Code128 Lua}
}}

\setmainfont{Libertinus Serif}
\setmonofont[Scale=0.82]{Fira Mono}
\fvset{
    fontsize=\small,
    frame=single,
    labelposition=topline,
    framesep=5pt
}
\geometry{
    left=32mm,
    right=40mm,
    top=22mm,
    bottom=28mm
}

\author{Roberto Giacomelli\\\small email: \url{giaconet.mailbox@gmail.com}}
\title{the \code{barracuda} manual\\[1ex]
\small \url{https://github.com/robitex/barracuda}}
\date{\small Date \brcdkey{date} --- Version \brcdkey{version} --- Beta stage}

\begin{document}
\maketitle

\abstract{%
Welcome to the \brcd{} software project devoted to barcode printing.

This manual shows you how to print barcodes in your \TeX{} documents and how to
export such graphic content to an external file, using \brcd{}.

\brcd{} is written in Lua programming language and is free software released
under the GPL 2 License.%
}

\tableofcontents
\newpage


\section{Getting started}
\label{secStart}

\subsection{Introduction}
\label{secIntro}

Barcode symbols are usually a sequence of vertical lines representing encoded
data that can be retrived with special laser scanner or more simpler with a
smartphone running dedicated apps. Almost every store item has a label with a
printed barcode for automatic identification purpose.

So far, \brcd{} supported symbologies are as the following:
\begin{itemize}
	\item Code 39,
	\item Code 128,
	\item EAN family (ISBN, ISSN, EAN 8, EAN 13, and the add-ons EAN 2 and EAN 5),
	\item ITF 2of5, interleaved Two of Five.
\end{itemize}

The package provides different output graphic format. At the moment they are:
\begin{itemize}
	\item PDF Portable Document Format (a modern \TeX{} engine is required),
	\item SVG Scalable Vector Graphic.
\end{itemize}

The name \brcd{} is an assonance to the name Barcode. I started the project back
in 2016 for getting barcode in my \TeX{} generated PDF documents, studying the
Lua\TeX{} technology such as direct \emph{pdfliteral node} creation.

At the moment \brcd{} is in \emph{beta} stage. In this phase the Lua API can
change respect to the result of development research.


\subsection{Manual Content}

The manual is divided into five part. In part~\ref{secIntro} introduces the
package and gives to the user a proof of concept to how to use it. The next
parts present detailed information about option parameter of each barcode
symbology and methods description to change the \emph{module} width of a EAN-13
barcode. It's also detailed how the Lua code works internally and how to
implement a barcode symbology not already included in the package.

The plan of the manual is (but some sections are not completed yet):
\begin{description}
\item[Part 1:] Getting started
\begin{itemize}
	\item general introduction \( \to \) \pageref{secIntro}
	\item print your first barcode \( \to \) \pageref{secEnter}
	\item installing \brcd{} on your system \( \to \) \pageref{secInstall}
\end{itemize}

\item[Part 2:] \LaTeX{} packages
\begin{itemize}
	\item \brcd{} \LaTeX{} package \( \to \) \pageref{secLaTeXPkg}
\end{itemize}

\item[Part 3:] Barcode Reference and Parameters
\begin{itemize}
	\item encoder identification rule \( \to \) \pageref{secEncName}
	\item barcode symbologies reference \( \to \) \pageref{secBcRef}
\end{itemize}

\item[Part 4:] Advanced Work with \brcd{}
\begin{itemize}
	\item Lua framework description \( \to \) \pageref{secFramework}
	\item API reference \( \to \) \pageref{secAPI}
	\item \code{ga} specification \( \to \) \pageref{secGA}
\end{itemize}

\item[Part 5:] Real examples
\begin{itemize}
	\item working example and use cases \( \to \) \pageref{secExample}
\end{itemize}
\end{description}


\subsection{Required knowledge and useful resources}

\brcd{} is a Lua package that can be executed by any Lua interpreter. To use it,
it's necessary a minimal knowledge of Lua programming language and a certain
ability with the terminal of your computer system in order to run command line
task or make software installation.

It's also possible to run \brcd{} directly within a \TeX{} source file, and
compile it with a suitable typesetting engine like Lua\TeX{}. In this case a
minimal \TeX{} system knowledge is required. As an example of this workflow you
simply can look to this manual because itself is typesetted with LuaLa\TeX{},
running \brcd{} to include barcodes as a vector graphic object.

A third way is to use the \LaTeX{} package \code{barracuda.sty} with its high
level macros. A minimal knowledge of the \LaTeX{} format is obviously required.

Here is a collection of useful learning resources:
\begin{description}
\item[Lua:] to learn Lua the main reference is the book called PIL, Programming
in Lua from one of the language's Author Roberto Ierusalimschy.
\item[\LaTeX:] \dots
\item[Lua\TeX:] \dots
\end{description}


\subsection{Running Barracuda}
\label{secEnter}

The starting point to work with \brcd{} is always a plain text file with some
code processed by a command line program with a Lua interpreter.

The paradigm of \brcd{} is the Object Oriented Programming. Generally speaking
every object must be created with a function called \emph{costructor} and every
action must be run calling a \emph{method} of it.

In this section you'll take a taste of \brcd{} coding in three different
execution context: a Lua script, a Lua\TeX{} document and a \LaTeX{} source file
using the macro package \code{barracuda.sty} providing an high level interface
to Lua code.

High level package like \code{barracuda.sty} make to write Lua code unnecessary.
It will be always possible return to Lua code in order to resolve complex
barcode requirements.


\subsubsection{A Lua script}

As a practical example to produce an EAN~13 barcode, open a text editor of your
choice on an empty file and save it as \code{first-run.lua} with the content of
the following two lines of code:
\medskip
\begin{Verbatim}[label=\footnotesize\code{first-run.lua}]
local barracuda = require "barracuda"
barracuda:save("ean-13", "8006194056290", "my_barcode", "svg")
\end{Verbatim}

What you have done is to write a \emph{script}. If you have installed a Lua
interpreter along with \brcd{}, open a terminal and run it with the command:
\begin{Verbatim}
$ lua first-run.lua
\end{Verbatim}

You will see in the same directory of your script, appearing a new file called
\code{my\_barcode.svg} with the drawing:
\begin{center}
\includegraphics{image/8006194056290}
\end{center}

Coming back to the script first of all, it's necessary to load the library
\brcd{} with the standard Lua function \code{require()} that returns an
object---more precisely a reference to a table where are stored all the
package machinery.

With the second line of code, an EAN~13 barcode is saved as
\code{my\_barcode.svg} using the method \code{save()} of the \brcd{} object. The
\code{save()} method takes in order the barcode symbology identifier called
\emph{treename}, an argument as a string or as a whole number that represents
data to be encoded, the output file name and the optional output format. With a
fifth optional argument we can pass options to the barcode encoder as a Lua
table.

Each encoder has an own identifier called treename explained at
section~\ref{secEncName}. In short, in \brcd{} we can build more encoders of the
same symbology with different parameters.


\subsubsection{A Lua\TeX{} source file}

\brcd{} can also runs with Lua\TeX{} and any others Lua powered \TeX{}
engines. The source file is a bit difference respect to the previuos script: the
Lua code lives inside the argument of a \verb=\directlua= primitive, moreover we
must use an horizontal box register as output destination.
\begin{Verbatim}
% !TeX program = LuaTeX
\newbox\mybox
\directlua{
	local require "barracuda"
	barracuda:hbox("ean-13", "8006194056290", "mybox")
}\leavevmode\box\mybox
\bye
\end{Verbatim}

The method \code{hbox()} works only with Lua\TeX{}. It takes three\footnote{A
fourth argment is optional as a table with user defined barcode parameters.}
arguments: encoder \emph{treename}, encoding data as a string, the \TeX{}
horizontal box name.


\subsubsection{A Lua\LaTeX{} source file}

\LaTeX{} working minimal example would be:
\begin{Verbatim}
% !TeX program = LuaLaTeX
\documentclass{article}
\usepackage{barracuda}
\begin{document}
\barracuda{ean-13}{8006194056290}
\end{document}
\end{Verbatim}


\subsection{A more deep look}

\brcd{} is designed to be modular and flexible. For example it is possible to
draw different barcodes on the same canvas or tune barcode parameters. 

The main workflow to draw a barcode object reveals more details on internal
structure. In fact, to draw an EAN~13 barcode we must do at least the following
steps:
\begin{enumerate}
\item load the library,
\item get a reference to the \code{Barcode} abstract class,
\item build an \code{ean} encoder of the variant \code{13},
\item build an EAN~13 symbol passing data to a costructor,
\item get a reference to a new canvas object,
\item draw barcode on the canvas object,
\item get a reference of the driver object,
\item print the graphic material saving an external \code{svg} file.
\end{enumerate}

Following that step by step procedure the corresponding code is translated in
the next listing:
\begin{Verbatim}
-- lua script
local barracuda = require "barracuda" -- step 1
local barcode = barracuda:barcode() -- step 2

local ean13, err_enc = barcode:new_encoder("ean-13") -- step 3
assert(ean13, err_enc)

local symb, err_symb = ean13:from_string("8006194056290") -- step 4
assert(symb, err_symb)

local canvas = barracuda:new_canvas() -- step 5
symb:append_ga(canvas) -- step 6

local driver = barracuda:get_driver() -- step 7
local ok, err_out = driver:save("svg", canvas, "my_barcode") -- step 8
assert(ok, err_out)
\end{Verbatim}

Late the manual will give objects and methods references at
section~\ref{secAPI}.


\subsection{Installing}
\label{secInstall}

\subsubsection{Installing for Lua}

Manually copy \code{src} folder content to a suitable directory of your system
that is reachable to the system Lua interpreter.

\subsubsection{Installing for TeX Live}

If you have TeX Live installed from CTAN or from DVD TeX Collection, before any
modification to your system check if the package is already installed looking
for \emph{installed} key in the output of the command:
\begin{Verbatim}
$ tlmgr show barracuda
\end{Verbatim}

If `barracuda` is not present, run the command:
\begin{Verbatim}
$ tlmgr install barracuda
\end{Verbatim}

If you have installed TeX Live via Linux OS repository try your distribution's
package management system running a software update.

It's also possible to install the package manually:
\begin{enumerate}
\item Grab the sources from CTAN or \url{https://github.com/robitex/barracuda}.
\item Unzip it at the root of one or your TDS trees (local or personal).
\item You may need to update some filename database after this, see your \TeX{}
distribution's manual for details.
\end{enumerate}


\section{Barracuda \LaTeX{} Package}
\label{secLaTeXPkg}

The \LaTeX{} package delivered with \brcd{} is still under an early stage of
development. The only macro available is \verb=\barracuda{encoder}{data}=.
A simple example is the following source file for Lua\LaTeX{}:
\begin{Verbatim}
% !TeX program = LuaLaTeX
\documentclass{article}
\usepackage{barracuda}
\begin{document}
\leavevmode
\barracuda{code39}{123ABC}\\
\barracuda{code128}{123ABC}
\end{document}
\end{Verbatim}

Every macro \verb=\barracuda= typesets a barcode symbol with the encoder defined
in the first argument, encoding data defined by the second.


\section{Barcode parameters}
\label{secBarcodeReference}

\subsection{Encoder treename}
\label{secEncName}

TODO

\subsection{Barcode Reference}
\label{secBcRef}

TODO

\section{Developer zone}

\subsection{The Barracuda Framework}
\label{secFramework}

The \brcd{} package framework consists in indipendent modules: a barcode class
hierarchy encoding a text into a barcode symbology; a geometrical library called
\code{libgeo} representing several graphic objects; an encoding library for the
\code{ga} format (graphic assembler) and several driver to \emph{print} a ga
stream into a file or a \TeX{} hbox register.

To implement a barcode encoder you have to write a component called
\emph{encoder} defining every parameters and implementing the encoder builder,
while a driver must understand ga opcode stream and print the corresponding
graphic object.

Every barcode encoder come with a set of parameters, some of them can be
reserved and can't be edit after the encoder was build. So, you can create many
instances of the same encoder for a single barcode type, with its own parameter
set.

The basic idea is getting faster encoders, for which the user may set up
paramenters at any level: barcode abstract class, encoder globally, down to a
single symbol object.

The Barcode class is completely indipendent from the ouput driver and viceversa.

\subsection{Lua API reference}
\label{secAPI}

TODO

\subsection{\code{ga} specification}
\label{secGA}

TODO

\section{Example and use cases}
\label{secExample}

TODO

\end{document}