diff options
Diffstat (limited to 'macros/luatex/generic/barracuda/doc/barracuda.tex')
-rw-r--r-- | macros/luatex/generic/barracuda/doc/barracuda.tex | 413 |
1 files changed, 0 insertions, 413 deletions
diff --git a/macros/luatex/generic/barracuda/doc/barracuda.tex b/macros/luatex/generic/barracuda/doc/barracuda.tex deleted file mode 100644 index 0fc6fbac28..0000000000 --- a/macros/luatex/generic/barracuda/doc/barracuda.tex +++ /dev/null @@ -1,413 +0,0 @@ -% !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} |