summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/barracuda/doc/barracuda.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/barracuda/doc/barracuda.tex')
-rw-r--r--macros/luatex/generic/barracuda/doc/barracuda.tex331
1 files changed, 331 insertions, 0 deletions
diff --git a/macros/luatex/generic/barracuda/doc/barracuda.tex b/macros/luatex/generic/barracuda/doc/barracuda.tex
new file mode 100644
index 0000000000..e5d6b6acdb
--- /dev/null
+++ b/macros/luatex/generic/barracuda/doc/barracuda.tex
@@ -0,0 +1,331 @@
+% !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}