% !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}
