% !TeX program = LuaLaTeX
% Copyright (C) 2019 Roberto Giacomelli
% Barracuda manual main source file

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

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

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

\setmainfont{Libertinus Serif}
\setmonofont{IBM Plex Sans Condensed}
\fvset{
    fontsize=\small,
    frame=single,
    labelposition=topline,
    framesep=6pt
}
\geometry{
    left=32mm,
    right=40mm,
    top=28mm,
    bottom=28mm
}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\brcd}{\code{barracuda}}

\author{Roberto Giacomelli\\\small email: \url{giaconet.mailbox@gmail.com}}
\title{\code{barracuda} manual\\[1ex]
\small \url{https://github.com/robitex/barracuda}}
\date{\small 2019-12-04\\Version v0.0.9.1}

\begin{document}
\maketitle

\abstract{%
Welcome to the \brcd{} software project devoted to barcodes 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.%
}


\section{Introduction}

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 (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 drivers for different graphic format, at the moment are:
\begin{itemize}
	\item PDF Portable Document Format (require a modern \TeX{} engine),
	\item SVG Scalable Vector Graphic.
\end{itemize}

The name \brcd{} is an assonance with the name Barcode. I started the project
back in 2016 for getting barcode in my \TeX{} generated PDF documents, studying
the Lua\TeX{} technology.


\subsection{Manual Content}

The manual is divided into three parts. At section~\ref{secEnter} the first look
gives to the user a proof of concept to how to use and how works the package
while the next parts present details like how to change the \emph{module} width
of a EAN-13 barcode or 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:] Get started
\begin{itemize}
	\item print your first barcode \( \to \) \ref{secEnter}
	\item installing \brcd{} on your system \( \to \) \ref{secInstall}
	\item \brcd{} \LaTeX{} package \( \to \) \ref{secLaTeXPkg}
\end{itemize}
\item[Part 2:] Advanced Work with \brcd{}
\begin{itemize}
	\item Lua framework description \( \to \) \ref{secFramework}
	\item working example and use cases \( \to \) \ref{secExample}
\end{itemize}
\item[Part 3:] Reference and parameters
\begin{itemize}
	\item barcode symbology reference \( \to \) \ref{secBcRef}
	\item \code{ga} specification
	\item API reference \( \to \) \ref{secAPI}
\end{itemize}
\end{description}

\subsection{Required knowledge and useful resources}

The \brcd{} is a Lua package that can be executed by any Lua interpreter. To use
it, it's necessary some knowledge of Lua programming language and a certain
ability with the terminal of your computer system in order to accomplish command
tasks or software installations.

It's also possible to run \brcd{} directly from within a \TeX{} source file,
compiled with a suitable typesetting engine like Lua\TeX{}. To do so 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.

Here is a collection of useful learning resources\dots

%
%
%
%


\section{Get Started with Barracuda}
\label{secEnter}

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

As a practical example producing an EAN-13 barcode, in a text editor of your
choice on a empty file called \code{first-run.lua}, type 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 and \brcd{}, open a terminal and run the command:
\begin{Verbatim}
$ lua first-run.lua
\end{Verbatim}

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

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

We can now produce the EAN-13 barcode using the method \code{save()} of the
\brcd{} object. The \code{save()} method takes in order the barcode symbology
identifier, the data to be encoded as a string or also a whole number, the
output file name and the optional output format.


\subsection{Running Lua\TeX}

Barracuda can also running inside Lua\TeX{} and the others Lua powered \TeX{}
engine. The text source file is a bit difference respect to a Lua script: Lua
code have to bring place as the argument of directlua primitive... we must use
a box register of type horizontal...

\begin{Verbatim}
% !TeX program = LuaTeX
\nopagenumbers
\newbox\mybox
\directlua{
	local require "barracuda"
	barracuda:hbox("ean-13", "8006194056290", "mybox")
}\box\mybox
\bye
\end{Verbatim}

The method \code{hbox()} works only with Lua\TeX{}.


\subsection{A more deep look}

Barracuda 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} class,
\item build an EAN encoder,
\item build an EAN symbol passing data to a costructor,
\item get a reference to a new canvas object,
\item draw barcode on canvas,
\item get a reference of driver object,
\item address canvas toward a driver.
\end{enumerate}

Follow that step by step procedure the corresponding code is in the next
listing:
\begin{Verbatim}
local barracuda = require "barracuda"
local barcode = barracuda:get_barcode_class()

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

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

local canvas = barracuda:new_canvas()
symb:append_ga(canvas)

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


\section{Installing}
\label{secInstall}

\subsection{Installing `barracuda` for TeX Live}

If you have TeX Live installed from CTAN or from DVD TeX Collection, check
before any modification to your system 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.

It's also possible a manual installation:
\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.
\item You may need to update some filename database after this, see your \TeX{}
distribution's manual for details.
\end{enumerate}

\subsection{Installing for Lua}

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


\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 represented with the
encoder defined in the first argument, the information defined by the second.


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

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

To implement a barcode encoder you need to write a component called
\emph{encoder} defining every parameters and producing the encoder class, 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 be setting up by the user only through the encoder.

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 encoder, for which the user may set up
paramenters at any level: barcode abstract class, encoder, down to a single
symbol.

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


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

TODO

\section{Barcode Reference}
\label{secBcRef}

TODO

\section{API reference}
\label{secAPI}

TODO

\end{document}
