summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/barracuda/doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-12-05 03:00:50 +0000
committerNorbert Preining <norbert@preining.info>2019-12-05 03:00:50 +0000
commit2905ee4c8de47cfdeea4787e465eb827f9b99e8b (patch)
tree802c26d7002fd7e2188412b5bd1f86cd9ee2c4d6 /macros/luatex/generic/barracuda/doc
parent05ad7831f64aa0e2fc9eac63816eeafcb0b09708 (diff)
CTAN sync 201912050300
Diffstat (limited to 'macros/luatex/generic/barracuda/doc')
-rw-r--r--macros/luatex/generic/barracuda/doc/barracuda-ga-asm.pdfbin0 -> 38718 bytes
-rw-r--r--macros/luatex/generic/barracuda/doc/barracuda-ga-asm.tex148
-rw-r--r--macros/luatex/generic/barracuda/doc/barracuda-manual-tool.tex7
-rw-r--r--macros/luatex/generic/barracuda/doc/barracuda.pdfbin0 -> 57452 bytes
-rw-r--r--macros/luatex/generic/barracuda/doc/barracuda.tex331
-rw-r--r--macros/luatex/generic/barracuda/doc/image/8006194056290.pdfbin0 -> 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
new file mode 100644
index 0000000000..18ba18b9c2
--- /dev/null
+++ b/macros/luatex/generic/barracuda/doc/barracuda-ga-asm.pdf
Binary files differ
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
new file mode 100644
index 0000000000..6472da10ee
--- /dev/null
+++ 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
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
new file mode 100644
index 0000000000..8effe87846
--- /dev/null
+++ b/macros/luatex/generic/barracuda/doc/image/8006194056290.pdf
Binary files differ