summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/lua2dox/lua2dox-refm.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/lua2dox/lua2dox-refm.tex')
-rw-r--r--Master/texmf-dist/doc/support/lua2dox/lua2dox-refm.tex465
1 files changed, 0 insertions, 465 deletions
diff --git a/Master/texmf-dist/doc/support/lua2dox/lua2dox-refm.tex b/Master/texmf-dist/doc/support/lua2dox/lua2dox-refm.tex
deleted file mode 100644
index 199d5449cdd..00000000000
--- a/Master/texmf-dist/doc/support/lua2dox/lua2dox-refm.tex
+++ /dev/null
@@ -1,465 +0,0 @@
-\documentclass[a4paper]{article}
-%\nofiles
-
-\usepackage[T1]{fontenc}
-\usepackage{hyperref}
-\usepackage{listings}
-\input{lua.def} % not installed properly so just include here
-
-%%
-% h
-\parindent=0bp
-\textwidth=450bp
-\oddsidemargin=0bp
-
-% v
-\parskip=.5em
-\voffset=-70bp
-\textheight=750bp
-
-
-%%%%%%%%%%%%%%%%%
-\def\sectionSprout(#1,#2){\vspace{#1}\penalty#2\vspace{-#1}}
-\def\Sect{\sectionSprout(125bp,-150)\section}
-\def\SSect{\sectionSprout(100bp,-100)\subsection}
-\def\SSSect{\sectionSprout(80bp,-50)\subsubsection}
-
-\def\BT{\begin{tabular}}
-\def\ET{\end{tabular}}
-
-\def\BE{\begin{enumerate}}
-\def\EE{\end{enumerate}}
-\def\IE{\item }
-
-\def\BI{\begin{itemize}}
-\def\EI{\end{itemize}}
-\def\II{\item }
-
-\long\def\Nerd#1{{\tt #1}}
-\def\URL#1{{\tt #1}}
-
-\def\LuaToDoX{Lua2D\raise-.3em\hbox{O}X$_{lua}$}
-\def\luatodox{\Nerd{lua2dox\_lua}}
-\def\Doxygen{\Nerd{Doxygen}}
-\def\doxygen{\Nerd{doxygen}}
-\def\To{$\rightarrow$}
-\def\BS{$\backslash$}
-
-\def\Foot#1{\footnote{#1}}
-
-\lstset{language=C++
- ,frame=single
- ,numbers=left
- ,numberstyle=\tiny
- ,tabsize=2
- }
-
-\hypersetup{
- pdfinfo={
- Title={Lua2DoX lua ref manual}
- ,Subject={Autodoc tool for Lua}
- }
- ,colorlinks=true
- ,linkcolor=blue
- }
-
-\def\SetRefmanVerDate#1#2{%
- \def\RefmanVersion{#1}%
- \def\RefmanDate{#2}%
- }
-\def\SetRefmanCopyright#1{%
- \def\RefmanCopyright{#1}%
- }
-
-\SetRefmanCopyright{Copyright (c) 2012-13 Simon Dales}
-\SetRefmanVerDate{0.2}{7th February 2013}
-
-
-\begin{document}
-\pagestyle{empty}
-\begin{center}
- \huge \LuaToDoX
-
- \large
- \RefmanVersion
-
- \RefmanCopyright
-
- \RefmanDate
-
-{\fboxsep=.5em\fboxrule=.1bp\fbox{%
-\begin{minipage}{300bp}
-\hyphenpenalty=10000%
-\small
-%\begin{abstract}
-This is a hack to enable \doxygen{} to document lua.
-
-It uses the well-known \doxygen{} filter mechanism to allow \doxygen{} to read extra computer languages.
-
-If this works for you then enjoy.
-
-%\end{abstract}
-\end{minipage}
-}}
-\end{center}
-
-\tableofcontents
-
-\newpage
-\pagestyle{headings}
-
-\Sect{Introduction}
-
-Documenting sourcecode is a hassle.
-There are two basic methods of providing documented sourcecode: ``literate programming'' and ``autodoc''.
-Without these tools a human has to keep the documentation and code aligned, which rarely happens.
-
-\SSect{Literate Programming}
-
-If one is sufficiently organised, and it fits in with your existing work practices, then there is
-a lot going for literate programming.
-Here you write a combined document that contains both code and documentation fragments.
-When you want code or documentation you run it through a program which makes the appropriate files.
-
-This is theoretically the neatest way of making code because no code is generated without documentation.
-The best known example of literate programming is the source of \TeX.
-
-\SSect{Autodoc}
-
-In the real world we get source from many sources, usually where literate programming wasn't used or isn't available.
-
-One solution is to use an automatic documentation tool:
-feed it sourcecode and it will extract what documentation it can.
-
-If you feed it raw source then all it can do is tell you where it found features such as function and class declarations.
-
-If your source has been suitably prepared, then more detailed documentation can be produced.
-This preparation takes the form of ``magic comments''.
-These are source comments that contain ``magic'' features that let the autodoc tool know to make use of them.
-
-\SSSect{Doxygen}
-
-\Doxygen{} is one of the many autodoc tools use to document C-like languages.
-It is widely used and supported in the linux world and has Mac OS X and Windows ports.
-
-\begin{lstlisting}[firstnumber=83]
-void helloWorldOnce(){
- printf("hello world\n");
- }
-/*!
- \brief writes hello world *n
-
- This is a demo of how to loop round
- and print something
-
- \param N number of times round
-*/
-void helloWorldN(int N){
- for (int i=0;i<N;i++)
- printf("hello world %d\n",i);
- }
-\end{lstlisting}
-
-\hspace{-.35em}{\fboxsep=.5em\fboxrule=.1bp\fbox{%
-\begin{minipage}{\textwidth}
-{\sf void {\bfseries helloWorldN}(int N)}
-
-{\itshape writes hello world *n}
-
-This is a demo of how to loop round
-and print something
-
-{\bfseries Parameters:}
-
-\hspace*{1em}{\itshape N} number of times round
-
-Definition at line {\bfseries 94} of file {\bfseries hello.cpp}.
-
-\vskip1em
-{\sf void {\bfseries helloWorldOnce}()}
-
-Definition at line {\bfseries 83} of file {\bfseries hello.cpp}.
-
-\end{minipage}\hspace{-.35em}%
-}%
-}\hspace*{-10em}\rule{0bp}{0bp}%
-
-\SSSect{\LuaToDoX}
-
-In the case of \doxygen{}, which is intended for C-like languages, it expects `\Nerd{///}' or `\Nerd{//!}' for C++ comments and `\Nerd{/**}\ldots\Nerd{*/}'/`\Nerd{/*!}\ldots\Nerd{*/}' for C-style comments.
-For \LuaToDoX{} we recycle this convention and use `\Nerd{-{}-!}' and `\Nerd{-{}-[[!}\ldots\Nerd{]]}'.
-
-The internal format of the magic comments is identical to \doxygen.
-This is not suprising in that \Nerd{lua2dox\_filter} is a \doxygen{} filter.
-What it does is to read lua code and output something not entirely unlike C++.
-
-This lets us make Doxygen output some documentation to let
-us develop this code.
-
-\begin{lstlisting}[firstnumber=83,language=lua]
-function helloWorldOnce()
- io.write("hello world\n")
-end
---[[!
- \brief writes hello world *n
-
- This is a demo of how to loop round
- and print something
-
- \param N number of times round
- ]]
-function helloWorldN(N)
- for i=0,N do
- io.write("hello world" .. i .. "\n")
- end
-end
-\end{lstlisting}
-
-\hspace{-.35em}{\fboxsep=.5em\fboxrule=.1bp\fbox{%
-\begin{minipage}{\textwidth}
-{\sf function {\bfseries helloWorldN}(N)}
-
-{\itshape writes hello world *n}
-
-This is a demo of how to loop round
-and print something
-
-{\bfseries Parameters:}
-
-\hspace*{1em}{\itshape N} number of times round
-
-Definition at line {\bfseries 94} of file {\bfseries hello.lua}.
-
-\vskip1em
-{\sf function {\bfseries helloWorldOnce}()}
-
-Definition at line {\bfseries 83} of file {\bfseries hello.lua}.
-
-\end{minipage}\hspace{-.35em}%
-}%
-}\hspace*{-10em}\rule{0bp}{0bp}%
-
-\SSect{Origins}
-
-\LuaToDoX{} inspired by the functionality of a Perl module called ``\Nerd{lua2dox}''%
-\Foot{\URL{http://search.cpan.org/\~{}alec/Doxygen-Lua-0.02/lib/Doxygen/Lua.pm}}.
-Found on CPAN when looking for something else; kinda handy.
-
-Improved from \Nerd{lua2dox} to make the \doxygen{} output more friendly.
-Runs faster in lua than in Perl.
-
-Because this Perl based system is called ``\Nerd{lua2dox}'', I have decided to add ``\Nerd{\_lua}'' to the name to keep the two separate, so it is called ``\luatodox''.
-
-\newpage
-\Sect{Installation}
-\SSect{System requirements}
-
-Should run on any reasonably modern computer (PC or Mac OS X).
-
-Requires a reasonably recent: \doxygen{} and \Nerd{luatex} or \Nerd{lua}.
-\BI
-\II \doxygen{} $\ge$ 1.8.1
-\II \Nerd{luatex} $\ge$ 0.6 / \Nerd{lua} 5.1
-\EI
-
-\SSSect{Luatex/lua}
-
-
-Whilst \Nerd{luatex} isn't strictly required to make it run; \TeX{} users
-are more likely to have a recent version (via \Nerd{texlive}) of \Nerd{texlua}
-rather than relying on your, possibly aging, distro's lua.
-
-It should work with either \Nerd{texlua} or \Nerd{lua}.
-The calling bash script determines which one is available (\Nerd{texlua} then \Nerd{lua}) and selects that one.
-
-\SSSect{\doxygen}
-
-Install this using whatever mechanism you usually use.
-
-It is also helpful if you know how to use \doxygen.
-
-\SSect{Linux/other Unices}
-
-Only tested for linux, but should work for any Unix-like OS.
-
-For other OS you need to figure it out yourself.
-If you do, then please email me with the code/suggestions.
-
-\BE
-\IE make an appropriatly named temporary directory (``\Nerd{tmp}'').
-\IE \Nerd{cd tmp}
-\IE untar into this directory.
-
-\IE manually check if lua2dox.lua runs on your system.
-
-From the commandline run ``\Nerd{./lua2dox\_filter -{}-help}''.
-If it runs and produces a sensible result then it probably works.
-
-\IE Manually pick an appropriate directory for this system.
-
-Make this new directory and copy/mv all these files into there.
-
-If you are installing it as a personal app then put it somewhere in your
-userspace. For system-wide: ask your sysadmin.
-
-In this example called ``\Nerd{$\sim$/programs/lua2dox}''.
-\IE ``\Nerd{cd $\sim$/programs/lua2dox}''.
-
-\IE Run ``\Nerd{./install.sh}''.
-This makes the links to the active code.
-
-Default is to put in `\Nerd{$\sim$/bin}''. For system-wide: ask your sysadmin.
-\EE
-
-\SSect{Mac OS X}
-
-Being a unix-like OS then install as for Linux.
-
-\SSect{Windows}
-
-As for unix but use the .BAT files.
-
-\newpage
-\Sect{Useage}
-
-Because this is a \doxygen{} filter then it is assumed that the endusers are familiar with
-the use of this app.
-When familiar then one can move on to documenting lua code.
-
-\SSect{Learn to use \Doxygen}
-
-Ensure \doxygen{} is installed on your system and that you are familiar with its use.
-Best is to try to make and document some simple C/C++/PHP to see what it produces.
-
-Included with this distribution are some examples of php and lua code.
-They are two simple programs that create some classes and then show their use.
-The documentation should be nearly the same as each other.
-
-\SSect{running \LuaToDoX}
-\SSSect{make Doxyfile}
-Run ``\Nerd{doxygen -g}'' to create a default \Nerd{Doxyfile}.
-This is the configuration file that \doxygen{} needs for making the documentation.
-
- Then alter it to let it recognise lua. Add the following lines:
-
-\begin{lstlisting}[language=bash,numbers=none]
-FILE_PATTERNS = *.lua
-FILTER_PATTERNS = *.lua=lua2dox_filter
-\end{lstlisting}
-
-
-You might also like to edit some other entries:
-
-\begin{lstlisting}[language=bash,numbers=none]
-PROJECT_NAME = <name of project>
-PROJECT_NUMBER = <version number>
-OUTPUT_DIRECTORY = docs
-SOURCE_BROWSER = yes
-GENERATE_LATEX = no
-\end{lstlisting}
-
-For example:
-
-\begin{lstlisting}[language=bash, numbers=none]
-PROJECT_NAME = "A Test Project"
-PROJECT_NUMBER = "0.1 20120926a"
-\end{lstlisting}
-
-Either add them to the end or find/edit the appropriate entry in \Nerd{Doxyfile}.
-
-\SSSect{run \doxygen}
-
-Once \Nerd{Doxyfile} has been edited run \doxygen{} and \LuaToDoX{} will be called as a filter.
-
-% When reading source with classes multiple passes are needed.
-% Each pass generates a list of member functions (as a file) that were found on this pass.
-% This list is read in on the next pass.
-% If the class+methods haven't changed this time then you only need to run it once, else run twice,
-% much like running \LaTeX{} \Nerd{$\backslash$tableofcontents}.
-
-\SSect{In use}
-
-As with \doxygen{} the HTML output is the most useful for development.
-When the project is finished then PDF output (via \LaTeX) may be useful.
-
-Typically you will have some source files open in your editor/IDE.
-Also keep a web-browser window open pointing at the documentation.
-
-After a bit of editing the documentation will become stale.
-At this point run \doxygen{} and refresh the HTML pages.
-
-\newpage
-\Sect{Design}
-
-\LuaToDoX{} is a \doxygen{} filter.
-It has a basic parser that will read each line of lua and output an equivalent in pseudo-C++.
-It loops round until it has found the end of the file.
-It only has to be good enough for \doxygen{} to see it as legal.
-Therefore our lua interpreter is fairly limited, but ``good enough''.
-
-The parser is relatively crude and assumes that the programmer writes lua in a fairly
-clean way.
-Some bits of lua will confuse it.
-
-In order for the source browser to work in the \doxygen{} output it must preserve the number of lines.
-The output of each line is either written as-is or a converted line.
-When \doxygen{} re-reads the source to make the source-HTML/\LaTeX{}/\ldots it uses the line number
-to set the position.
-
-
-It only supports comments that preceded the function/class declaration.
-Any in the middle will act as cruft in the resulting documentation.
-This will be slightly out of place but at least should refer to somewhere near to
-where it was intended.
-In particular ``\Nerd{\BS todo}''. This will appear in the ToDo list, but not associated with the right function.
-
-\SSect{Classes}
-Class declarations are assumed to be using a ``well-known'' userdefined function ``\Nerd{class()}''.
-It processes\goodbreak``\Nerd{TAA = class(TA)}''$_{lua}$ \To{} ``\Nerd{class TAA: public TA\{\}};''$_{C++}$.
-
-% However it will probably have some member functions.
-% These get converted from \goodbreak''\Nerd{A.foo(a,b)}''$_{lua}$ \To{} ``\Nerd{A::foo(a,b)}''$_{C++}$.
-% This is stored in a temporary file.
-% When \LuaToDoX{} is run a subsequent time this is used to generate a list of methods.
-% So \goodbreak``\Nerd{AA = class(A)}''$_{lua}$ \To{} ``\Nerd{class AA: public A\{foo(a,b);bar(x);\}};''$_{C++}$
-
-\SSSect{Methods}
-
-Methods are mangled as: ``\Nerd{TA.fred(this,A)}''$_{lua}$ to ``\Nerd{/*! \BS memberof TA */ fred(this,A)}''$_{C++}$.
-This is a \doxygen{} feature introduced in 1.8.1.
-It allows the filter to work in a single pass.
-
-\SSect{Multiline function declarations}
-
-Because \LuaToDoX{} can only process one line at a time it cannot be guaranteed to correctly process function declarations
-with multiline parameter list.
-This is because the parser isn't sophisticated enough to guarantee finding the close paren on some random later line.
-
-So I have put in a hack that will insert the ``missing'' close paren.
-It looks at the function declaration that you have got and checks for a close paren.
-It if is not there then it will add a spoof parameter and the close.
-
-The effect is that you will get the function documented, but not with the parameter list you might expect.
-
-\begin{lstlisting}[firstnumber=94]
-function foo(A
- ,B
- ,C)
-\end{lstlisting}
-
-Becomes
-\begin{lstlisting}[firstnumber=94]
-function foo(A,___MissingCloseParenHere___)
-\end{lstlisting}
-
-\SSect{Multiple magic comments}
-
-The hacking of lua to C++ by \LuaToDoX{} has the limitation that some magic comments will not get associated with the correct function/class. This is a ``feature'' that might get correct in a later version.
-
-\newpage
-\Sect{ChangeLog}
-\input{ChangeLog}
-
-\end{document}
-
-%%eof \ No newline at end of file