summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/luatex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-08-13 22:41:51 +0000
committerKarl Berry <karl@freefriends.org>2012-08-13 22:41:51 +0000
commit891d790aa1dafff5340c181e3dce3332526e4834 (patch)
tree049abb04059bc666a0ffa9c585547f5fee297a4c /Master/texmf-dist/doc/luatex
parent99f6ebc940e504927ea38d6600f8ca9f893667bb (diff)
new luatex package luaxml (13aug12)
git-svn-id: svn://tug.org/texlive/trunk@27394 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/luatex')
-rw-r--r--Master/texmf-dist/doc/luatex/luaxml/README27
-rw-r--r--Master/texmf-dist/doc/luatex/luaxml/luaxml.pdfbin0 -> 111453 bytes
-rw-r--r--Master/texmf-dist/doc/luatex/luaxml/luaxml.tex355
3 files changed, 382 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/luatex/luaxml/README b/Master/texmf-dist/doc/luatex/luaxml/README
new file mode 100644
index 00000000000..cb48cbab9bd
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luaxml/README
@@ -0,0 +1,27 @@
+Introduction
+============
+
+LuaXML is pure lua library for reading and serializing of the XML files. Current release is aimed mainly as support
+for the odsfile package. The documentation was created by automatic conversion of original documentation in the source code.
+In this version, some files not useful for luaTeX were droped. Original files can be found at
+
+ http://manoelcampos.com/files/LuaXML--0.0.0-lua5.1.tgz
+
+
+License:
+========
+
+This code is freely distributable under the terms of the Lua license
+ (http://www.lua.org/copyright.html)
+
+
+Author
+------
+Michal Hoftich
+Email: michal.h21@gmail.com
+
+Original authors: Paul Chakravarti and Manoel Campos (http://manoelcampos.com)
+
+If you are interested in the process of development you may observe
+
+ https://github.com/michal-h21/LuaXML \ No newline at end of file
diff --git a/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf b/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf
new file mode 100644
index 00000000000..cddfdcdf5d9
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luaxml/luaxml.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/luatex/luaxml/luaxml.tex b/Master/texmf-dist/doc/luatex/luaxml/luaxml.tex
new file mode 100644
index 00000000000..34363fbcf04
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/luaxml/luaxml.tex
@@ -0,0 +1,355 @@
+\documentclass{ltxdoc}
+\usepackage{tgschola,url}
+\usepackage[english]{babel}
+\begin{document}
+ \title{The \textsc{LuaXML} library}
+ \author{Paul Chakravarti \and Michal Hoftich}
+ \maketitle
+\tableofcontents
+\section*{Introduction}
+
+|LuaXML| is pure lua library for reading and serializing of the |xml| files.
+Current release is aimed mainly as support for the odsfile package.
+In first release it was included with the odsfile package,
+but as it is general library which can be used also with other packages,
+I decided to distribute it as separate library.
+
+\noindent Example of usage:
+
+\begin{verbatim}
+xml = require('luaxml-mod-xml')
+handler = require('luaxml-mod-handler')
+\end{verbatim}
+
+First load the libraries. In |luaxml-mod-xml|, there is xml parser and also serializer. In |luaxml-mod-handler|, there are various handlers for dealing with xml data. Handlers are objects with callback functions which are invoked for every type of content in the |xml| file. More information about handlers can be found in the original documentation, section \ref{sec:handlers}.
+\begin{verbatim}
+sample = [[
+<a>
+ <d>hello</d>
+ <b>world.</b>
+ <b at="Hi">another</b>
+</a>]]
+treehandler = handler.simpleTreeHandler()
+x = xml.xmlParser(treehandler)
+x:parse(sample)
+\end{verbatim}
+
+You have to create handler object, using |handler.simpleTreeHandler()| and xml parser object using |xml.xmlParser(handler object)|. |simpleTreehandler| creates simple table hierarchy, with top root node in |treehandler.root|
+\begin{verbatim}
+-- pretty printing function
+function printable(tb, level)
+ level = level or 1
+ local spaces = string.rep(' ', level*2)
+ for k,v in pairs(tb) do
+ if type(v) ~= "table" then
+ print(spaces .. k..'='..v)
+ else
+ print(spaces .. k)
+ level = level + 1
+ printable(v, level)
+ end
+ end
+end
+
+-- print table
+printable(treehandler.root)
+-- print xml serialization of table
+print(xml.serialize(treehandler.root))
+-- direct access to the element
+print(treehandler.root["a"]["b"][1])
+
+-- output:
+-- a
+-- d=hello
+-- b
+-- 1=world.
+-- 2
+-- 1=another
+-- _attr
+-- at=Hi
+-- <?xml version="1.0" encoding="UTF-8"?>
+-- <a>
+-- <d>hello</d>
+-- <b>world.</b>
+-- <b at="Hi">
+-- another
+-- </b>
+-- </a>
+--
+-- world.
+\end{verbatim}
+
+Note that |simpleTreeHandler| creates tables that can be easily accessed using standard lua functions, but in case of mixed content, like
+\begin{verbatim}
+<a>hello
+ <b>world</b>
+</a>
+\end{verbatim}
+it produces wrong results. It is useful mostly for data |xml| files, not for text formats like |xhtml|.
+
+Because at the moment it is intended mainly as support for the odsfile package, there is little documentation,
+what follows is the original documentation of |LuaXML|, which may be little bit obsolete now.
+
+\clearpage
+\noindent{\Huge Original documentation}
+\medskip
+
+\noindent This document was created automatically from original source code comments using Pandoc\footnote{\url{http://johnmacfarlane.net/pandoc/}}
+
+\section{Overview}
+
+
+This module provides a non-validating XML stream parser in Lua.
+\section{Features}
+
+\begin{itemize}
+\item
+ Tokenises well-formed XML (relatively robustly)
+\item
+ Flexible handler based event api (see below)
+\item
+ Parses all XML Infoset elements - ie.
+ \begin{itemize}
+ \item
+ Tags
+ \item
+ Text
+ \item
+ Comments
+ \item
+ CDATA
+ \item
+ XML Decl
+ \item
+ Processing Instructions
+ \item
+ DOCTYPE declarations
+ \end{itemize}
+\item
+ Provides limited well-formedness checking (checks for basic syntax \&
+ balanced tags only)
+\item
+ Flexible whitespace handling (selectable)
+\item
+ Entity Handling (selectable)
+\end{itemize}
+\section{Limitations}
+
+\begin{itemize}
+\item
+ Non-validating
+\item
+ No charset handling
+\item
+ No namespace support
+\item
+ Shallow well-formedness checking only (fails to detect most semantic
+ errors)
+\end{itemize}
+\section{API}
+
+The parser provides a partially object-oriented API with functionality
+split into tokeniser and hanlder components.
+
+The handler instance is passed to the tokeniser and receives callbacks
+for each XML element processed (if a suitable handler function is
+defined). The API is conceptually similar to the SAX API but implemented
+differently.
+
+The following events are generated by the tokeniser
+
+\begin{verbatim}
+handler:start - Start Tag
+handler:end - End Tag
+handler:text - Text
+handler:decl - XML Declaration
+handler:pi - Processing Instruction
+handler:comment - Comment
+handler:dtd - DOCTYPE definition
+handler:cdata - CDATA
+\end{verbatim}
+The function prototype for all the callback functions is
+
+\begin{verbatim}
+callback(val,attrs,start,end)
+\end{verbatim}
+where attrs is a table and val/attrs are overloaded for specific
+callbacks - ie.
+
+\begin{tabular}{llp{5cm}}
+Callback & val & attrs (table)\\
+\hline
+start & name & |{ attributes (name=val).. }|\\
+end & name & nil\\
+text & |<text>| & nil\\
+cdata & |<text> | & nil\\
+decl & "xml" & |{ attributes (name=val).. }|\\
+pi & pi name & \begin{verbatim}{ attributes (if present)..
+ _text = <PI Text>
+}\end{verbatim}\\
+comment & |<text>| & nil\\
+dtd & root element & \begin{verbatim}{ _root = <Root Element>,
+ _type = SYSTEM|PUBLIC,
+ _name = <name>,
+ _uri = <uri>,
+ _internal = <internal dtd>
+}\end{verbatim}\\
+\end{tabular}
+
+(start \& end provide the character positions of the start/end of the
+element)
+
+XML data is passed to the parser instance through the `parse' method
+(Nore: must be passed a single string currently)
+
+\section{Options}
+
+Parser options are controlled through the `self.options' table.
+Available options are -
+
+\begin{itemize}
+\item
+ stripWS
+
+ Strip non-significant whitespace (leading/trailing) and do not
+ generate events for empty text elements
+\item
+ expandEntities
+
+ Expand entities (standard entities + single char numeric entities only
+ currently - could be extended at runtime if suitable DTD parser added
+ elements to table (see obj.\_ENTITIES). May also be possible to expand
+ multibyre entities for UTF--8 only
+\item
+ errorHandler
+
+ Custom error handler function
+\end{itemize}
+NOTE: Boolean options must be set to `nil' not `0'
+
+\section{Usage}
+
+Create a handler instance -
+
+\begin{verbatim}
+h = { start = function(t,a,s,e) .... end,
+ end = function(t,a,s,e) .... end,
+ text = function(t,a,s,e) .... end,
+ cdata = text }
+\end{verbatim}
+(or use predefined handler - see luaxml-mod-handler.lua)
+
+Create parser instance -
+
+\begin{verbatim}
+p = xmlParser(h)
+\end{verbatim}
+Set options -
+
+\begin{verbatim}
+p.options.xxxx = nil
+\end{verbatim}
+Parse XML data -
+
+\begin{verbatim}
+xmlParser:parse("<?xml... ")
+\end{verbatim}
+\section{Handlers}\label{sec:handlers}
+
+\subsection{Overview}
+
+Standard XML event handler(s) for XML parser module (luaxml-mod-xml.lua)
+
+\subsection{Features}
+
+\begin{verbatim}
+printHandler - Generate XML event trace
+domHandler - Generate DOM-like node tree
+simpleTreeHandler - Generate 'simple' node tree
+simpleTeXhandler - SAX like handler with support for CSS selectros
+\end{verbatim}
+\subsection{API}
+
+Must be called as handler function from xmlParser and implement XML
+event callbacks (see xmlParser.lua for callback API definition)
+
+\subsubsection{printHandler}
+
+printHandler prints event trace for debugging
+
+\subsubsection{domHandler}
+
+domHandler generates a DOM-like node tree structure with
+a single ROOT node parent - each node is a table comprising
+fields below.
+
+\begin{verbatim}
+node = { _name = <Element Name>,
+ _type = ROOT|ELEMENT|TEXT|COMMENT|PI|DECL|DTD,
+ _attr = { Node attributes - see callback API },
+ _parent = <Parent Node>
+ _children = { List of child nodes - ROOT/NODE only }
+ }
+
+\end{verbatim}
+The dom structure is capable of representing any valid XML document
+\subsubsection{simpleTreeHandler}
+
+simpleTreeHandler is a simplified handler which attempts to generate a
+more `natural' table based structure which supports many common XML
+formats.
+
+The XML tree structure is mapped directly into a recursive table
+structure with node names as keys and child elements as either a table
+of values or directly as a string value for text. Where there is only a
+single child element this is inserted as a named key - if there are
+multiple elements these are inserted as a vector (in some cases it may
+be preferable to always insert elements as a vector which can be
+specified on a per element basis in the options). Attributes are
+inserted as a child element with a key of `\_attr'.
+
+Only Tag/Text \& CDATA elements are processed - all others are ignored.
+
+This format has some limitations - primarily
+
+\begin{itemize}
+\item Mixed-Content behaves unpredictably - the relationship between text
+ elements and embedded tags is lost and multiple levels of mixed
+ content does not work
+\item If a leaf element has both a text element and attributes then the text
+ must be accessed through a vector (to provide a container for the
+ attribute)
+\end{itemize}
+In general however this format is relatively useful.
+
+
+\subsection{Options}
+
+\begin{verbatim}
+simpleTreeHandler.options.noReduce = { <tag> = bool,.. }
+
+ - Nodes not to reduce children vector even if only
+ one child
+
+domHandler.options.(comment|pi|dtd|decl)Node = bool
+
+ - Include/exclude given node types
+\end{verbatim}
+\subsection{Usage}
+
+Pased as delegate in xmlParser constructor and called as callback by
+xmlParser:parse(xml) method.
+
+\section{History}
+
+This library is fork of LuaXML library originaly created by Paul
+Chakravarti. Its original version can be found at
+\url{http://manoelcampos.com/files/LuaXML--0.0.0-lua5.1.tgz}. Some files not
+needed for use with luatex were droped from the distribution.
+Documentation was converted from original comments in the source code.
+
+\section{License}
+
+This code is freely distributable under the terms of the Lua license
+(\url{http://www.lua.org/copyright.html})
+\end{document}