diff options
author | Norbert Preining <norbert@preining.info> | 2020-02-05 03:03:08 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2020-02-05 03:03:08 +0000 |
commit | 4b795f65d52cde0d136c0175ce20101946378b54 (patch) | |
tree | 07b9b0c89193d379ff6971be01a8ca1e3e6931ca /macros/luatex/generic/barracuda/doc | |
parent | fc358ce7332053945afe16ced2a271556cdccfb7 (diff) |
CTAN sync 202002050303
Diffstat (limited to 'macros/luatex/generic/barracuda/doc')
-rw-r--r-- | macros/luatex/generic/barracuda/doc/barracuda-ga-asm.tex | 2 | ||||
-rw-r--r-- | macros/luatex/generic/barracuda/doc/barracuda-manual-tool.tex | 34 | ||||
-rw-r--r-- | macros/luatex/generic/barracuda/doc/barracuda.pdf | bin | 57452 -> 67784 bytes | |||
-rw-r--r-- | macros/luatex/generic/barracuda/doc/barracuda.tex | 348 |
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 Binary files differindex 6472da10ee..99d8034ea3 100644 --- a/macros/luatex/generic/barracuda/doc/barracuda.pdf +++ b/macros/luatex/generic/barracuda/doc/barracuda.pdf 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 |