diff options
author | Norbert Preining <norbert@preining.info> | 2019-12-05 03:00:50 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-12-05 03:00:50 +0000 |
commit | 2905ee4c8de47cfdeea4787e465eb827f9b99e8b (patch) | |
tree | 802c26d7002fd7e2188412b5bd1f86cd9ee2c4d6 /macros/luatex/generic/barracuda/doc | |
parent | 05ad7831f64aa0e2fc9eac63816eeafcb0b09708 (diff) |
CTAN sync 201912050300
Diffstat (limited to 'macros/luatex/generic/barracuda/doc')
-rw-r--r-- | macros/luatex/generic/barracuda/doc/barracuda-ga-asm.pdf | bin | 0 -> 38718 bytes | |||
-rw-r--r-- | macros/luatex/generic/barracuda/doc/barracuda-ga-asm.tex | 148 | ||||
-rw-r--r-- | macros/luatex/generic/barracuda/doc/barracuda-manual-tool.tex | 7 | ||||
-rw-r--r-- | macros/luatex/generic/barracuda/doc/barracuda.pdf | bin | 0 -> 57452 bytes | |||
-rw-r--r-- | macros/luatex/generic/barracuda/doc/barracuda.tex | 331 | ||||
-rw-r--r-- | macros/luatex/generic/barracuda/doc/image/8006194056290.pdf | bin | 0 -> 5682 bytes |
6 files changed, 486 insertions, 0 deletions
diff --git a/macros/luatex/generic/barracuda/doc/barracuda-ga-asm.pdf b/macros/luatex/generic/barracuda/doc/barracuda-ga-asm.pdf Binary files differnew file mode 100644 index 0000000000..18ba18b9c2 --- /dev/null +++ b/macros/luatex/generic/barracuda/doc/barracuda-ga-asm.pdf diff --git a/macros/luatex/generic/barracuda/doc/barracuda-ga-asm.tex b/macros/luatex/generic/barracuda/doc/barracuda-ga-asm.tex new file mode 100644 index 0000000000..1c403455f8 --- /dev/null +++ b/macros/luatex/generic/barracuda/doc/barracuda-ga-asm.tex @@ -0,0 +1,148 @@ +% !TeX program = LuaLaTeX +% Copyright (C) 2019 Roberto Giacomelli + +\documentclass{article} + +\usepackage{fontspec} +\setmainfont{Libertinus Serif} + +\usepackage[margin=18mm]{geometry} +\usepackage{array} +\usepackage{booktabs} + +\newcolumntype{C}{>{\ttfamily}c} +\newcolumntype{L}{>{\ttfamily}l} + +\begin{document} +Goal: describe geometrical object like lines and rectangles +mainly for a barcode drawing library. + + + +\section{\texttt{ga} instruction set} + +A graphic data specification format called '\texttt{ga}' \emph{graphic alchemy}, +or if you want \emph{generic graphic assembler}. + +\begin{verbatim} +ga<DIM, UINT> := generic graphic assembler + <DIM> := numeric type parameter for dimension, for example f64 or i32 + <UINT> := numeric type parameter for quantity, an unsigned integer, i.e. u8 + +ga<DIM, UINT> := +Elem<DIM, UINT> + +Elem<DIM, UINT> := Code<u8> + Args<DIM, UINT> + +Code<u8> := State<u8> | Object<u8> | Fn<u8> + State<u8> := 1 -> 31 -- graphic properties + Object<u8> := 32 -> 239 -- graphic objects + Fn<u8> := 240 -> 255 -- functions + +Args<DIM, UINT> : <x: DIM> | <e: u8> | <n: UINT> | <c: CHARS> + <x: DIM> := a dimension value of type DIM + <e: u8> := an enumeration value of type u8 (unsigned byte) + <n: UINT> := an unsigned integer for multiplicity + <c: CHARS> := chars sequence ended with 0 +\end{verbatim} + + + +\section{Properties} + +Colors, linecap style etc\dots + +\noindent\begin{tabular}{CLlL} +\toprule +OpCode & Mnemonic key & Graphic property & Operands\\ +\midrule + 1 & pen\_thick & Line thick & <w: DIM>\\ + 2 & line\_cap\_style & Line cap style & <e: u8>\\ + 3 & line\_join\_style & Line join style & <e: u8>\\ + 8 & color & ... \\ +\midrule +30 & start\_bbox\_group & Stop to check the bounding box & -\\ +31 & end\_bbox\_group & Set a bounding box and restart to check & <x1: DIM> <y1: DIM> <x2: DIM> <y2: DIM>\\ +\bottomrule +\end{tabular} + + + +\section{Objects} + +\subsection{Lines} + +A segment that starts from point P1 (x1, y1) and ends to P2 (x2, y2). + +\noindent\begin{tabular}{CLlL} +\toprule +OpCode & Mnemonic key & Graphic object & Operands\\ +\midrule +32 & line & Line & <x1: DIM> <y1: DIM> <x2: DIM> <y2: DIM>\\ +33 & hline & Horizontal line & <x1: DIM> <x2: DIM> <y: DIM>\\ +34 & vline & Vertical line & <y1: DIM> <y2: DIM> <x: DIM>\\ +\midrule +36 & vbar & Vertical bars & <y1: DIM> <y2: DIM> <b: UINT> <x1: DIM> <t1: DIM> ...\\ +37 & hbar & Horizontal bars & <x1: DIM> <x2: DIM> <b: UINT> <y1: DIM> <t1: DIM> ...\\ +\midrule +38 & polyline & Open polyline & <n: UINT> <x1: DIM> <y1: DIM> <x2: DIM> <y2: DIM> ...\\ +39 & c\_polyline & Closed polyline & <n: UINT> <x1: DIM> <y1: DIM> <x2: DIM> <y2: DIM> ...\\ +\bottomrule +\end{tabular} + + +\subsection{Rectangles} + +\noindent\begin{tabular}{CLlL} +\toprule +OpCode & Mnemonic key & Graphic object & Operands\\ +\midrule + 48 & rect & Rectangle & <x1: DIM> <y1: DIM> <x2: DIM> <y2: DIM>\\ + 49 & f\_rect & Filled rectangle & <x1: DIM> <y1: DIM> <x2: DIM> <y2: DIM>\\ + 50 & rect\_size & Rectangle & <x1: DIM> <y1: DIM> <w: DIM> <h: DIM>\\ + 51 & f\_rect\_size & Filled rectangle & <x1: DIM> <y1: DIM> <w: DIM> <h: DIM>\\ + +\bottomrule +\end{tabular} + + +\subsection{Text} + +\noindent\begin{tabular}{CLl} +\toprule +OpCode & Mnemonic key & Graphic object/Operands\\ +\midrule + 130 & text & A text with several glyphs\\ + & & \ttfamily <ax: FLOAT> <ay: FLOAT> <xpos: DIM> <ypos: DIM> <c: CHARS>\\ +\midrule + 131 & text\_xspaced & A text with glyphs equally spaced on its vertical axis\\ + & & \ttfamily <x1: DIM> <xgap: DIM> <ay: FLOAT> <ypos: DIM> <c: CHARS>\\ +\midrule + 132 & text\_xwidth & Glyphs equally spaced on vertical axis between two x coordinates\\ + & & \ttfamily <ay: FLOAT> <x1: DIM> <x2: DIM> <y: DIM> <c: CHARS>\\ +\midrule + & under design assessment\\ + 140 & \_text\_group & Texts on the same baseline \\ + & & \ttfamily <ay: DIM> <y: DIM> <n: UINT> <<xi: DIM> <ai: FLOAT> <ci: CHARS>> \\ +\bottomrule +\end{tabular} + + +\subsection{Function} + + +\noindent\begin{tabular}{CLlL} +\toprule +OpCode & Mnemonic key & Function & Operands\\ +\midrule + 240 & move & Translate objects & <n: UINT> <dx: DIM> <dy: UINT>\\ + 241 & copy & Copy object & <n: UINT> <c: UINT> <dx1: DIM> <dy1: UINT> ...\\ + 242 & and\_copy & Place and copy objects & <n: UINT> <c: UINT> <dx1: DIM> <dy1: UINT> ...\\ + 243 & grid & Copy next \(n\) objects on a grid & <n: UINT> <col: UINT> <row: UINT> <dx: DIM> <dy: DIM>\\ + 244 & sl\_grid\\ + 250 & mirror\\ + 255 & comment & A string comment & <s: STRING>\\ +\bottomrule +\end{tabular} + + +\end{document} diff --git a/macros/luatex/generic/barracuda/doc/barracuda-manual-tool.tex b/macros/luatex/generic/barracuda/doc/barracuda-manual-tool.tex new file mode 100644 index 0000000000..9e5f5f8a47 --- /dev/null +++ b/macros/luatex/generic/barracuda/doc/barracuda-manual-tool.tex @@ -0,0 +1,7 @@ + + + + + + + diff --git a/macros/luatex/generic/barracuda/doc/barracuda.pdf b/macros/luatex/generic/barracuda/doc/barracuda.pdf Binary files differnew file mode 100644 index 0000000000..6472da10ee --- /dev/null +++ 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 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} diff --git a/macros/luatex/generic/barracuda/doc/image/8006194056290.pdf b/macros/luatex/generic/barracuda/doc/image/8006194056290.pdf Binary files differnew file mode 100644 index 0000000000..8effe87846 --- /dev/null +++ b/macros/luatex/generic/barracuda/doc/image/8006194056290.pdf |