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.tex413
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}