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.tex131
1 files changed, 90 insertions, 41 deletions
diff --git a/Master/texmf-dist/doc/support/lua2dox/lua2dox-refm.tex b/Master/texmf-dist/doc/support/lua2dox/lua2dox-refm.tex
index dfa42dc5bac..199d5449cdd 100644
--- a/Master/texmf-dist/doc/support/lua2dox/lua2dox-refm.tex
+++ b/Master/texmf-dist/doc/support/lua2dox/lua2dox-refm.tex
@@ -37,11 +37,13 @@
\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}}
@@ -61,17 +63,29 @@
,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
- v0.1
+ \RefmanVersion
- Copyright (c) 2012 Simon Dales
+ \RefmanCopyright
- 4th July 2012
+ \RefmanDate
{\fboxsep=.5em\fboxrule=.1bp\fbox{%
\begin{minipage}{300bp}
@@ -80,7 +94,7 @@
%\begin{abstract}
This is a hack to enable \doxygen{} to document lua.
-It uses the well-known \doxygen{} filter mechanism to fool \doxygen{} into reading foreign languages.
+It uses the well-known \doxygen{} filter mechanism to allow \doxygen{} to read extra computer languages.
If this works for you then enjoy.
@@ -105,9 +119,9 @@ Without these tools a human has to keep the documentation and code aligned, whic
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 assembles the appropriate files.
+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.
+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}
@@ -126,7 +140,7 @@ These are source comments that contain ``magic'' features that let the autodoc t
\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 MacOS and Windows ports.
+It is widely used and supported in the linux world and has Mac OS X and Windows ports.
\begin{lstlisting}[firstnumber=83]
void helloWorldOnce(){
@@ -214,12 +228,12 @@ and print something
\hspace*{1em}{\itshape N} number of times round
-Definition at line {\bfseries 94} of file {\bfseries hello.cpp}.
+Definition at line {\bfseries 94} of file {\bfseries hello.lua}.
\vskip1em
{\sf function {\bfseries helloWorldOnce}()}
-Definition at line {\bfseries 83} of file {\bfseries hello.cpp}.
+Definition at line {\bfseries 83} of file {\bfseries hello.lua}.
\end{minipage}\hspace{-.35em}%
}%
@@ -227,7 +241,7 @@ Definition at line {\bfseries 83} of file {\bfseries hello.cpp}.
\SSect{Origins}
-\LuaToDoX{} inspired by the functionality of \Nerd{lua2dox}%
+\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.
@@ -240,9 +254,13 @@ Because this Perl based system is called ``\Nerd{lua2dox}'', I have decided to a
\Sect{Installation}
\SSect{System requirements}
-Should run on any reasonably modern computer (PC or MacOS X).
+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}
@@ -268,27 +286,38 @@ 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\_lua -{}-help}''.
+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 sysadmin.
+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}''.
+\IE Run ``\Nerd{./install.sh}''.
This makes the links to the active code.
-Default is to put in `\Nerd{\~{}/bin}''. For system-wide: ask sysadmin.
+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}
-Not yet
-\SSect{Mac OSX}
-Not yet
+
+As for unix but use the .BAT files.
\newpage
\Sect{Useage}
@@ -308,32 +337,45 @@ The documentation should be nearly the same as each other.
\SSect{running \LuaToDoX}
\SSSect{make Doxyfile}
-Run ``\Nerd{lua2dox\_lua -g}'' to create a default \Nerd{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 two following lines:
+ Then alter it to let it recognise lua. Add the following lines:
-\begin{lstlisting}{language=bash}
+\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
-FILE_PATTERNS = *.lua
-FILTER_PATTERNS = *.lua=lua2dox_filter
SOURCE_BROWSER = yes
GENERATE_LATEX = no
\end{lstlisting}
-Either add them to the end or find the appropriate entry in \Nerd{Doxyfile}.
+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 \LuaToDoX}
+\SSSect{run \doxygen}
-Once \Nerd{Doxyfile} has been edited run as ``\Nerd{lua2dox\_lua}''.
+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}.
+% 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}
@@ -344,8 +386,7 @@ 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 \LuaToDoX{} once/twice and refresh the HTML pages.
-Then your documentation will be updated.
+At this point run \doxygen{} and refresh the HTML pages.
\newpage
\Sect{Design}
@@ -370,22 +411,27 @@ 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{@todo}''. This will appear in the ToDo list, but not associated with the right function.
+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{AA = class(A)}'' \To{} ``\Nerd{class AA: public A\{\}};''.
+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++}$
-However it will probably have some member functions.
-These get converted from \goodbreak''\Nerd{A.foo(a,b)}'' \To{} ``\Nerd{A::foo(a,b)}''.
-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)}'' \To{} ``\Nerd{class AA: public A\{foo(a,b);bar(x);\}};''
+\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 correctly process 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.
@@ -410,6 +456,9 @@ function foo(A,___MissingCloseParenHere___)
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}