summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/barracuda/doc
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/barracuda/doc')
-rw-r--r--macros/luatex/generic/barracuda/doc/barracuda-ga-asm.tex2
-rw-r--r--macros/luatex/generic/barracuda/doc/barracuda-manual-tool.tex34
-rw-r--r--macros/luatex/generic/barracuda/doc/barracuda.pdfbin57452 -> 67784 bytes
-rw-r--r--macros/luatex/generic/barracuda/doc/barracuda.tex348
4 files changed, 249 insertions, 135 deletions
diff --git a/macros/luatex/generic/barracuda/doc/barracuda-ga-asm.tex b/macros/luatex/generic/barracuda/doc/barracuda-ga-asm.tex
index 1c403455f8..014cb9d1c4 100644
--- a/macros/luatex/generic/barracuda/doc/barracuda-ga-asm.tex
+++ b/macros/luatex/generic/barracuda/doc/barracuda-ga-asm.tex
@@ -1,5 +1,5 @@
% !TeX program = LuaLaTeX
-% Copyright (C) 2019 Roberto Giacomelli
+% Copyright (C) 2020 Roberto Giacomelli
\documentclass{article}
diff --git a/macros/luatex/generic/barracuda/doc/barracuda-manual-tool.tex b/macros/luatex/generic/barracuda/doc/barracuda-manual-tool.tex
index 9e5f5f8a47..8b00e1c2b5 100644
--- a/macros/luatex/generic/barracuda/doc/barracuda-manual-tool.tex
+++ b/macros/luatex/generic/barracuda/doc/barracuda-manual-tool.tex
@@ -1,7 +1,39 @@
+% an auxiliary package for the manual
+\directlua{
+ barracuda = require "barracuda"
+ local v = barracuda._VERSION
+ local p = v:find(" ")
+ brcd_data = {
+ version = v:sub(p+1),
+ date = barracuda._DATE
+ }
+}
+\newcommand{\code}[1]{\texttt{#1}}
+\newcommand{\brcd}{\code{barracuda}}
+\newbox\barracudabox
+\newcommand\barracuda[3][_brcd_empty_=true]{\directlua{
+ local enc_name = [[#2]]
+ local data = [[#3]]
+ local opt = {#1};
+ if opt._brcd_empty_ == true then
+ barracuda:hbox(enc_name, data, "barracudabox")
+ else
+ barracuda:hbox(enc_name, data, "barracudabox", opt)
+ end
+}%
+\leavevmode\box\barracudabox
+}
-
+\newcommand{\brcdkey}[1]{\directlua{
+ local key = [===[#1]===]
+ if brcd_data[key] then
+ tex.sprint(brcd_data[key])
+ else
+ error("Key '"..key.."' not found")
+ end
+}}
diff --git a/macros/luatex/generic/barracuda/doc/barracuda.pdf b/macros/luatex/generic/barracuda/doc/barracuda.pdf
index 6472da10ee..99d8034ea3 100644
--- a/macros/luatex/generic/barracuda/doc/barracuda.pdf
+++ b/macros/luatex/generic/barracuda/doc/barracuda.pdf
Binary files differ
diff --git a/macros/luatex/generic/barracuda/doc/barracuda.tex b/macros/luatex/generic/barracuda/doc/barracuda.tex
index e5d6b6acdb..0fc6fbac28 100644
--- a/macros/luatex/generic/barracuda/doc/barracuda.tex
+++ b/macros/luatex/generic/barracuda/doc/barracuda.tex
@@ -1,8 +1,8 @@
% !TeX program = LuaLaTeX
-% Copyright (C) 2019 Roberto Giacomelli
-% Barracuda manual main source file
+% Copyright (C) 2020 Roberto Giacomelli
+% Barracuda manual, main TeX source file
-\documentclass[11pt]{article}
+\documentclass[11pt,a4paper]{article}
\usepackage{fontspec}
\usepackage{geometry}
\usepackage{fancyvrb}
@@ -13,40 +13,40 @@
\input{barracuda-manual-tool}
\hypersetup{
+hidelinks,
+linktoc = all,
pdfinfo={
- Title={Barracuda manual},
- Subject={Barcode printing package},
- Author={Roberto Giacomelli},
- Keywords={Barcode EAN Code128 Lua}
+ Title={the Barracuda manual},
+ Subject={Barcode printing package},
+ Author={Roberto Giacomelli},
+ Keywords={Barcode EAN Code128 Lua}
}}
\setmainfont{Libertinus Serif}
-\setmonofont{IBM Plex Sans Condensed}
+\setmonofont[Scale=0.82]{Fira Mono}
\fvset{
fontsize=\small,
frame=single,
labelposition=topline,
- framesep=6pt
+ framesep=5pt
}
\geometry{
left=32mm,
right=40mm,
- top=28mm,
+ top=22mm,
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]
+\title{the \code{barracuda} manual\\[1ex]
\small \url{https://github.com/robitex/barracuda}}
-\date{\small 2019-12-04\\Version v0.0.9.1}
+\date{\small Date \brcdkey{date} --- Version \brcdkey{version} --- Beta stage}
\begin{document}
\maketitle
\abstract{%
-Welcome to the \brcd{} software project devoted to barcodes printing.
+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{}.
@@ -55,8 +55,15 @@ export such graphic content to an external file, using \brcd{}.
under the GPL 2 License.%
}
+\tableofcontents
+\newpage
-\section{Introduction}
+
+\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
@@ -67,80 +74,117 @@ 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 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 drivers for different graphic format, at the moment are:
+The package provides different output graphic format. At the moment they are:
\begin{itemize}
- \item PDF Portable Document Format (require a modern \TeX{} engine),
+ \item PDF Portable Document Format (a modern \TeX{} engine is required),
\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.
+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 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 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:] Get started
+\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 print your first barcode \( \to \) \ref{secEnter}
- \item installing \brcd{} on your system \( \to \) \ref{secInstall}
- \item \brcd{} \LaTeX{} package \( \to \) \ref{secLaTeXPkg}
+ \item encoder identification rule \( \to \) \pageref{secEncName}
+ \item barcode symbologies reference \( \to \) \pageref{secBcRef}
\end{itemize}
-\item[Part 2:] Advanced Work with \brcd{}
+
+\item[Part 4:] Advanced Work with \brcd{}
\begin{itemize}
- \item Lua framework description \( \to \) \ref{secFramework}
- \item working example and use cases \( \to \) \ref{secExample}
+ \item Lua framework description \( \to \) \pageref{secFramework}
+ \item API reference \( \to \) \pageref{secAPI}
+ \item \code{ga} specification \( \to \) \pageref{secGA}
\end{itemize}
-\item[Part 3:] Reference and parameters
+
+\item[Part 5:] Real examples
\begin{itemize}
- \item barcode symbology reference \( \to \) \ref{secBcRef}
- \item \code{ga} specification
- \item API reference \( \to \) \ref{secAPI}
+ \item working example and use cases \( \to \) \pageref{secExample}
\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.
+\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 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.
+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.
-Here is a collection of useful learning resources\dots
+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}
-\section{Get Started with Barracuda}
+\subsection{Running 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.
+code 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:
+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"
@@ -148,97 +192,127 @@ 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:
+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 the new file
+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 \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.
+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.
-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.
+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.
-\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...
+\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
-\nopagenumbers
\newbox\mybox
\directlua{
local require "barracuda"
barracuda:hbox("ean-13", "8006194056290", "mybox")
-}\box\mybox
+}\leavevmode\box\mybox
\bye
\end{Verbatim}
-The method \code{hbox()} works only with Lua\TeX{}.
+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}
-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.
+\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
+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 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 canvas,
-\item get a reference of driver object,
-\item address canvas toward a driver.
+\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}
-Follow that step by step procedure the corresponding code is in the next
-listing:
+Following that step by step procedure the corresponding code is translated in
+the next listing:
\begin{Verbatim}
-local barracuda = require "barracuda"
-local barcode = barracuda:get_barcode_class()
+-- lua script
+local barracuda = require "barracuda" -- step 1
+local barcode = barracuda:barcode() -- step 2
-local ean13, err_enc = barcode:new_encoder("ean-13")
+local ean13, err_enc = barcode:new_encoder("ean-13") -- step 3
assert(ean13, err_enc)
-local symb, err_symb = ean13:from_string("8006194056290")
+local symb, err_symb = ean13:from_string("8006194056290") -- step 4
assert(symb, err_symb)
-local canvas = barracuda:new_canvas()
-symb:append_ga(canvas)
+local canvas = barracuda:new_canvas() -- step 5
+symb:append_ga(canvas) -- step 6
-local driver = barracuda:get_driver()
-local ok, err_out = driver:save("svg", canvas, "my_barcode", "svg")
+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}.
-\section{Installing}
+
+\subsection{Installing}
\label{secInstall}
-\subsection{Installing `barracuda` for TeX Live}
+\subsubsection{Installing for Lua}
-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:
+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}
@@ -249,21 +323,16 @@ $ tlmgr install barracuda
\end{Verbatim}
If you have installed TeX Live via Linux OS repository try your distribution's
-package management system.
+package management system running a software update.
-It's also possible a manual installation:
+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.
+\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}
-\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}
@@ -282,49 +351,62 @@ A simple example is the following source file for Lua\LaTeX{}:
\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.
+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}
-\section{The Barracuda Framework}
+TODO
+
+\subsection{Barcode Reference}
+\label{secBcRef}
+
+TODO
+
+\section{Developer zone}
+
+\subsection{The Barracuda Framework}
\label{secFramework}
-The \brcd{} package framework consists in indipendet modules: a barcode class
+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 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.
+\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 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.
+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 be setting up by the user only through the encoder.
+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.
-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 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.
+The Barcode class is completely indipendent from the ouput driver and viceversa.
-Barcode class is completely indipendent from the ouput driver and viceversa.
-
-
-\section{Example and use cases}
-\label{secExample}
+\subsection{Lua API reference}
+\label{secAPI}
TODO
-\section{Barcode Reference}
-\label{secBcRef}
+\subsection{\code{ga} specification}
+\label{secGA}
TODO
-\section{API reference}
-\label{secAPI}
+\section{Example and use cases}
+\label{secExample}
TODO