#LyX 1.6.5 created this file. For more info see http://www.lyx.org/ \lyxformat 345 \begin_document \begin_header \textclass article \begin_preamble % for: LaTeX DogWagger version=`4.0.1' fileTarget=`Dogwagger402.pl' startComment=`#' %======================================================================== % LaTeX Dogwagger takes LaTeX files and pulls out verbatim comments, % % concatenating the text enclosed in these verbatim comments % % into executable code. Copyright (C) J van Schalkwyk, 2005. % % LaTeX Dogwagger is made available under the GNU Public Licence (GPL). % % To NOT include a particular verbatim section, a comment line % % containing the text: DogWagger dogsAllowed=`no' must precede *ANY* % % line containing the text \begin{verbatim} ! % %=============================================================== \hyphenation{fileTarget endFile} \usepackage{titlesec} \hyphenation{fileTarget endFile} \titleformat{\section}{\LARGE\sffamily}{\thesection}{1em}{} \titleformat{\subsection}{\Large\sffamily}{\thesubsection}{0.5em}{} \titleformat{\subsubsection}{\large\sffamily}{\thesubsubsection}{0.5em}{} \end_preamble \use_default_options false \begin_modules theorems-ams eqs-within-sections figs-within-sections \end_modules \language english \inputencoding auto \font_roman times \font_sans berasans \font_typewriter beramono \font_default_family rmdefault \font_sc false \font_osf false \font_sf_scale 90 \font_tt_scale 80 \graphics default \paperfontsize 12 \spacing single \use_hyperref true \pdf_bookmarks true \pdf_bookmarksnumbered false \pdf_bookmarksopen false \pdf_bookmarksopenlevel 1 \pdf_breaklinks false \pdf_pdfborder true \pdf_colorlinks true \pdf_backref false \pdf_pdfusetitle true \papersize a4paper \use_geometry false \use_amsmath 2 \use_esint 1 \cite_engine natbib_authoryear \use_bibtopic false \paperorientation portrait \secnumdepth 3 \tocdepth 3 \paragraph_separation indent \defskip medskip \quotes_language english \papercolumns 1 \papersides 1 \paperpagestyle fancy \tracking_changes false \output_changes false \author "" \author "" \end_header \begin_body \begin_layout Title \family sans \size giant LaTeX \begin_inset space \space{} \end_inset Dogwagger \begin_inset Newline newline \end_inset \size footnotesize [A different approach to documentation] \size normal \begin_inset Newline newline \end_inset \size scriptsize Version 4.0.2 \end_layout \begin_layout Author J.M. van Schalkwyk \end_layout \begin_layout Standard \end_layout \begin_layout Standard \begin_inset Wrap figure lines 5 placement o overhang 2in width "3cm" status open \begin_layout Plain Layout \begin_inset ERT status open \begin_layout Plain Layout \backslash vskip -4.2in \backslash hskip -4.6in \end_layout \end_inset \begin_inset Graphics filename images/Dogwagger.png lyxscale 25 width 5.5cm height 4cm \end_inset \begin_inset Note Note status open \begin_layout Plain Layout OK, inelegant. (better in preamble) \end_layout \end_inset \end_layout \end_inset \end_layout \begin_layout Standard \family sans \begin_inset CommandInset toc LatexCommand tableofcontents \end_inset \family default \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section Introduction \end_layout \begin_layout Standard In a single line, you can change for the better how you document your computer code. Here's that line: \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % DogWagger version= \backslash textrm{ \backslash large`}4.0.2' fileTarget= \backslash textrm{ \backslash large`}MYFILE.pl' \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \begin_inset Note Note status open \begin_layout Plain Layout I use \backslash textrm{ \backslash large`} to emphasize the backticks! \end_layout \end_inset \end_layout \begin_layout Standard Inserted at the start of a LaTeX file, this comment line allows you to combine your code and documentation \emph on without \emph default having to learn the use of new tools. This example generates Perl but, with a little help from Dogwagger, a single LaTeX file can spawn multiple different files in multiple languages --- html, PHP, Javascript, C, C++, SQL, R, Erlang, and so forth. \end_layout \begin_layout Subsection* What's the catch? \end_layout \begin_layout Standard The only catch is that you must be familiar with LaTeX, or (for those who are allergic to natural rubber), you must have tried the almost-human-friendly alternative, LyX. \begin_inset Foot status open \begin_layout Plain Layout LyX users must however be familiar with the term \begin_inset Quotes eld \end_inset evil red text \begin_inset Quotes erd \end_inset . \end_layout \end_inset If you're terrified by the idea of running a program from the command line, then Dogwagger may also not be for you. \end_layout \begin_layout Standard Dogwagger is freely available under the GNU Public Licence (See Appendix \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sec:Appendix:-GNU-GPL" \end_inset ), and will work with a simple, free text editor (like Notepad, vim, Emacs) or specific LaTeX-friendly editors like LyX and Kile. \end_layout \begin_layout Subsection* How does it work? \end_layout \begin_layout Standard You simply embed all of your code within the LaTeX document as \emph on verbatim \emph default statements, and submit the .tex file to DogWagger, which pulls out the code and turns it into a program. The living proof of this is the document you're reading, which not only describes but \emph on contains \emph default the entire source code of Dogwagger! \end_layout \begin_layout Subsection* Why Dogwagger? \end_layout \begin_layout Standard It's simple. Other documentation managers have problems: \end_layout \begin_layout Itemize Complex dependencies; \end_layout \begin_layout Itemize A steep learning curve; or \end_layout \begin_layout Itemize The need to adopt a new programming approach (e.g. noweb). \begin_inset Foot status open \begin_layout Plain Layout A new approach may not be an entirely bad thing, but the resulting fragmentation may not be kind to those used to reading \begin_inset Quotes eld \end_inset more normal \begin_inset Quotes erd \end_inset code. \end_layout \end_inset \end_layout \begin_layout Subsection* Why the name? \end_layout \begin_layout Standard Conventional documentation of computer code often looks tacked on, resembling the stumpy, customarily docked tail of a large rottweiler. Dogwagger tries to address this problem by integrating the documentation and the program. The program becomes something which is pulled out of the documentation, rather than the other way around. \end_layout \begin_layout Standard For example, in the great programming language Perl, there's a convention that allows you to mark sections of the program with an equals sign, followed by a name. All of the subsequent code is ignored by Perl until a magic line beginning with the expression \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+=cut+ \end_layout \end_inset is encountered. A separate program can then be used to pull out the \emph on cut \emph default sections and assemble them into some sort of documentation. This approach is called POD, or `Plain Old Documentation'. Dogwagger, although it is written in Perl, is more sophisticated, as it works the other way around. The tail wags the dog. \end_layout \begin_layout Subsection* Why LaTeX & Perl? \end_layout \begin_layout Standard LaTeX is a good way to produce documents that are both functional and fairly elegant, especially if you're working on a large project and need good technical documentation. It's the document preparation system of choice for mathematical and astrophysic al journals, and has been tried and tested over decades. Perl is powerful and available on almost any platform you care to mention. \end_layout \begin_layout Subsection* How do I run Dogwagger? \end_layout \begin_layout Standard You will need Perl installed on your system (most UNIX and Linux systems will have it; with MS Windows, consider Strawberry Perl or ActivePerl). \end_layout \begin_layout Standard Open up a console box (otherwise known as a `terminal' or the `command line', e.g. Konsole in Ubuntu, or a DOS box in MS Windows), change to the directory where you've put the file Dogwagger402.pl, and type in: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash hskip 1cm \backslash textbf{perl Dogwagger402.pl MYFILE.tex} \end_layout \end_inset \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \SpecialChar \ldots{} for Dogwagger to work its magic. Type the following from the command line: \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash hskip 1cm \end_layout \end_inset \family sans \series bold perl Dogwagger402.pl \begin_inset space \quad{} \end_inset - \begin_inset space \thinspace{} \end_inset -help \end_layout \begin_layout Standard \begin_inset Note Note status open \begin_layout Plain Layout \series bold - \begin_inset space \thinspace{} \end_inset - \series default Small space inserted to make the bugger legible. Hmm. \end_layout \begin_layout Plain Layout and why does \series bold \begin_inset ERT status open \begin_layout Plain Layout \backslash texttt{--} \end_layout \end_inset fail?? Oh, of course, -- is en-dash! \end_layout \end_inset \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \SpecialChar \ldots{} for a full list of options, or simply read on. \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Subsection Dogwagger: Advantages & disadvantages \end_layout \begin_layout Standard The few disadvantages have already been mentioned. In more detail the advantages are: \end_layout \begin_layout Itemize Program code and documentation are seamlessly integrated; \end_layout \begin_layout Itemize Updates are concurrent. You can update program and documentation at one go, and generate program \emph on or \emph default documentation by simply submitting the same file to either PDFLaTeX \begin_inset space \space{} \end_inset or Dogwagger; \end_layout \begin_layout Itemize Binary code can be integrated (as required) with other code, without needing fancy tools or many different types of file; \end_layout \begin_layout Itemize As Dogwagger is available under the GNU public licence, it'll aways be freely available. You can download the source code of this file (Dogwagger402.tex) from the dogwagger page at the website \begin_inset CommandInset href LatexCommand href name "anaesthetist.com" target "http://www.anaesthetist.com/mnm/dogwagger/index.htm" \end_inset . \end_layout \begin_layout Subsection GNU Public Licence \end_layout \begin_layout Standard \series bold NB. \series default This program is distributed under the Gnu Public Licence (GPL). A copy should accompany any distribution. For details of the GPL, see Appendix \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sec:Appendix:-GNU-GPL" \end_inset , at the end of this document. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. \end_layout \begin_layout Standard You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash hypertarget{below}{ \end_layout \end_inset \begin_inset ERT status collapsed \begin_layout Plain Layout } \end_layout \end_inset \end_layout \begin_layout Section How to use Dogwagger \end_layout \begin_layout Standard If you read the LaTeX \begin_inset space \space{} \end_inset source for \emph on this file \emph default , (available as both .lyx and .tex documents) then you'll see Dogwagger in action! But to get a bit more than a flavour read the following documentation thoroughly. The basic idea is: \end_layout \begin_layout Enumerate Create your LaTeX \begin_inset space \space{} \end_inset documentation; \end_layout \begin_layout Enumerate At will, insert sections of program within the documentation as \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+ \backslash verbatim+ \end_layout \end_inset comments --- these chunks will eventually all be concatenated into one program file! \end_layout \begin_layout Enumerate Dress things up a little. \end_layout \begin_layout Standard That's really it. The dressing up is very easy indeed. You've already encountered the most important piece of `dressing up', the Dogwagger title line: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % Dogwagger version= \backslash textrm{ \backslash large`}4.0.2' fileTarget= \backslash textrm{ \backslash large`}foo.pl' \end_layout \begin_layout Plain Layout \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard If such a line isn't present, and you submit a file for Dogwagger to parse, then she will complain bitterly. You'll also get warnings if the version number is wrong. Note the backticks ( \begin_inset ERT status open \begin_layout Plain Layout \backslash textrm{ \backslash large`} \end_layout \end_inset ) at the start of \begin_inset ERT status open \begin_layout Plain Layout \backslash textrm{ \backslash large`} \end_layout \end_inset quoted items \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+'+ \end_layout \end_inset . The \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+fileTarget+ \end_layout \end_inset instruction is self-explanatory. \end_layout \begin_layout Standard There are a two other parameters you will almost certainly use on this important title line. Examples are: \end_layout \begin_layout Itemize \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout startComment= \backslash textrm{ \backslash large`} \backslash #' \end_layout \end_inset \end_layout \begin_layout Itemize \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout noWarn= \backslash textrm{ \backslash large`}yes' \end_layout \end_inset \end_layout \begin_layout Standard The \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+startComment+ \end_layout \end_inset option specifies how lines will be commented out. This is important because DogWagger normally writes a few lines at the start of a generated file saying where the file came from and when it was created. In addition, separate sections in the generated program code are separated by comments. The default comment character is \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+#+ \end_layout \end_inset . \end_layout \begin_layout Standard Different programming languages use different character sequences to signal a comment line --- for example, C++ uses a double slash \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+//+ \end_layout \end_inset , and Perl uses \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+#+ \end_layout \end_inset ! But we can even implement the old-fashioned C \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+/*+ \end_layout \end_inset comment style \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+*/+ \end_layout \end_inset with the following combination of instructions: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % Dogwagger startComment= \backslash textrm{ \backslash large`}/*' endComment= \backslash textrm{ \backslash large`}*/' [etc] \end_layout \begin_layout Plain Layout \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard By default, Dogwagger kindly warns you before it overwrites files, but you can override this behaviour using \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout noWarn= \backslash textrm{ \backslash large`}yes' \end_layout \end_inset \family default \color inherit . \end_layout \begin_layout Subsection Suppress unwanted \emph on verbatim \emph default sections \end_layout \begin_layout Standard If you don't want the next \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+verbatim+ \end_layout \end_inset section to appear in code, say: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % Dogwagger dogsAllowed= \backslash textrm{ \backslash large`}no' \end_layout \begin_layout Plain Layout \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Subsection Make multiple files \end_layout \begin_layout Standard Part of the way through your documentation, you may wish to terminate the current code (file) you're creating, and start a new file. For example, you may have discussed (and created) the main CPP program, and now wish to do the same for the .H header file. This is pretty easy. In the line \emph on immediately preceding \emph default the next \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+verbatim+ \end_layout \end_inset section, insert a commented line similar to the following: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % Dogwagger newTarget= \backslash textrm{ \backslash large`}foobar.h' startComment= \backslash textrm{ \backslash large`}//' \end_layout \begin_layout Plain Layout \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard Remember to make the very first character of the line a `%', so as to comment the line out in LaTeX. See how we use \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout newTarget \end_layout \end_inset \family default \color inherit to remind ourselves that this isn't the first file specified in the title line, but a subsequent one. \end_layout \begin_layout Subsubsection Files within directories \end_layout \begin_layout Standard We deliberately don't encourage files generated by DogWagger to be written to obscure locations. Files can however be written to an \emph on existing \emph default subdirectory thus: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % Dogwagger newTarget= \backslash textrm{ \backslash large`}foo/bar.c' startComment= \backslash textrm{ \backslash large`}//' \end_layout \begin_layout Plain Layout \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard This statement creates the file \emph on bar.c \emph default in the subdirectory \emph on foo \emph default . Always use a forward slash (a la Unix) not the DOS/MS Windows backslash. Dogwagger will \emph on not \emph default create the subdirectory. \end_layout \begin_layout Subsection Deferred code \end_layout \begin_layout Standard \begin_inset CommandInset label LatexCommand label name "deferred" \end_inset You can \emph on defer \emph default writing of a code section until other sections on which it \emph on depends \emph default have been written to the output file. For example, when discussing SQL code, we might wish to talk about the main table first, but in the final code we will first want to define the minor tables on which the main table depends! \end_layout \begin_layout Standard To make use of this facility, use the following commands: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % Dogwagger dependsOn= \backslash textrm{ \backslash large`}alpha' \end_layout \begin_layout Plain Layout \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \SpecialChar \ldots{} or even, if something depends on several other sections: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % Dogwagger dependsOn= \backslash textrm{ \backslash large`}alpha,beta,gamma' \end_layout \begin_layout Plain Layout \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard The name of the section depended on is then given by: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % Dogwagger myName= \backslash textrm{ \backslash large`}alpha' \end_layout \begin_layout Plain Layout \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard When a dependsOn statement is encountered the assumption is made that \emph on all \emph default of the names depended on have \emph on not yet been defined \emph default ! If any of them existed, then the smart user would simply leave them out! \end_layout \begin_layout Standard An item can have entries for both \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout myName \end_layout \end_inset \family default \color inherit and \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout dependsOn \end_layout \end_inset \family default \color inherit . In this case, the name is kept pending until all \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout dependsOn \end_layout \end_inset \family default \color inherit blocks have been created, at which point the item is written to output; then only is the name of the item itself resolved. \begin_inset Foot status open \begin_layout Plain Layout Self-dependence will be unresolved, causing an error. \end_layout \end_inset \end_layout \begin_layout Standard It's important to realise that if two sections of code A and B are deferred pending the writing of code C, then the only way to ensure that B is written after A is to explicitly state that B depends on A. \end_layout \begin_layout Subsection Include binary files \end_layout \begin_layout Standard Because binary files, especially executable ones, are inscrutable (and potential ly harmful) you should generally avoid spreading them around, but occasionally it may be necessary to include such a file with your source code. Dogwagger meets this need by allowing UUencoded files to be included in \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+verbatim+ \end_layout \end_inset sections thus: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % Dogwagger newTarget= \backslash textrm{ \backslash large`}uudecode' \end_layout \begin_layout Plain Layout \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard In other words, the only `filename' which is reserved is the case-sensitive \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout uudecode \end_layout \end_inset \family default \color inherit . If this name is specified, then (as is usual for uunecoded files) the filename is picked out of the subsequent uuencoded information, located within the verbatim statement. There's a (uuencoded) uunecoding program in Appendix \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sec:Appendix:-UUencoding-program" \end_inset . \begin_inset Foot status collapsed \begin_layout Plain Layout In Ubuntu Linux, try \begin_inset Quotes eld \end_inset sudo apt-get install sharutils \begin_inset Quotes erd \end_inset . \end_layout \end_inset \end_layout \begin_layout Standard Because uuencoded text for a single file must be contained in one \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+verbatim+ \end_layout \end_inset section, and this file is written immediately, you can write such a file from within the middle of creating other code. (This means that, in contrast to \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+newTarget+ \end_layout \end_inset , you should not specify uuencode as the \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+fileTarget+ \end_layout \end_inset parameter). \begin_inset Note Note status open \begin_layout Plain Layout although this is not formally enforced. \end_layout \end_inset \end_layout \begin_layout Subsection Minor frills and restrictions \end_layout \begin_layout Standard In between the beginning and end of each \begin_inset ERT status open \begin_layout Plain Layout `verbatim' \end_layout \end_inset section there \emph on must \emph default be at least one line of data. If you put a carriage return immediately after the \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+ \backslash begin{+ \backslash verb+verbatim}+ \end_layout \end_inset it will be ignored. However, a carriage return just before an \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+ \backslash end{+ \backslash verb+verbatim}+ \end_layout \end_inset statement will be included in the output code. Play with this feature. \end_layout \begin_layout Standard There are several little conveniences in DogWagger. You can label the comment at the start of each section using a line like the following \emph on immediately preceding \emph default a \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+verbatim+ \end_layout \end_inset section: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % Dogwagger sectionTitle= \backslash textrm{ \backslash large`}This is a BIG BOLD section' \end_layout \begin_layout Plain Layout \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard We can do slightly more fancy things: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash % Dogwagger sectionTitle= \backslash textrm{ \backslash large`}Foo: Section \backslash $[SECTION]' \end_layout \begin_layout Plain Layout \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \SpecialChar \ldots{} which actually uses Dogwagger's internal section counter to replace \begin_inset Newline linebreak \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash $[SECTION] \end_layout \end_inset \family default \color inherit with the relevant section number. \end_layout \begin_layout Subsubsection Write code as a single line \end_layout \begin_layout Standard Occasionally it's convenient to write several lines of verbatim text as a single line of output. Dogwagger to the rescue with the \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout oneLine= \backslash textrm{ \backslash large`}yes' \end_layout \end_inset \family default \color inherit command! \end_layout \begin_layout Standard Note that in this mode, trailing spaces count, but the leading spaces on the next line are removed. All other whitespace is preserved \emph on as is \emph default . \end_layout \begin_layout Subsection Make a debug version! \end_layout \begin_layout Standard Here's a command which you can \emph on only \emph default include in the title line: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout include= \backslash textrm{ \backslash large`}everything' \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard This wrinkle allows you to create two versions of code, a \emph on debug \emph default version, and a production version. By default, if you \emph on omit \emph default the above command from the title line, then the production version is created. If you include it, then we make a debug version. And what's the difference? Well, if Dogwagger encounters a line within a \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+verbatim+ \end_layout \end_inset section which begins with the sequence: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout +OPTIONAL \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \SpecialChar \ldots{} then by default all of the code \begin_inset Note Note status open \begin_layout Plain Layout (including, of course, the OPTIONAL statement itself) \end_layout \end_inset is \emph on omitted \emph default until: \end_layout \begin_layout Standard \begin_inset VSpace defskip \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout -OPTIONAL \end_layout \end_inset \family default \color inherit \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard is encountered later on. `Including everything' forces Dogwagger to include this optional code. \end_layout \begin_layout Standard In many languages, there are ways of creating debug versions, for example the C++ \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+#define+ \end_layout \end_inset followed by \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+#ifdef+ \end_layout \end_inset and so on, but our way is more explicit and simpler. \begin_inset Foot status collapsed \begin_layout Plain Layout We considered having an optional parameter after the OPTIONAL statement to allow multiple versions, but rejected this as extremely silly. \end_layout \end_inset \end_layout \begin_layout Subsection Use Dogwagger with LyX \begin_inset CommandInset label LatexCommand label name "sub:Use-Dogwagger-with-LyX" \end_inset \end_layout \begin_layout Standard I believe that LyX, the first \begin_inset Quotes eld \end_inset what you see is what you mean \begin_inset Quotes erd \end_inset word-processor, is now mature enough to supplant other LaTeX editors. Put \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+ \backslash begin+ \backslash verb+{verbatim}+ \end_layout \end_inset and \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+ \backslash end+ \backslash verb+{verbatim}+ \end_layout \end_inset statements and contained code within \begin_inset Quotes eld \end_inset Evil Red Text \begin_inset Quotes erd \end_inset boxes (ERT, press Control+L). There are only two catches: \end_layout \begin_layout Enumerate ERT is raw LaTeX, so be careful to balance begin/end statements, braces, $ and so forth. (Also use \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+ \backslash verb+ \end_layout \end_inset with great caution). \end_layout \begin_layout Enumerate It's best to start the ERT with a comment line, before the actual \begin_inset Newline linebreak \end_inset \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash %~DogWagger \end_layout \end_inset \family default \color inherit line. This is because LyX may otherwise sometimes confuse Dogwagger by putting other characters before the % at the start of the \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash %~DogWagger \end_layout \end_inset \family default \color inherit line. \end_layout \begin_layout Standard The very first Dogwagger line is best put in the LaTeX preamble (Document | Settings). \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section The source code of Dogwagger \end_layout \begin_layout Standard Here's the Dogwagger version 4.0.2 code. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout %Ignore the `=name' and `=cut' statements, as they are merely a convenience \end_layout \begin_layout Plain Layout \end_layout \end_inset \begin_inset ERT status open \begin_layout Plain Layout %to permit the original TEX file to be executed as a Perl script! \backslash footnote{As discussed above!} \end_layout \begin_layout Plain Layout \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Header (Section $[SECTION])' \end_layout \begin_layout Plain Layout { \backslash footnotesize \backslash begin{verbatim} \end_layout \begin_layout Plain Layout #!/usr/local/bin/perl -w \end_layout \begin_layout Plain Layout use strict; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout ################################################################### \end_layout \begin_layout Plain Layout # This program is distributed under the Gnu Public Licence (GPL). \end_layout \begin_layout Plain Layout # You should have received a copy of the GNU General Public License \end_layout \begin_layout Plain Layout # along with this program; if not, write to the Free Software \end_layout \begin_layout Plain Layout # Foundation, Inc., 59 Temple Place - Suite 330, \end_layout \begin_layout Plain Layout # Boston, MA 02111-1307, USA. \end_layout \begin_layout Plain Layout ################################################################### \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout my $ERRCOUNT=0; # global. Ugh. \end_layout \begin_layout Plain Layout my $LINECOUNT=0; # likewise \end_layout \begin_layout Plain Layout my $OPTN=0; # global that supports +OPTIONAL \end_layout \begin_layout Plain Layout my $MAJORVERSION = 4; # * REMEMBER TO CHANGE FROM VERSION 4.0.2 \end_layout \begin_layout Plain Layout my $MINORVERSION = 0; # * REMEMBER TO CHANGE FROM VERSION 4.0.2 \end_layout \begin_layout Plain Layout my $TV = 2; # * version 4.0.2 (TV = tinyversion) \end_layout \begin_layout Plain Layout \backslash end{verbatim}} \end_layout \end_inset \end_layout \begin_layout Subsection Initialisation \end_layout \begin_layout Standard We get the current (system) time (Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sub:Read-the-time" \end_inset ), and then create several important arrays used for processing of deferred code. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Initialisation (Section $[SECTION])' \end_layout \begin_layout Plain Layout { \backslash footnotesize \backslash begin{verbatim} \end_layout \begin_layout Plain Layout my $TODAY = &GetLocalTime(); \end_layout \begin_layout Plain Layout my @CHILDREN; \end_layout \begin_layout Plain Layout my @DEPENDENCIES; \end_layout \begin_layout Plain Layout my @PENDINGNAME; \end_layout \begin_layout Plain Layout my $DEFAULTNEWLINE = " \backslash n"; \end_layout \begin_layout Plain Layout my $NEWLINE = $DEFAULTNEWLINE; \end_layout \begin_layout Plain Layout \backslash end{verbatim}} \end_layout \end_inset \end_layout \begin_layout Standard The deferred arrays are CHILDREN (an array of sections which depend on other named sections, and haven't yet been written to file), DEPENDENCIES which stores the corresponding names \emph on depended on \emph default , and PENDINGNAME, which stores the name of each child, if that child has a name. \end_layout \begin_layout Standard Each child contains multiple lines which will only be written to file when all of the dependencies of the child have been satisfied. As each name is encountered, it is removed from each dependency list where it occurs. If a dependency list becomes \emph on empty \emph default in this process, the corresponding item is written to output. \end_layout \begin_layout Standard The variable \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+$NEWLINE+ \end_layout \end_inset is a global that lets us specify the newline character(s) throughout all files that are printed. \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section Startup \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash vskip -1mm \end_layout \end_inset \begin_inset Note Note status open \begin_layout Plain Layout to fit help onto a page! \end_layout \begin_layout Plain Layout NOTE that in LyX, changing the baseline mono font size does NOT affect linespaci ng, but using footnotesize does! \end_layout \end_inset We handle the command line \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+--help+ \end_layout \end_inset option with a help message: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Startup (Section $[SECTION])' \end_layout \begin_layout Plain Layout { \backslash footnotesize \backslash begin{verbatim} \end_layout \begin_layout Plain Layout my ($HelpMessage) = " \backslash n perl Dogwagger" \end_layout \begin_layout Plain Layout . " $MAJORVERSION$MINORVERSION$TV.pl SOURCENAME.tex [log=WAGLOG.LOG] \backslash n" \end_layout \begin_layout Plain Layout . " See: http://www.anaesthetist.com/mnm/dogwagger/ \backslash n" \end_layout \begin_layout Plain Layout . "================================================================== \backslash n" \end_layout \begin_layout Plain Layout . " *Picks out program code from within LaTeX verbatim statements* \backslash n" \end_layout \begin_layout Plain Layout . " Within the .tex file, a DOGWAGGER LINE starts with \backslash n" \end_layout \begin_layout Plain Layout . "% Dogwagger \backslash n" \end_layout \begin_layout Plain Layout . " ... followed on that line by one or more of: \backslash n" \end_layout \begin_layout Plain Layout . " Option (example) Meaning \backslash n" \end_layout \begin_layout Plain Layout . " -------------------- --------------------------------------- \backslash n" \end_layout \begin_layout Plain Layout . " version=`4.0.2' ... state optimal Dogwagger version to use \backslash n" \end_layout \begin_layout Plain Layout . " fileTarget=`FOO.BAR' ... the name of the very FIRST target file \backslash n" \end_layout \begin_layout Plain Layout . " [newLine=` \backslash \backslash n \backslash \backslash r'] ... replace newline characters with these. \backslash n" \end_layout \begin_layout Plain Layout . " <> \backslash n" \end_layout \begin_layout Plain Layout . " newTarget=`NEW.BAR' ... end off preceding file, start new file \backslash n" \end_layout \begin_layout Plain Layout . " <> \backslash n" \end_layout \begin_layout Plain Layout . " startFile=`' ... final text in file, default is also '' \backslash n" \end_layout \begin_layout Plain Layout . " noHeader=`yes' ... Dogwagger will now not write a header \backslash n" \end_layout \begin_layout Plain Layout . " noTail=`yes' ... omit all Dogwagger code at end of file \backslash n" \end_layout \begin_layout Plain Layout . " startComment=`' ... how comment ends, (default is nothing) \backslash n" \end_layout \begin_layout Plain Layout . " noWarn=`yes' ... do NOT warn before overwriting a file. \backslash n" \end_layout \begin_layout Plain Layout . " <> \backslash n" \end_layout \begin_layout Plain Layout . " dogsAllowed=`no' ... do NOT include following verbatim text \backslash n" \end_layout \begin_layout Plain Layout . " sectionTitle=`BLAH' ... force use of this as new section title \backslash n" \end_layout \begin_layout Plain Layout . " noSections=`yes' ... turn section titles on (or off: `no') \backslash n" \end_layout \begin_layout Plain Layout . " oneLine=`yes' ... in this block alone, concatenate lines \backslash n" \end_layout \begin_layout Plain Layout . " (with suppression of leading spaces) \backslash n" \end_layout \begin_layout Plain Layout . " dependsOn=`ALPHA' ... defer writing text until name defined \backslash n" \end_layout \begin_layout Plain Layout . " dependsOn=`A,B,C' ... defer until multiple blocks are named \backslash n" \end_layout \begin_layout Plain Layout . " myName=`ALPHA' ... name a block (this is case sensitive) \backslash n" \end_layout \begin_layout Plain Layout . " newTarget=`uudecode' ... just extract a single uuencoded file. \backslash n" \end_layout \begin_layout Plain Layout . " <> \backslash n" \end_layout \begin_layout Plain Layout . " *--------------------------------------------------------------* \backslash n" \end_layout \begin_layout Plain Layout . " Your LaTeX code must include, in its first 40 lines, a DOGWAGGER \backslash n" \end_layout \begin_layout Plain Layout . " LINE that describes both the version and the first target file. \backslash n" \end_layout \begin_layout Plain Layout . " All subsequent LaTeX verbatim sections are appended, by default. \backslash n" \end_layout \begin_layout Plain Layout . " To modify behaviour, put a DOGWAGGER LINE immediately preceding \backslash n" \end_layout \begin_layout Plain Layout . " the first line of a verbatim statement, using the above options. \backslash n" \end_layout \begin_layout Plain Layout . " *--------------------------------------------------------------* \backslash n" \end_layout \begin_layout Plain Layout . " Dogwagger 4.0.2 is Copyright (C) J van Schalkwyk, 2005--2011 \backslash n" \end_layout \begin_layout Plain Layout . " Made available under the GNU General Public Licence v2. \backslash n" \end_layout \begin_layout Plain Layout . "================================================================= \backslash n"; \end_layout \begin_layout Plain Layout \backslash end{verbatim}} \end_layout \end_inset \end_layout \begin_layout Standard After printing a Dogwagger banner (and the date), we obtain the name of the .tex source file from the command line (ARGV). If this is instead a request for help, we print the help message and exit; otherwise we validate the file name. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` write header (Section $[SECTION])' \end_layout \begin_layout Plain Layout { \backslash footnotesize \backslash begin{verbatim} \end_layout \begin_layout Plain Layout my ($fido) = ""; # file name \end_layout \begin_layout Plain Layout print " \backslash n \backslash n ======================= \backslash n" \end_layout \begin_layout Plain Layout . " Dogwagger Version " \end_layout \begin_layout Plain Layout . "$MAJORVERSION.$MINORVERSION.$TV \backslash n" \end_layout \begin_layout Plain Layout . " ======================= \backslash n"; \end_layout \begin_layout Plain Layout print (" $TODAY \backslash n"); \end_layout \begin_layout Plain Layout $fido = $ARGV[0]; # command line \end_layout \begin_layout Plain Layout if ( $fido =~ /--help/i ) \end_layout \begin_layout Plain Layout { print $HelpMessage; \end_layout \begin_layout Plain Layout exit; \end_layout \begin_layout Plain Layout } else \end_layout \begin_layout Plain Layout { print " (Try --help for help) \backslash n"; }; \end_layout \begin_layout Plain Layout if ( !(defined $fido) || ((length $fido) < 5)) \end_layout \begin_layout Plain Layout { die "Error. Bad file name. " \end_layout \begin_layout Plain Layout . "Please submit a valid name e.g. foo.tex"; }; \end_layout \begin_layout Plain Layout \backslash end{verbatim}} \end_layout \end_inset \end_layout \begin_layout Standard We check for a log file (a second, optional, command-line \begin_inset Newline linebreak \end_inset argument \series bold \begin_inset ERT status open \begin_layout Plain Layout log=FOO.log \end_layout \end_inset \series default ), and otherwise default to the name \begin_inset Newline linebreak \end_inset WAGLOG.LOG. We open this log, and then invoke WagTheDog: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Open log file (Section $[SECTION])' \end_layout \begin_layout Plain Layout { \backslash footnotesize \backslash begin{verbatim} \end_layout \begin_layout Plain Layout my $filelog = $ARGV[1]; # format is: log=filename.xxx \end_layout \begin_layout Plain Layout if ($filelog =~ /log=( \backslash w+ \backslash . \backslash w+)/i ) \end_layout \begin_layout Plain Layout { $filelog = $1; # pull out name \end_layout \begin_layout Plain Layout } else \end_layout \begin_layout Plain Layout { $filelog="WAGLOG.LOG"; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout open FILELOG, ">$filelog" or \end_layout \begin_layout Plain Layout die "*CRASH* Could not open LOG <$filelog> :$! \backslash n"; \end_layout \begin_layout Plain Layout print FILELOG "LaTeX DogWagger, Version " \end_layout \begin_layout Plain Layout . "$MAJORVERSION.$MINORVERSION.$TV [$TODAY]"; \end_layout \begin_layout Plain Layout &Caution ("INPUT file: <$fido>"); \end_layout \begin_layout Plain Layout my $cSECTIONS= 0; # 4 globals: count verbatim sections, \end_layout \begin_layout Plain Layout my $cFILES = 1; # generated files (must be >=1), \end_layout \begin_layout Plain Layout my $cSKIP = 0; # sections skipped, \end_layout \begin_layout Plain Layout my $cOUST = 0; # and files overwritten. \end_layout \begin_layout Plain Layout if ( (my $fail = WagTheDog($fido)) \end_layout \begin_layout Plain Layout ||($ERRCOUNT > 0) \end_layout \begin_layout Plain Layout ) { print " \backslash n*Problems: $fail, Errors=$ERRCOUNT \backslash n"; }; \end_layout \begin_layout Plain Layout $TODAY = &GetLocalTime(); \end_layout \begin_layout Plain Layout &Caution( "Done [$TODAY]. Sections:$cSECTIONS($cSKIP skipped), " \end_layout \begin_layout Plain Layout . "files:$cFILES ($cOUST overwritten). \backslash n \backslash n" ); \end_layout \begin_layout Plain Layout exit; \end_layout \begin_layout Plain Layout \backslash end{verbatim}} \end_layout \end_inset \end_layout \begin_layout Standard The main function WagTheDog (§ \begin_inset CommandInset ref LatexCommand ref reference "sec:The-principal-function" \end_inset ) returns an error message if it fails. A global error count over zero also indicates failure. \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section The principal function \begin_inset CommandInset label LatexCommand label name "sec:The-principal-function" \end_inset \end_layout \begin_layout Standard As the name suggests, WagTheDog does the work. WagTheDog has several ugly features \begin_inset Foot status collapsed \begin_layout Plain Layout Some of these are a legacy from when DogWagger had a GUI, others are just bad programming. \end_layout \end_inset --- let's see how DogWagger copes! \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub WagTheDog \end_layout \begin_layout Plain Layout { my($fido); \end_layout \begin_layout Plain Layout ($fido)=@_; \end_layout \begin_layout Plain Layout my(@CHILDREN, @DEPENDENCIES, @PENDINGNAME); \end_layout \begin_layout Plain Layout my $RETAINTARGETLINE = ''; # used for new file parameters \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection Preliminaries \end_layout \begin_layout Standard After some debugging statements and a check for the presence of a filename string, we clear the various arrays, and set up \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+myNam+ \end_layout \end_inset , which stores the name of the current block of code that is being written. Once we've finished writing this block, we will resolve all of the dependencies on \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+myNam+ \end_layout \end_inset . \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog:preliminaries (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout @CHILDREN = (); \end_layout \begin_layout Plain Layout @DEPENDENCIES = (); \end_layout \begin_layout Plain Layout @PENDINGNAME = (); \end_layout \begin_layout Plain Layout $CHILDREN[0]=''; \end_layout \begin_layout Plain Layout $DEPENDENCIES[0]=''; \end_layout \begin_layout Plain Layout $PENDINGNAME[0]=''; \end_layout \begin_layout Plain Layout my($myNam); \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard Let's open the source file, failing if this opening fails: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog:open source (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout $LINECOUNT = 0; \end_layout \begin_layout Plain Layout my ($E1) = 0; \end_layout \begin_layout Plain Layout open FIDO, $fido \end_layout \begin_layout Plain Layout or $E1 = &GlobalError("Could not open source <$fido> :$!"); \end_layout \begin_layout Plain Layout if ($E1) \end_layout \begin_layout Plain Layout { return ($E1); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection Find the header line \end_layout \begin_layout Standard Next, scan through the first n=40 lines for the header line: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog:header line (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout my($i) = 40; \end_layout \begin_layout Plain Layout while ($i > 0) \end_layout \begin_layout Plain Layout { $_ = ; \end_layout \begin_layout Plain Layout $LINECOUNT ++; \end_layout \begin_layout Plain Layout if ( / \backslash %.* Dogwagger/i ) \end_layout \begin_layout Plain Layout { $i = 0; }; # force end \end_layout \begin_layout Plain Layout $i --; }; \end_layout \begin_layout Plain Layout if (! $i) # if DogWagger found, $i should be -1. \end_layout \begin_layout Plain Layout { &Caution("DogWagger data not found in <$fido>"); \end_layout \begin_layout Plain Layout close FIDO; \end_layout \begin_layout Plain Layout return ('No data'); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout my($hotline) = $_; # redundant \end_layout \begin_layout Plain Layout $NEWLINE = &GetNewLine($hotline); # determine newline code \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard We fail if the first Dogwagger line is not encountered. The only requirements \begin_inset Note Note status open \begin_layout Plain Layout now \end_layout \end_inset are the presence of the term ` Dogwagger', and that the line is commented out à la LaTeX. \end_layout \begin_layout Subsection Check the version \end_layout \begin_layout Standard We will soon check for version compatibility, and extract Dogwagger command data into the variables defined below: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: check version (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout my ($version, $DOGFILE, $startComment, $nowarn, \end_layout \begin_layout Plain Layout $sft, $eft, \end_layout \begin_layout Plain Layout $endComment, $nohead, $nosections, $notail); \end_layout \begin_layout Plain Layout # amended 2011-12-18 \end_layout \begin_layout Plain Layout my($majorVersion, $minorVersion); \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard All variables apart from those pertaining to comments are reset to default (null string) after the closure of the current file, so for each file with starting and/or ending text, the values must be specified anew! ReadHeader (Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sec:Reading-the-header" \end_inset ) obtains the values: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: ReadHeader (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout my($MANDATORY); \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout ($version, $DOGFILE, $startComment, $nowarn, $MANDATORY, \end_layout \begin_layout Plain Layout $sft, $eft, $endComment, $nohead, \end_layout \begin_layout Plain Layout $nosections, $notail) = &ReadHeader($hotline); \end_layout \begin_layout Plain Layout # nohead.. added 2011-12-18 \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout if ($version == 0) # error \end_layout \begin_layout Plain Layout { return ('Bad header'); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout $_ = $version; \end_layout \begin_layout Plain Layout /(.+) \backslash .(.+) \backslash .(.+)/; # pull out major and minor version numbers: \end_layout \begin_layout Plain Layout $majorVersion = $1; \end_layout \begin_layout Plain Layout $minorVersion = $2; # ignore trivial version number = $3 \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard We check the version specified against the current version of Dogwagger: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog:confirm version (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout if ($majorVersion > $MAJORVERSION) \end_layout \begin_layout Plain Layout { &Caution( \end_layout \begin_layout Plain Layout "Warning: DogWag(V$MAJORVERSION.$MINORVERSION) " \end_layout \begin_layout Plain Layout . "won't support all features of V$majorVersion.$minorVersion"); \end_layout \begin_layout Plain Layout } else \end_layout \begin_layout Plain Layout { if ( ($majorVersion == $MAJORVERSION) \end_layout \begin_layout Plain Layout &&($minorVersion > $MINORVERSION) \end_layout \begin_layout Plain Layout ) \end_layout \begin_layout Plain Layout { &Caution( "Caution: minor version switch. " \end_layout \begin_layout Plain Layout . "Problems may abound!"); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard Dogwagger emits appropriate warnings if either the major or minor version numbers of Dogwagger are incompatible with those in the file being translated. Trivial version numbers (the third part of the dotted version number) are ignored. \end_layout \begin_layout Subsection Open the target file \end_layout \begin_layout Standard We open the target file (Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sub:Open-the-target" \end_inset ), using the name provided, and fail if this fails. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: open target (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout my ($ok, $wagline); \end_layout \begin_layout Plain Layout if (! OpenTargetFile($DOGFILE, $startComment, $fido, \end_layout \begin_layout Plain Layout $nowarn, $sft, $endComment, $nohead)) \end_layout \begin_layout Plain Layout # nohead.. added 2011-12-18 \end_layout \begin_layout Plain Layout { return ("Could not open target <$DOGFILE>"); }; #fail \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection Read source, and process \end_layout \begin_layout Standard Now we're ready to read in the source file, and process it. \begin_inset Note Note status open \begin_layout Plain Layout Note that as of v \begin_inset space ~ \end_inset 4.0.1, a verbatim statement that is commented out will not be included. \end_layout \end_inset Several startup flags control interpretation, the most important being \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+ishot+ \end_layout \end_inset , which determines whether we are actively writing lines, or just throwing away LaTeX \begin_inset space \space{} \end_inset text. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: read source (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout my($ishot, $hotdata, $chomper, $chomped, $hotline); \end_layout \begin_layout Plain Layout my($nodogs); \end_layout \begin_layout Plain Layout my($SECTION) = 1; \end_layout \begin_layout Plain Layout my ($SECTIONTITLE) = ''; # default is empty \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout $ishot = 0; \end_layout \begin_layout Plain Layout $chomper = 0; # default is OFF \end_layout \begin_layout Plain Layout $chomped = 0; \end_layout \begin_layout Plain Layout $ok = 1; \end_layout \begin_layout Plain Layout $nodogs = 0; # default \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard A biig \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+while+ \end_layout \end_inset statement surrounds everything, within which we read each line in turn and process it. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: main WHILE (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout while($ok) # an enormous while statement **** \end_layout \begin_layout Plain Layout { $_ = ; \end_layout \begin_layout Plain Layout if (! defined) # force exit ($ok = 0) if end of file. \end_layout \begin_layout Plain Layout { $ok = 0; \end_layout \begin_layout Plain Layout } else \end_layout \begin_layout Plain Layout { $_ = &ChompLine($_); \end_layout \begin_layout Plain Layout $LINECOUNT ++; \end_layout \begin_layout Plain Layout if (! $ishot) # if not writing \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard In the above, ChompLine (Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sub:ChompLine" \end_inset ) chomps the terminal `newline' character(s) off the input line that is read from the file handle \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+FIDO+ \end_layout \end_inset . \end_layout \begin_layout Subsection Not hot \begin_inset CommandInset label LatexCommand label name "sub:Not-hot" \end_inset \end_layout \begin_layout Standard The following code deals with the case where we are not `hot', i.e. not writing to a target file. Ideally the nested {statements} should be indented, (or the entire function should be broken down and rewritten) but I've simply removed the indentation to make the PDF more legible. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: not hot (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout ### [OUTER INDENTED SECTION] \end_layout \begin_layout Plain Layout ## ARE NOT HOT (ARE NOT WRITING): \end_layout \begin_layout Plain Layout { if ( /(.*) \backslash \backslash begin \backslash {verbatim \backslash }(.*)/ ) # if "begin verbatim": \end_layout \begin_layout Plain Layout { $cSECTIONS ++; # bump verbatim section count \end_layout \begin_layout Plain Layout if (! $nodogs) \end_layout \begin_layout Plain Layout { $hotdata = $2; # amended 2011-12-19 \end_layout \begin_layout Plain Layout if ($1 !~ / \backslash %/ ) # if verbatim not commented out \end_layout \begin_layout Plain Layout { $ishot = 1; # turn on \end_layout \begin_layout Plain Layout $SECTION = &PrintSectionHeader($startComment, \end_layout \begin_layout Plain Layout $SECTION, $endComment, $nosections, \end_layout \begin_layout Plain Layout $SECTIONTITLE); \end_layout \begin_layout Plain Layout print DOGFILE $hotdata; # clumsy but explicit \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard The above deals with the case where we've just encountered \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+ \backslash begin{+ \backslash verb+verbatim}+ \end_layout \end_inset . We ensure that this statement hasn't been commented out in LaTeX, and if not, print a section header (See § \begin_inset CommandInset ref LatexCommand ref reference "sub:Print-a-section-header" \end_inset ). Otherwise, we check for a Dogwagger instruction: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: instruction? (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout } else # NOT "begin verbatim": \end_layout \begin_layout Plain Layout { my($depOn); \end_layout \begin_layout Plain Layout $myNam = ''; \end_layout \begin_layout Plain Layout $depOn = ''; \end_layout \begin_layout Plain Layout $nodogs = 0; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout if (/^ \backslash s* \backslash % \backslash s*DogWagger/i) # if is DogWagger *** \end_layout \begin_layout Plain Layout { &PrintLogLine ( "{wag} "); \end_layout \begin_layout Plain Layout if ( /dogsAllowed= \backslash `no \backslash '/) # dogs NOT allowed \end_layout \begin_layout Plain Layout { $nodogs = 1; \end_layout \begin_layout Plain Layout $cSKIP ++; \end_layout \begin_layout Plain Layout print FILELOG "__skip__"; \end_layout \begin_layout Plain Layout } else \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard If the instruction is \begin_inset Quotes eld \end_inset no dogs allowed \begin_inset Quotes erd \end_inset we set this flag; otherwise we look for the other common Dogwagger commands \begin_inset Note Note status open \begin_layout Plain Layout : \color blue \begin_inset ERT status open \begin_layout Plain Layout dependsOn \end_layout \end_inset \color inherit , \color blue \begin_inset ERT status open \begin_layout Plain Layout myName \end_layout \end_inset \color inherit , \color blue \begin_inset ERT status open \begin_layout Plain Layout oneLine \end_layout \end_inset \color inherit , and \color blue \begin_inset ERT status open \begin_layout Plain Layout sectionTitle \end_layout \end_inset \color inherit , and \size small \color blue \begin_inset ERT status open \begin_layout Plain Layout noSections \end_layout \end_inset \end_layout \end_inset as follows. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog:other commands (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout { $wagline = $_; # dogs are allowed ** \end_layout \begin_layout Plain Layout if (/^(.*)dependsOn= \backslash `(.+?) \backslash '(.*)$/) \end_layout \begin_layout Plain Layout { $depOn = $2; \end_layout \begin_layout Plain Layout $_ = "$1$3"; \end_layout \begin_layout Plain Layout print FILELOG "dependencies <$depOn>; "; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout if (/^(.*)myName= \backslash `(.+?) \backslash '(.*)$/) \end_layout \begin_layout Plain Layout { $myNam = $2; \end_layout \begin_layout Plain Layout $_ = "$1$3"; \end_layout \begin_layout Plain Layout print FILELOG "name=$myNam; "; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout if (/^(.*)oneLine= \backslash `yes \backslash '(.*)$/) \end_layout \begin_layout Plain Layout { $chomper = 1; # turn on! \end_layout \begin_layout Plain Layout $_ = "$1$2"; \end_layout \begin_layout Plain Layout print FILELOG "(chomp) "; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout if (/^(.*)sectionTitle= \backslash `(.+?) \backslash '(.*)$/) \end_layout \begin_layout Plain Layout { $SECTIONTITLE = $2; \end_layout \begin_layout Plain Layout $_ = "$1$3"; \end_layout \begin_layout Plain Layout print FILELOG "title<$SECTIONTITLE> "; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout if ( ! ( /newTarget=/ ) # provided NOT new file [4.0.2] \end_layout \begin_layout Plain Layout && ( /^(.*)noSections= \backslash `(.+?) \backslash '(.*)$/ ) \end_layout \begin_layout Plain Layout ) { print FILELOG "nosections=$2 "; \end_layout \begin_layout Plain Layout if ($2 eq 'yes') \end_layout \begin_layout Plain Layout { $nosections=1; \end_layout \begin_layout Plain Layout $_ = "$1$3"; \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout elsif ($2 eq 'no') \end_layout \begin_layout Plain Layout { $nosections=0; \end_layout \begin_layout Plain Layout $_ = "$1$3"; \end_layout \begin_layout Plain Layout }; # if neither yes nor no, ignore! \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard The \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout noSections \end_layout \end_inset \family default \color inherit test allows you to turn section headers on or off at will, so we need to accommodate not just the `yes' option but also the `no' option. Specifying something other than `yes' or `no' will force an error, as $_ is then not updated, and Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sub:An-erroneous-Dogwagger-command" \end_inset will catch this below. Although turning on \color blue \family sans \begin_inset ERT status open \begin_layout Plain Layout noSections \end_layout \end_inset \family default \size small \size default \color inherit (disabling printing of section headers) is logically incompatible with \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout sectionTitle \end_layout \end_inset \color inherit , \family default we don't check for this minor conflict. \end_layout \begin_layout Standard \begin_inset Note Note status open \begin_layout Plain Layout ## section replaced by ReadTargetParams, 2011-12-18. \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Subsubsection A new file \end_layout \begin_layout Standard The final legal Dogwagger instruction is \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout newTarget \end_layout \end_inset \family default \color inherit . The code is here made a bit more complex because I need to accommodate the possibility that \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout newTarget \end_layout \end_inset \family default \color inherit is a uuencoded file. (I've again decreased the indentation, a reflection of the baroque complexity of WagTheDog). \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: a new file (Section $[SECTION])' \end_layout \begin_layout Plain Layout { \backslash footnotesize \backslash begin{verbatim} \end_layout \begin_layout Plain Layout if (/^(.*)newTarget= \backslash `(.+?) \backslash '(.*)$/) # newtarget * \end_layout \begin_layout Plain Layout { $cFILES ++; # bump file count \end_layout \begin_layout Plain Layout ##################deeply indented section####################### \end_layout \begin_layout Plain Layout $RETAINTARGETLINE = "$1$3"; # keep all other specifications \end_layout \begin_layout Plain Layout $DOGFILE = $2; # get name of new file \end_layout \begin_layout Plain Layout if ($DOGFILE =~ /^uudecode$/) \end_layout \begin_layout Plain Layout # if uudecoding do NOT terminate current file! \end_layout \begin_layout Plain Layout { my ($ufile, $umode, $uout) = Uudecode(); \end_layout \begin_layout Plain Layout if (length $ufile > 0) \end_layout \begin_layout Plain Layout { &PrintLogLine ("uudecoding <$ufile> mode $umode"); \end_layout \begin_layout Plain Layout my ($E2) = 0; \end_layout \begin_layout Plain Layout if (-e $ufile) { $cOUST++; }; # bump overwrite count! \end_layout \begin_layout Plain Layout open UFILE, ">$ufile" \end_layout \begin_layout Plain Layout or $E2 = &GlobalError("Uudecode failed <$ufile>"); \end_layout \begin_layout Plain Layout if (! $E2) \end_layout \begin_layout Plain Layout { binmode UFILE; # NB otherwise MSDOS stuffup! \end_layout \begin_layout Plain Layout print UFILE $uout; # IGNORE UNIX mode in $umode. \end_layout \begin_layout Plain Layout close UFILE; \end_layout \begin_layout Plain Layout }; }; \end_layout \begin_layout Plain Layout \backslash end{verbatim}} \end_layout \end_inset \end_layout \begin_layout Standard The above code handles the case where the target name is precisely `uudecode', decoding and writing the uuencoded file (and increasing the overwrite count $cOUST if the file exists). Otherwise close the current target file (Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sub:Close-target-file" \end_inset ), read new target parameters (ReadTargetParams, Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sub:Read-target-file-parameters" \end_inset ), and open a new file (See Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sub:Open-the-target" \end_inset ). \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: close file (Section $[SECTION])' \end_layout \begin_layout Plain Layout { \backslash footnotesize \backslash begin{verbatim} \end_layout \begin_layout Plain Layout } else # close current, open new! \end_layout \begin_layout Plain Layout { &CloseDogFile($startComment, $eft, $endComment, $notail); \end_layout \begin_layout Plain Layout ($startComment, $nowarn, $MANDATORY, $sft, \end_layout \begin_layout Plain Layout $eft, $endComment, $nohead, $nosections, $notail) = \end_layout \begin_layout Plain Layout &ReadTargetParams($RETAINTARGETLINE, $startComment, \end_layout \begin_layout Plain Layout $endComment); \end_layout \begin_layout Plain Layout print FILELOG (" \backslash n Comment format now \backslash "$startComment" \end_layout \begin_layout Plain Layout . "foo$endComment \backslash ""); \end_layout \begin_layout Plain Layout if (! OpenTargetFile($DOGFILE, $startComment, $fido, \end_layout \begin_layout Plain Layout $nowarn, $sft, $endComment, $nohead)) \end_layout \begin_layout Plain Layout # nohead.. added 2011-12-18 \end_layout \begin_layout Plain Layout { return ("Could not open target: <$DOGFILE>"); #fail \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout #################end deeply indented section#################### \end_layout \begin_layout Plain Layout \backslash end{verbatim}} \end_layout \end_inset \end_layout \begin_layout Subsubsection An erroneous Dogwagger command \begin_inset CommandInset label LatexCommand label name "sub:An-erroneous-Dogwagger-command" \end_inset \end_layout \begin_layout Standard That's the end of the deeply indented section. Next, the case where the command was not \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout newTarget \end_layout \end_inset \family default \color inherit . As we've examined all the valid options, any residual command must be in error: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: bad command (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout } else # end newtarget * \end_layout \begin_layout Plain Layout { if ( /( \backslash w+= \backslash `.+ \backslash ')/ ) # implies unknown command \end_layout \begin_layout Plain Layout { &Caution("*Warning* LINE $LINECOUNT " \end_layout \begin_layout Plain Layout . "Unknown/duplicated " \end_layout \begin_layout Plain Layout . "Dogwagger command(s) <$1>"); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard Finally, if there are dependencies, we store these (StoreChild, Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sub:Store-array-of-lines" \end_inset ). \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: store child (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout if (length $depOn > 0) # if dependency \end_layout \begin_layout Plain Layout { if (! &StoreChild ($myNam, $depOn, $chomper)) # keep whole \end_layout \begin_layout Plain Layout { &Caution("WARNING: \backslash \end_layout \begin_layout Plain Layout Input file <$fido> terminated unexpectedly!"); \end_layout \begin_layout Plain Layout close FIDO; \end_layout \begin_layout Plain Layout close DOGFILE; \end_layout \begin_layout Plain Layout return ('Sudden INPUT failure'); #fail! \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout $myNam = ''; # cannot YET resolve (is a dependency). \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection Hot code \end_layout \begin_layout Standard The preceding code dealt with the case where were are not `hot'. If we \emph on are \emph default busy writing lines to output (are hot) we next check for the end of a \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+verbatim+ \end_layout \end_inset statement. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: hot code (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout } else # (MIDDLE OF OUTER INDENTED SECTION) \end_layout \begin_layout Plain Layout # ARE HOT (ARE WRITING): \end_layout \begin_layout Plain Layout { if ( /(.*) \backslash \backslash end \backslash {verbatim \backslash }/ ) # end verbatim? \end_layout \begin_layout Plain Layout { if ($OPTN) # OPTION still on? \end_layout \begin_layout Plain Layout { &Alert ( "Optional text not closed. See log!"); \end_layout \begin_layout Plain Layout &GlobalError(" \backslash n ERROR line $LINECOUNT: " \end_layout \begin_layout Plain Layout . "+OPTIONAL not closed"); \end_layout \begin_layout Plain Layout $OPTN = 0; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout $hotdata = $1; \end_layout \begin_layout Plain Layout print DOGFILE $hotdata; # last chunk. \end_layout \begin_layout Plain Layout print FILELOG " ... $LINECOUNT."; \end_layout \begin_layout Plain Layout if (length $myNam > 0) # if name defined \end_layout \begin_layout Plain Layout { $SECTION = &FixName($myNam, $startComment, \end_layout \begin_layout Plain Layout $SECTION, $endComment, \end_layout \begin_layout Plain Layout $nosections, $SECTIONTITLE); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout $ishot = 0; # turn off. \end_layout \begin_layout Plain Layout $chomper = 0; # back to default \end_layout \begin_layout Plain Layout $chomped = 0; # redundant. \end_layout \begin_layout Plain Layout $SECTIONTITLE = ''; \end_layout \begin_layout Plain Layout } else # end of "end verbatim". \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard If it is the end of a verbatim statement, we print the last bit of text just before the end. Then, if \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+myNam+ \end_layout \end_inset contains a name, we resolve all of the dependencies on that name using the function FixName (Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sub:Resolve-labelling-dependencies" \end_inset ). \end_layout \begin_layout Standard Otherwise (it's not the end of a verbatim statement) we check for the case where we are `chomping' lines (the \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout oneLine \end_layout \end_inset \family default \color inherit option forces multiple verbatim lines to be concatenated, removing all newline characters). \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: chomping? (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout # NOT end of verbatim. Are still hot. \end_layout \begin_layout Plain Layout { if ($chomped) # Already chomped? \end_layout \begin_layout Plain Layout { / *(.*)/; # remove leading spaces \end_layout \begin_layout Plain Layout $_ = $1; # (even allow null line) \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout if ($chomper) # IF line must be chomped \end_layout \begin_layout Plain Layout { print FILELOG '+'; # Amended 2011-12-18 \end_layout \begin_layout Plain Layout $chomped = 1; # signal we've just chomped. \end_layout \begin_layout Plain Layout } else # UNLESS chomping, \end_layout \begin_layout Plain Layout { $_ = "$_$NEWLINE"; # restore a default newline! \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard We also check for +OPTIONAL code, only written if we specified \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+include=`everything'+ \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: OPTIONAL? (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout if ( /^ \backslash s* \backslash +OPTIONAL(.*)$/) \end_layout \begin_layout Plain Layout { $OPTN = 1; \end_layout \begin_layout Plain Layout $_ = ""; \end_layout \begin_layout Plain Layout if (length $1 > 0) \end_layout \begin_layout Plain Layout { &Caution("Warning LINE $LINECOUNT. " \end_layout \begin_layout Plain Layout . "Extra +OPTIONAL text"); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout if ( /^ \backslash s*-OPTIONAL(.+)$/) \end_layout \begin_layout Plain Layout { $OPTN = 0; \end_layout \begin_layout Plain Layout $_ = ""; \end_layout \begin_layout Plain Layout if (length $1 > 0) \end_layout \begin_layout Plain Layout { &Caution("Warning LINE $LINECOUNT. " \end_layout \begin_layout Plain Layout . "Extra-OPTIONAL text"); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout if ($MANDATORY || ! $OPTN) # unless optional is active \end_layout \begin_layout Plain Layout { print DOGFILE $_; # write to output \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout }; # end "end verbatim" \end_layout \begin_layout Plain Layout }; # END 'ARE HOT'. \end_layout \begin_layout Plain Layout ### END OUTER INDENTED SECTION \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection Finish off \end_layout \begin_layout Standard We finish off our enormous \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+while+ \end_layout \end_inset statement, and close the source file. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` WagTheDog: done (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout }; # *** end defined \end_layout \begin_layout Plain Layout }; # end of enormous while stmt. \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout close FIDO; \end_layout \begin_layout Plain Layout print FILELOG " \backslash n Line $LINECOUNT: "; # preliminary to closing \end_layout \begin_layout Plain Layout &CloseDogFile($startComment, $eft, $endComment, $notail); \end_layout \begin_layout Plain Layout return(0); \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard Returning zero from WagTheDog signals success. (All statements of failure return a string that describes how things failed). We write the current line number to the log file so that this last line number is logged. \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section Reading the header \begin_inset CommandInset label LatexCommand label name "sec:Reading-the-header" \end_inset \end_layout \begin_layout Standard As discussed in the introductory section, we must accommodate the various header line options. We obtain the version, fileTarget and newLine values in the following routine: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Read a header (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub ReadHeader \end_layout \begin_layout Plain Layout { my ($hotline); \end_layout \begin_layout Plain Layout ($hotline) = @_; \end_layout \begin_layout Plain Layout my ($ver, $target, $comment, $nowarn, $mandatory, \end_layout \begin_layout Plain Layout $sft, $eft, $endComment, \end_layout \begin_layout Plain Layout $nohead, $nosections, $notail); # $nohead 2011-12-18 \end_layout \begin_layout Plain Layout $ver = 0; \end_layout \begin_layout Plain Layout $target = ''; \end_layout \begin_layout Plain Layout $comment = '#'; # aka startComment \end_layout \begin_layout Plain Layout $nowarn = 0; \end_layout \begin_layout Plain Layout $mandatory = 0; \end_layout \begin_layout Plain Layout $sft = ''; \end_layout \begin_layout Plain Layout $eft = ''; \end_layout \begin_layout Plain Layout $endComment = ''; \end_layout \begin_layout Plain Layout $nohead = 0; # default write head \end_layout \begin_layout Plain Layout $nosections = 0; # and section \end_layout \begin_layout Plain Layout $notail = 0; \end_layout \begin_layout Plain Layout if ( $hotline !~ /^(.*)version= \backslash `( \backslash d+ \backslash . \backslash d+ \backslash . \backslash d+) \backslash '(.*)$/ ) \end_layout \begin_layout Plain Layout { &Caution ("Missing/defective version number"); \end_layout \begin_layout Plain Layout return (0,0,0,0, 0,0,0,0, 0,0,0); #fail \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout $ver = $2; \end_layout \begin_layout Plain Layout $hotline = "$1$3"; \end_layout \begin_layout Plain Layout if ( $hotline !~ /^(.*)fileTarget= \backslash `(.+?) \backslash '(.*)$/ ) \end_layout \begin_layout Plain Layout { &Caution ("Missing/defective target filename"); \end_layout \begin_layout Plain Layout return (0,0,0,0, 0,0,0,0, 0,0,0); #fail \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout $target = $2; \end_layout \begin_layout Plain Layout $hotline = "$1$3"; \end_layout \begin_layout Plain Layout if ($hotline =~ /^(.*)newLine= \backslash `(.+?) \backslash '(.*)$/ ) \end_layout \begin_layout Plain Layout { $NEWLINE = $2; \end_layout \begin_layout Plain Layout $hotline = "$1$3"; \end_layout \begin_layout Plain Layout $NEWLINE =~ s/ \backslash \backslash n/ \backslash n/g; # \end_layout \begin_layout Plain Layout $NEWLINE =~ s/ \backslash \backslash r/ \backslash r/g; # replace \backslash n =r \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout ($comment, $nowarn, $mandatory, $sft, $eft, \end_layout \begin_layout Plain Layout $endComment, $nohead, $nosections, $notail) = \end_layout \begin_layout Plain Layout &ReadTargetParams($hotline, $comment, $endComment); \end_layout \begin_layout Plain Layout return ($ver, $target, $comment, $nowarn, $mandatory, \end_layout \begin_layout Plain Layout $sft, $eft, $endComment, \end_layout \begin_layout Plain Layout $nohead, $nosections, $notail); } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard Other parameters are obtained by ReadTargetParams (§ \begin_inset CommandInset ref LatexCommand ref reference "sub:Read-target-file-parameters" \end_inset ). \end_layout \begin_layout Subsection Read target file parameters \begin_inset CommandInset label LatexCommand label name "sub:Read-target-file-parameters" \end_inset \end_layout \begin_layout Standard We read in parameters that are directly related to file creation. These parameters do \emph on not \emph default include the version number and the \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout fileTarget \end_layout \end_inset \family default \color inherit parameter. In version 2.1 we added the option to specify the very first few characters of the file using the \emph on startFile \emph default option. This is useful for HTML and PHP. See also the corresponding \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout endFile \end_layout \end_inset \family default \color inherit option for terminating the last chunk of a file. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Read target parameters (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub ReadTargetParams \end_layout \begin_layout Plain Layout { my ($topline, $comment, $endComment); \end_layout \begin_layout Plain Layout ($topline, $comment, $endComment) = @_; \end_layout \begin_layout Plain Layout my ($nowarn, $mandatory, $sft, $eft, $endComment, \end_layout \begin_layout Plain Layout $nohead, $nosections, $notail); # $nohead.. added 2011-12-18 \end_layout \begin_layout Plain Layout my ($alterSC, $alterEC); \end_layout \begin_layout Plain Layout $nowarn = 0; \end_layout \begin_layout Plain Layout $mandatory = 0; \end_layout \begin_layout Plain Layout $sft = ''; \end_layout \begin_layout Plain Layout $eft = ''; \end_layout \begin_layout Plain Layout $nohead = 0; # default write head \end_layout \begin_layout Plain Layout $nosections= 0; # and section \end_layout \begin_layout Plain Layout $notail = 0; \end_layout \begin_layout Plain Layout $alterSC = 0; # ON if alter startComment \end_layout \begin_layout Plain Layout $alterEC = 0; # on if alter endComment \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout if ($topline =~ /^(.*)include= \backslash `everything \backslash '(.*)$/) \end_layout \begin_layout Plain Layout { $mandatory = 1; \end_layout \begin_layout Plain Layout $topline = "$1$2"; \end_layout \begin_layout Plain Layout print FILELOG "include ALL "; }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout if ($topline =~ /^(.*)startComment= \backslash `(.+?) \backslash '(.*)$/) \end_layout \begin_layout Plain Layout { $comment = $2; # new startComment \end_layout \begin_layout Plain Layout $topline = "$1$3"; \end_layout \begin_layout Plain Layout $alterSC = 1; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout if ($topline =~ /^(.*)newComment= \backslash `(.+?) \backslash '(.*)$/) # obsolete. \end_layout \begin_layout Plain Layout { &Caution( "Minor warning: newComment is deprecated " \end_layout \begin_layout Plain Layout . "(LINE $LINECOUNT). Use startComment." ); \end_layout \begin_layout Plain Layout $comment = $2; \end_layout \begin_layout Plain Layout $topline = "$1$3"; \end_layout \begin_layout Plain Layout $alterSC = 1; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout if ($topline =~ /^(.*)endComment= \backslash `(.*?) \backslash '(.*)$/) \end_layout \begin_layout Plain Layout { $endComment = $2; \end_layout \begin_layout Plain Layout $topline = "$1$3"; \end_layout \begin_layout Plain Layout $alterEC = 1; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard Because the comment format is carried over, there's a potential problem if an old format has an \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout endComment \end_layout \end_inset \family default \color inherit (e.g. \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+-->+ \end_layout \end_inset ) and we change the \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout startComment \end_layout \end_inset \family default \color inherit alone. We thus \emph on reset \family sans \emph default \color blue \begin_inset ERT status open \begin_layout Plain Layout endComment \end_layout \end_inset \family default \color inherit if we've altered \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout startComment \end_layout \end_inset \family default \color inherit but not \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout endComment \end_layout \end_inset \family default \color inherit : \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` start v end comment (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout if ($alterSC && ! $alterEC) # if only alter startComment \end_layout \begin_layout Plain Layout { $endComment = ''; # force endComment to default. \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard The remaining options are straightforward: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % DogWagger sectionTitle=` headline options (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout if ($topline =~ /^(.*)noWarn= \backslash `yes \backslash '(.*)$/) \end_layout \begin_layout Plain Layout { $nowarn = 1; \end_layout \begin_layout Plain Layout $topline = "$1$2"; \end_layout \begin_layout Plain Layout print FILELOG "warn is OFF; " }; \end_layout \begin_layout Plain Layout if ($topline =~ /^(.*)startFile= \backslash `(.*?) \backslash '(.*)$/) # ver 2.1 \end_layout \begin_layout Plain Layout { $sft = $2; \end_layout \begin_layout Plain Layout $topline = "$1$3"; \end_layout \begin_layout Plain Layout print FILELOG "start code {$sft}; "; \end_layout \begin_layout Plain Layout $sft =~ s/ \backslash \backslash n/$NEWLINE/mg; # CR's !! \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout if ($topline =~ /^(.*)endFile= \backslash `(.*?) \backslash '(.*)$/) # ver 2.1 \end_layout \begin_layout Plain Layout { $eft = $2; \end_layout \begin_layout Plain Layout $topline = "$1$3"; \end_layout \begin_layout Plain Layout print FILELOG "end code {$eft}; "; \end_layout \begin_layout Plain Layout $eft =~ s/ \backslash \backslash n/$NEWLINE/mg; # CR's !! \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout if ($topline =~ /^(.*)noHeader= \backslash `yes \backslash '(.*)$/ ) # 2011-12-18 \end_layout \begin_layout Plain Layout { $nohead=1; \end_layout \begin_layout Plain Layout $topline = "$1$2"; \end_layout \begin_layout Plain Layout print FILELOG "NO header; " }; \end_layout \begin_layout Plain Layout if ($topline =~ /^(.*)noSections= \backslash `yes \backslash '(.*)$/ ) \end_layout \begin_layout Plain Layout { $nosections=1; \end_layout \begin_layout Plain Layout $topline = "$1$2"; \end_layout \begin_layout Plain Layout print FILELOG "NO sections; " }; \end_layout \begin_layout Plain Layout if ($topline =~ /^(.*)noTail= \backslash `yes \backslash '(.*)$/ ) \end_layout \begin_layout Plain Layout { $notail=1; \end_layout \begin_layout Plain Layout $topline = "$1$2"; \end_layout \begin_layout Plain Layout print FILELOG "NO tail; " }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout if ($topline =~ /( \backslash w+= \backslash `.+ \backslash ')/ ) \end_layout \begin_layout Plain Layout { &Caution("*Warning* LINE $LINECOUNT Unknown/duplicated " \end_layout \begin_layout Plain Layout . "Dogwagger NEWFILE command(s) <$1>"); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout return ($comment, $nowarn, $mandatory, \end_layout \begin_layout Plain Layout $sft, $eft, $endComment, \end_layout \begin_layout Plain Layout $nohead, $nosections, $notail); } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section Miscellaneous routines \end_layout \begin_layout Standard The following are trivial: \end_layout \begin_layout Subsection Confirm an action \end_layout \begin_layout Standard Get console input (confirmation, i.e. `y'): \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Confirm (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub Confirm \end_layout \begin_layout Plain Layout { my ($msg); \end_layout \begin_layout Plain Layout ($msg) = @_; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout print " \backslash n$msg"; \end_layout \begin_layout Plain Layout my($ans); \end_layout \begin_layout Plain Layout $ans = ; # get stdin \end_layout \begin_layout Plain Layout if ($ans =~ /^y/i ) \end_layout \begin_layout Plain Layout { return(1); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout return (0); } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection Alert \end_layout \begin_layout Standard Alert the user with a warning. Do not alter $_. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Alert (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub Alert \end_layout \begin_layout Plain Layout { my ($msg); \end_layout \begin_layout Plain Layout ($msg) = @_; \end_layout \begin_layout Plain Layout print "$msg"; } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection ChompLine \begin_inset CommandInset label LatexCommand label name "sub:ChompLine" \end_inset \end_layout \begin_layout Standard Remove CR/LF characters from the start/end of a line: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout %DogWagger sectionTitle=` Chomp line (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub ChompLine \end_layout \begin_layout Plain Layout { my ($line); \end_layout \begin_layout Plain Layout ($line) = @_; \end_layout \begin_layout Plain Layout if ( $line =~ /([^ \backslash n \backslash r]*)/ms ) \end_layout \begin_layout Plain Layout { $line = $1; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout return($line); } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection Determine newline character(s) \end_layout \begin_layout Standard Given a sample line, find out the codes used eg 0D or 0D0A. Unescape is below (§ \begin_inset CommandInset ref LatexCommand ref reference "sub:Unescape" \end_inset ). \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout %DogWagger sectionTitle=` Get newline characters (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub GetNewLine \end_layout \begin_layout Plain Layout { my ($line); \end_layout \begin_layout Plain Layout ($line) = @_; \end_layout \begin_layout Plain Layout if ( $line =~ /[^ \backslash n \backslash r]*([ \backslash n \backslash r]+)$/ms ) \end_layout \begin_layout Plain Layout { my($nl) = $1; \end_layout \begin_layout Plain Layout $_ = &Unescape($1); \end_layout \begin_layout Plain Layout print FILELOG " \backslash n newline is <$_> "; \end_layout \begin_layout Plain Layout return($nl); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout print FILELOG " \backslash n Resorting to newline default."; \end_layout \begin_layout Plain Layout return($DEFAULTNEWLINE); } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection Caution --- Alert with print \end_layout \begin_layout Standard `Caution' always generates an alert. This code should not alter $_. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Caution (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub Caution \end_layout \begin_layout Plain Layout { my ($msg); \end_layout \begin_layout Plain Layout ($msg) = @_; \end_layout \begin_layout Plain Layout print FILELOG " \backslash n$msg"; # must prepend newline. \end_layout \begin_layout Plain Layout &Alert(" \backslash n$msg"); } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection Read the time \begin_inset CommandInset label LatexCommand label name "sub:Read-the-time" \end_inset \end_layout \begin_layout Standard This is the local machine time. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Get local time (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub GetLocalTime \end_layout \begin_layout Plain Layout { my ($sec, $min, $hour, $mday, $mon, \end_layout \begin_layout Plain Layout $year, $wday, $yday, $isdst); \end_layout \begin_layout Plain Layout ($sec, $min, $hour, $mday, $mon, \end_layout \begin_layout Plain Layout $year, $wday, $yday, $isdst) = localtime(time); \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout $year += 1900; #fix y2k. \end_layout \begin_layout Plain Layout $mon ++; #january is zero! \end_layout \begin_layout Plain Layout return ("$year-$mon-$mday $hour:$min:$sec"); } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection An error-related hack \end_layout \begin_layout Standard Clumsy. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` global error (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub GlobalError \end_layout \begin_layout Plain Layout { my ($msg); \end_layout \begin_layout Plain Layout ($msg) = @_; \end_layout \begin_layout Plain Layout print FILELOG " \backslash n$msg"; \end_layout \begin_layout Plain Layout $ERRCOUNT ++; # bump error count \end_layout \begin_layout Plain Layout return($msg); \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection Pretty up codes \begin_inset CommandInset label LatexCommand label name "sub:Unescape" \end_inset \end_layout \begin_layout Standard We look for \backslash r and \backslash n (carriage return, line feed) and substitute text representations: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Unescape (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub Unescape \end_layout \begin_layout Plain Layout { my ($t); \end_layout \begin_layout Plain Layout ($t) = @_; \end_layout \begin_layout Plain Layout $t =~ s/ \backslash n/ \backslash \backslash n/ms; \end_layout \begin_layout Plain Layout $t =~ s/ \backslash r/ \backslash \backslash r/ms; \end_layout \begin_layout Plain Layout return($t); \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section Deferred code \end_layout \begin_layout Standard The following routines allow you to write code that is deferred until the code it depends on has been resolved. Do not assume that if A and B both depend on C, that A or B will be resolved in any particular order, unless you explicitly state that A depends on B, or vice versa! \end_layout \begin_layout Subsection Store array of lines \begin_inset CommandInset label LatexCommand label name "sub:Store-array-of-lines" \end_inset \end_layout \begin_layout Standard Here we keep `child' (dependent) lines in an array, to be resolved later when all dependencies are met. The index of the topmost child is given by \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+$#CHILDREN+ \end_layout \end_inset . The list of dependencies contains elements separated by commas, and there are starting and terminal commas to facilitate matching. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Store child (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub StoreChild \end_layout \begin_layout Plain Layout { my ($pendingName, $dependencies, $chomper); \end_layout \begin_layout Plain Layout ($pendingName, $dependencies, $chomper) = @_; \end_layout \begin_layout Plain Layout my ($idx, $child); \end_layout \begin_layout Plain Layout $idx = 1+$#CHILDREN; \end_layout \begin_layout Plain Layout print FILELOG "Keeping child[$idx]."; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout $_ = ; # first line *must* be begin verbatim \end_layout \begin_layout Plain Layout # what if this is not defined?? (check me) \end_layout \begin_layout Plain Layout $LINECOUNT ++; \end_layout \begin_layout Plain Layout $_ = &ChompLine($_); \end_layout \begin_layout Plain Layout if ($chomper) # IF line must be chomped \end_layout \begin_layout Plain Layout { print FILELOG '/'; # \end_layout \begin_layout Plain Layout } else # UNLESS chomping, \end_layout \begin_layout Plain Layout { $_ = "$_$NEWLINE"; # restore a default newline! \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard The above allows a \color blue \family sans oneLine= \begin_inset ERT status open \begin_layout Plain Layout \backslash textrm{ \backslash large`} \end_layout \end_inset true' \family default \color inherit statement to affect a deferred block. We now make sure that the line begins with a new \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+verbatim+ \end_layout \end_inset statement. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` ensure verbatim (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout if ( / \backslash \backslash begin \backslash {verbatim \backslash }(.*)/ ) \end_layout \begin_layout Plain Layout { $child = $1; # keep rest of line \end_layout \begin_layout Plain Layout } else \end_layout \begin_layout Plain Layout { print FILELOG " \backslash n*ERROR at line $LINECOUNT:" \end_layout \begin_layout Plain Layout . " no verbatim stmt on 1st child line!"; \end_layout \begin_layout Plain Layout $ERRCOUNT ++; # bump error \end_layout \begin_layout Plain Layout print FILELOG "<$ERRCOUNT!>"; \end_layout \begin_layout Plain Layout print FILELOG "<$_>"; \end_layout \begin_layout Plain Layout return 1; # not fatal, per se. \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard Next, store the name of the pending section, and its dependencies, all at the top of the current (global) lists. The actual text is stored in \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+$child+ \end_layout \end_inset . See how the dependencies list has a leading comma. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` dependencies (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout $DEPENDENCIES[$idx] = ",$dependencies,"; \end_layout \begin_layout Plain Layout $PENDINGNAME[$idx] = $pendingName; \end_layout \begin_layout Plain Layout $CHILDREN[$idx] = ''; # default nothing \end_layout \begin_layout Plain Layout my($ok) =1; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard We sequentially read in lines until end-of-file (an error), or the verbatim statement ends. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` sequential read (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout while($ok) \end_layout \begin_layout Plain Layout { $_ = ; \end_layout \begin_layout Plain Layout if (! defined) \end_layout \begin_layout Plain Layout { return 0; # fail \end_layout \begin_layout Plain Layout } else \end_layout \begin_layout Plain Layout { $_ = &ChompLine($_); \end_layout \begin_layout Plain Layout $LINECOUNT ++; \end_layout \begin_layout Plain Layout if ($chomper) # IF line must be chomped \end_layout \begin_layout Plain Layout { print FILELOG '/'; \end_layout \begin_layout Plain Layout } else # UNLESS chomping, \end_layout \begin_layout Plain Layout { $_ = "$_$NEWLINE"; # restore a default newline! \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout if ( /(.*) \backslash \backslash end \backslash {verbatim \backslash }/ ) \end_layout \begin_layout Plain Layout { $ok = 0; \end_layout \begin_layout Plain Layout $child = "$child$1"; # append last section \end_layout \begin_layout Plain Layout } else \end_layout \begin_layout Plain Layout { $child = "$child$_"; # concatenate. \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout $CHILDREN[$idx] = $child; # store away lines to be printed \end_layout \begin_layout Plain Layout return 1; \end_layout \begin_layout Plain Layout } # success! \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection Resolve labelling dependencies \begin_inset CommandInset label LatexCommand label name "sub:Resolve-labelling-dependencies" \end_inset \end_layout \begin_layout Standard FixName walks through all dependencies, resolves them (where relevant), and on resolution, writes the relevant child code to output. (A `child' is a section which depends on other sections, and must not be written before these sections have been identified and written). \end_layout \begin_layout Standard The arguments submitted are the name to be resolved, the codes for starting and ending a comment (c, ec), whether section headers will be written (nosectio ns), and the \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+$SECTION+ \end_layout \end_inset number. Note that the last-mentioned will be amended and returned. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Fix name (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout sub FixName \end_layout \begin_layout Plain Layout { my ($fname, $c, $SECTION, $ec, $nosections, $SECTIONTITLE); \end_layout \begin_layout Plain Layout ($fname, $c, $SECTION, $ec, $nosections, $SECTIONTITLE) = @_; \end_layout \begin_layout Plain Layout # nosections added 2011-12-18 \end_layout \begin_layout Plain Layout my ($morenames) = ",$fname,"; \end_layout \begin_layout Plain Layout my ($idx); \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard We now enter a while loop that takes the `name to be resolved' off \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+morenames+ \end_layout \end_inset and then enters an inner \emph on while \emph default loop that examines each pending name to see whether it's dependent on the name to be resolved. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` fixname while loop (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout while ( $morenames =~ /^(.*,)(.+),$/ ) # split off last name \end_layout \begin_layout Plain Layout { $fname = $2; \end_layout \begin_layout Plain Layout $morenames = $1; \end_layout \begin_layout Plain Layout $idx = $#CHILDREN; \end_layout \begin_layout Plain Layout while ($idx > -1 ) # for each child entry \end_layout \begin_layout Plain Layout { if ($DEPENDENCIES[$idx] =~ /(.*,)$fname,(.*)/ ) \end_layout \begin_layout Plain Layout { $_ = "$1$2"; # if name in list, clip \end_layout \begin_layout Plain Layout print FILELOG " (child[$idx] now has <$fname>) "; \end_layout \begin_layout Plain Layout $DEPENDENCIES[$idx] = $_; # rewrite \end_layout \begin_layout Plain Layout if ( /^,$/ ) # if all resolved \end_layout \begin_layout Plain Layout { print FILELOG "WRITING child[$idx] "; \end_layout \begin_layout Plain Layout $SECTION = &PrintSectionHeader($c, $SECTION, \end_layout \begin_layout Plain Layout $ec, $nosections, \end_layout \begin_layout Plain Layout $SECTIONTITLE); \end_layout \begin_layout Plain Layout print DOGFILE $CHILDREN[$idx]; \end_layout \begin_layout Plain Layout $CHILDREN[$idx] = ''; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard Once we've resolved this dependency, we realise that other files may in turn be dependent on the child that has been resolved. We get the name of \emph on this \emph default child off \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+@PENDINGNAME+ \end_layout \end_inset and add it to \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+$morenames+ \end_layout \end_inset . \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` and repeat (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout # ....WAIT! this child may have dependencies! \end_layout \begin_layout Plain Layout if (length $PENDINGNAME[$idx] > 0) # if so ... \end_layout \begin_layout Plain Layout { $morenames = \end_layout \begin_layout Plain Layout "$morenames$PENDINGNAME[$idx],"; \end_layout \begin_layout Plain Layout # add name of resolved child! \end_layout \begin_layout Plain Layout $PENDINGNAME[$idx] = '';# clear me! \end_layout \begin_layout Plain Layout }; }; }; \end_layout \begin_layout Plain Layout $idx --; # move to preceding child \end_layout \begin_layout Plain Layout }; # all children done. \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout return $SECTION; } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard The above explains why we \emph on must \emph default work backwards through \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+@DEPENDENCIES+ \end_layout \end_inset . Earlier entries may depend on later ones, but later ones will have been resolved at entry. It's therefore wrong to start \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+$idx+ \end_layout \end_inset at zero and count up. \end_layout \begin_layout Subsection Check for unresolved dependencies \end_layout \begin_layout Standard At the end, we have to make sure that all dependencies have been resolved, or signal an error. Errors are also written to the log. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Check unresolved dependencies (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub CheckUnresolved \end_layout \begin_layout Plain Layout { my($idx); \end_layout \begin_layout Plain Layout $idx = $#CHILDREN; \end_layout \begin_layout Plain Layout my ($errcnt); \end_layout \begin_layout Plain Layout $errcnt = 0; \end_layout \begin_layout Plain Layout while ($idx > -1) \end_layout \begin_layout Plain Layout { \end_layout \begin_layout Plain Layout if (length $CHILDREN[$idx] > 0) \end_layout \begin_layout Plain Layout { print FILELOG " \backslash n \backslash n *** ERROR *** " \end_layout \begin_layout Plain Layout . " \backslash n \backslash n Unresolved code: \backslash n "; \end_layout \begin_layout Plain Layout print FILELOG "Dependencies: <$DEPENDENCIES[$idx]> \backslash n"; \end_layout \begin_layout Plain Layout print FILELOG "Name: <$PENDINGNAME[$idx]> \backslash n" \end_layout \begin_layout Plain Layout . " Code ends> \backslash n \backslash n"; \end_layout \begin_layout Plain Layout $errcnt++; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout $idx --; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout return $errcnt; } # number of errors, 0=ok. \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section Handle multiple files \end_layout \begin_layout Standard This section is a consequence of Dogwagger's \begin_inset Note Note status open \begin_layout Plain Layout version 2 \end_layout \end_inset ability to generate multiple files from a single .TEX source. We chose the simple option of closing the first file and then opening and writing the next one, rather than having multiple dangling file handles. The sole exception to this rule is that if we are writing a UUdecoded binary file, we don't fiddle with the currently open file. \end_layout \begin_layout Subsection Open the target \begin_inset CommandInset label LatexCommand label name "sub:Open-the-target" \end_inset \end_layout \begin_layout Standard We open a target file, warning appropriately about overwrites. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` open target file (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub OpenTargetFile \end_layout \begin_layout Plain Layout { my ($DOGFILE, $c, $fido, $nowarn, $sft, $ec, \end_layout \begin_layout Plain Layout $nohead); # nohead added 2011-12-18 \end_layout \begin_layout Plain Layout ($DOGFILE, $c, $fido, $nowarn, $sft, $ec, \end_layout \begin_layout Plain Layout $nohead) = @_; \end_layout \begin_layout Plain Layout my($ok); \end_layout \begin_layout Plain Layout $TODAY = &GetLocalTime(); \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard We check that the file exists, and warn if overwriting, unless this warning has been suppressed: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` warn if overwriting (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout if (-e $DOGFILE) # if file exists \end_layout \begin_layout Plain Layout { if (! $nowarn) # and warning enabled \end_layout \begin_layout Plain Layout { if (! &Confirm ( \end_layout \begin_layout Plain Layout "Overwrite <$DOGFILE>? Are you sure?")) \end_layout \begin_layout Plain Layout { &Caution( "[NOT overwriting $DOGFILE]"); \end_layout \begin_layout Plain Layout $DOGFILE = 'JUNK.JUNK'; # write to junk file. \end_layout \begin_layout Plain Layout } else \end_layout \begin_layout Plain Layout { print FILELOG "[Overwriting $DOGFILE]"; \end_layout \begin_layout Plain Layout $cOUST++; # increase overwrite count. \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout } else \end_layout \begin_layout Plain Layout { $cOUST++; # increase overwrite count. \end_layout \begin_layout Plain Layout }; }; \end_layout \begin_layout Plain Layout my ($E3) = 0; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard If not overwriting, rather than simply discarding the text, we rather clumsily write to the file \emph on JUNK.JUNK \emph default . \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` discard file (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout open DOGFILE, ">$DOGFILE" or \end_layout \begin_layout Plain Layout $E3 = &GlobalError( \end_layout \begin_layout Plain Layout "Could not open target <$DOGFILE> :$!"); \end_layout \begin_layout Plain Layout if ($E3) \end_layout \begin_layout Plain Layout { return 0; \end_layout \begin_layout Plain Layout }; #fail \end_layout \begin_layout Plain Layout print FILELOG " \backslash n \backslash n==Opened target file <$DOGFILE> "; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard On opening the target file, we write several lines to this file ( \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+DOGFILE+ \end_layout \end_inset ) using the comment character(s) to rem out the lines. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` write headlines (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout print DOGFILE $sft; # very first text eg. for PHP. \end_layout \begin_layout Plain Layout # print EVEN IF noHead=`yes'. \end_layout \begin_layout Plain Layout if (! $nohead) # added 2011-12-18 \end_layout \begin_layout Plain Layout { print DOGFILE \end_layout \begin_layout Plain Layout "$c Generated by LaTeX DogWagger Version " . \end_layout \begin_layout Plain Layout "$MAJORVERSION.$MINORVERSION.$TV " \end_layout \begin_layout Plain Layout . "from file <$fido>$ec$NEWLINE"; \end_layout \begin_layout Plain Layout print DOGFILE "$c Date: [$TODAY] $ec$NEWLINE"; \end_layout \begin_layout Plain Layout print DOGFILE "$c Do NOT edit this file. " \end_layout \begin_layout Plain Layout . "Edit the LaTeX source!!$ec$NEWLINE"; \end_layout \begin_layout Plain Layout # \backslash n appended 2011-12-18. Is this wise? \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout return 1; # success \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard The \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout noHead=`yes' \end_layout \end_inset \family default \color inherit option allows us to suppress the Dogwagger header text, but if we specified \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout startFile \end_layout \end_inset \family default \color inherit text, it is still (of course) written. \end_layout \begin_layout Subsection Close target file \begin_inset CommandInset label LatexCommand label name "sub:Close-target-file" \end_inset \end_layout \begin_layout Standard Simply close the output file handle \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+DOGFILE+ \end_layout \end_inset . \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Close target file (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub CloseDogFile \end_layout \begin_layout Plain Layout { my ($c, $eft, $ec, $notail); \end_layout \begin_layout Plain Layout ($c, $eft, $ec, $notail) = @_; \end_layout \begin_layout Plain Layout my ($EC) = &CheckUnresolved(); \end_layout \begin_layout Plain Layout $ERRCOUNT += $EC; # global \end_layout \begin_layout Plain Layout if ($EC > 0) \end_layout \begin_layout Plain Layout { print FILELOG " \backslash nUnresolved errors <$EC>"; \end_layout \begin_layout Plain Layout if (! $notail) \end_layout \begin_layout Plain Layout { print DOGFILE \end_layout \begin_layout Plain Layout "$NEWLINE$NEWLINE$c -- WARNING:" \end_layout \begin_layout Plain Layout . " $EC errors. See log!$ec$NEWLINE"; \end_layout \begin_layout Plain Layout }; }; \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \begin_layout Plain Layout \end_layout \end_inset \end_layout \begin_layout Standard We can suppress writing of terminal (`tail') Dogwagger code, but the final code in \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+$eft+ \end_layout \end_inset is written (if it exists) regardless of the value in \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+$notail+ \end_layout \end_inset . \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` write tail (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout if (! $notail) \end_layout \begin_layout Plain Layout { print DOGFILE "$c -END OF FILE- $ec$NEWLINE"; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout print DOGFILE $eft; # Print EVEN if noTail=`yes' \end_layout \begin_layout Plain Layout close DOGFILE; \end_layout \begin_layout Plain Layout print FILELOG " FILE CLOSED== "; \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section Trivial amendments \end_layout \begin_layout Subsection Print a section header \begin_inset CommandInset label LatexCommand label name "sub:Print-a-section-header" \end_inset \end_layout \begin_layout Standard We now have the ability to label sections with pre-defined text (commented out). Remember that \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+$LINECOUNT+ \end_layout \end_inset is an ugly global. We submit the section count \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+$SECTION+ \end_layout \end_inset , and return this value incremented by one. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Print section header (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub PrintSectionHeader \end_layout \begin_layout Plain Layout { my($c, $SECTION, $ec, $nosections, $SECTIONTITLE); \end_layout \begin_layout Plain Layout # $nosections 2011-12-18 \end_layout \begin_layout Plain Layout ($c, $SECTION, $ec, $nosections, $SECTIONTITLE) = @_; \end_layout \begin_layout Plain Layout if (! $nosections) \end_layout \begin_layout Plain Layout { if (length $SECTIONTITLE > 0) \end_layout \begin_layout Plain Layout { $_ = $SECTIONTITLE; \end_layout \begin_layout Plain Layout if (/ \backslash $ \backslash [SECTION \backslash ]/) # if contains section count \end_layout \begin_layout Plain Layout { s/ \backslash $ \backslash [SECTION \backslash ]/$SECTION/; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout print DOGFILE "$NEWLINE$c$_$ec$NEWLINE"; \end_layout \begin_layout Plain Layout } else \end_layout \begin_layout Plain Layout { print DOGFILE "$NEWLINE$c -
" \end_layout \begin_layout Plain Layout . " - $ec$NEWLINE"; \end_layout \begin_layout Plain Layout }; }; \end_layout \begin_layout Plain Layout &PrintLogLine ("writing section [$SECTION]"); \end_layout \begin_layout Plain Layout $SECTION ++; \end_layout \begin_layout Plain Layout return $SECTION; \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard The above code also replaces the text \family sans \color blue \begin_inset ERT status open \begin_layout Plain Layout \backslash $[SECTION] \end_layout \end_inset \family default \color inherit (within the section header) with the actual section count. \end_layout \begin_layout Subsection Print LOG line \end_layout \begin_layout Standard We often print to the log with a line number, so let's formalise this: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Print log line (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub PrintLogLine \end_layout \begin_layout Plain Layout { my($t); \end_layout \begin_layout Plain Layout ($t) = @_; \end_layout \begin_layout Plain Layout print FILELOG " \backslash n line $LINECOUNT: $t"; \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Standard It makes code slightly more concise, at little cost. \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section Binary encoding and decoding \end_layout \begin_layout Standard Responding to the need to write binary code from our TEX source: \end_layout \begin_layout Subsection UUdecode \end_layout \begin_layout Standard We read the global file handle FIDO, mandating that the initial line is the `begin verbatim' line. The line immediately after this must contain the UUencoded header line. The subsidiary routine UUdecodeLine returns not only decoded text, but also an error code. If the error code is less than zero, an error has occurred; if the error code is zero, then the subsequent line \emph on must \emph default be an \color green \begin_inset ERT status open \begin_layout Plain Layout end \end_layout \end_inset \color inherit statement signalling the end of the UUencoded section! \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Uudecode (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub Uudecode \end_layout \begin_layout Plain Layout { my ($filename, $mode, @rslt); \end_layout \begin_layout Plain Layout my ($line, $decoded, $err); \end_layout \begin_layout Plain Layout $filename = ""; \end_layout \begin_layout Plain Layout $line = ; # this should be \backslash begin{verbatim} line: \end_layout \begin_layout Plain Layout $LINECOUNT ++; \end_layout \begin_layout Plain Layout if ($line !~ / \backslash \backslash begin \backslash {verbatim \backslash }/ ) \end_layout \begin_layout Plain Layout { &Alert ("Uudecode: no verbatim <$line>"); \end_layout \begin_layout Plain Layout return ("", "", ""); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout $line = ; # MUST be header! \end_layout \begin_layout Plain Layout $LINECOUNT ++; \end_layout \begin_layout Plain Layout $line = &ChompLine($line); \end_layout \begin_layout Plain Layout $line =~ /begin \backslash s+( \backslash d{3}) \backslash s+(.+)/; \end_layout \begin_layout Plain Layout if (! defined $1) \end_layout \begin_layout Plain Layout { # here write error! \end_layout \begin_layout Plain Layout &Alert ("Uudecode: bad first UU line <$line>"); \end_layout \begin_layout Plain Layout return ("", "", ""); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout $mode = $1; \end_layout \begin_layout Plain Layout $filename=$2; \end_layout \begin_layout Plain Layout $err = 1; # -ve will signal failure \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout while ( $line = ) \end_layout \begin_layout Plain Layout { # hmm what if extra 0xD ? \end_layout \begin_layout Plain Layout last if (! defined $line); # ?? \end_layout \begin_layout Plain Layout $LINECOUNT ++; \end_layout \begin_layout Plain Layout $line = &ChompLine($line); \end_layout \begin_layout Plain Layout last if ($line =~ /^end/); \end_layout \begin_layout Plain Layout if (! $err) # bad if err zero \end_layout \begin_layout Plain Layout { &Alert ("Uudecode: end stmt not seen!<$line>"); \end_layout \begin_layout Plain Layout last; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout ($decoded, $err) = UudecodeLine($line); \end_layout \begin_layout Plain Layout # nb if $err is zero, next line must be /^end/! \end_layout \begin_layout Plain Layout if ($err < 0) \end_layout \begin_layout Plain Layout { # here could write error! \end_layout \begin_layout Plain Layout if ($err == -1) \end_layout \begin_layout Plain Layout { $err = "Bad line"; \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout elsif ($err == -2) \end_layout \begin_layout Plain Layout { $err = "silly length($decoded)"; \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout elsif ($err == -3) \end_layout \begin_layout Plain Layout { $err = "lengths don't match($decoded)"; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout &Alert ("Uudecode: error $err in <$line>"); \end_layout \begin_layout Plain Layout last; # terminate \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout push @rslt, $decoded; \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout return ($filename, $mode, join("",@rslt)); \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \end_layout \end_inset \end_layout \begin_layout Subsection UUdecode line \end_layout \begin_layout Standard Here's the routine that actually does the business of UUdecoding. We've kept this very simple, based on publicly available code. \begin_inset Foot status open \begin_layout Plain Layout \begin_inset CommandInset href LatexCommand href name " http://search.cpan.org/src/ANDK/Convert-UU-0.52/lib/Convert/UU.pm" target " http://search.cpan.org/src/ANDK/Convert-UU-0.52/lib/Convert/UU.pm" \end_inset \end_layout \end_inset On most UNIX/Linux systems, UUencoding and decoding should be readily available , but for DOS uuencoding, try e.g. \begin_inset CommandInset href LatexCommand href name "this program." target "http://drn.digitalriver.com/product.php%5Bid%5D39753%5Bcid%5D2%5BSiteID%5Ddriverguide" \end_inset \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger sectionTitle=` Uudecode line (Section $[SECTION])' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout sub UudecodeLine \end_layout \begin_layout Plain Layout { my ($line) = @_; \end_layout \begin_layout Plain Layout my ($charlen); \end_layout \begin_layout Plain Layout my ($decoded, $ld); \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout $line =~ /(.).* \backslash `*$/; # remove terminal backticks too! \end_layout \begin_layout Plain Layout if (! defined $1) \end_layout \begin_layout Plain Layout { return ("", -1); # dud line! \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout $charlen = (ord($1) - 32) & 077; \end_layout \begin_layout Plain Layout if ($charlen == 0) \end_layout \begin_layout Plain Layout { # ie terminal line with single backtick: \end_layout \begin_layout Plain Layout # no error, but END! \end_layout \begin_layout Plain Layout return ("", 0); \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout if (($charlen > 45) || ($charlen <0)) \end_layout \begin_layout Plain Layout { return ("$charlen($1)", -2); # bad length \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout # convert to number, then count of characters encoded; \end_layout \begin_layout Plain Layout $decoded = unpack("u", $line); #uudecode! \end_layout \begin_layout Plain Layout $ld = length $decoded; \end_layout \begin_layout Plain Layout if ($ld != $charlen) \end_layout \begin_layout Plain Layout { return ("$ld:$charlen:$decoded", -3); # length doesn't match! \end_layout \begin_layout Plain Layout }; \end_layout \begin_layout Plain Layout return ($decoded, 1); # success! \end_layout \begin_layout Plain Layout } \end_layout \begin_layout Plain Layout \backslash end{verbatim} \backslash vskip -2mm \end_layout \end_inset \end_layout \begin_layout Standard See the archaic use of octal. But it works. \end_layout \begin_layout Subsubsection* A brief note on uuencoding/decoding \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout % uuencoding rules: \end_layout \begin_layout Plain Layout \end_layout \end_inset \begin_inset ERT status open \begin_layout Plain Layout % http://en.wikipedia.org/wiki/UUcoding \end_layout \begin_layout Plain Layout \end_layout \end_inset \begin_inset ERT status open \begin_layout Plain Layout % http://www.gsp.com/cgi-bin/man.cgi?section=5&topic=uuencode \end_layout \begin_layout Plain Layout \end_layout \end_inset \end_layout \begin_layout Standard This description assumes you understand hexadecimal and ASCII. A uuencoded file consists of: \end_layout \begin_layout Enumerate A header line; \end_layout \begin_layout Enumerate A body; \end_layout \begin_layout Enumerate A trailer line. \end_layout \begin_layout Standard All other lines must be ignored Lines may end with 0x0D, 0x0A, or any combinatio n of the two (ie carriage return and/or line feed). From now on we'll call the end of line character(s) the 'endline'. Conventionally this should be \emph on encoded \emph default as simply 0x0A. Here are the details: \end_layout \begin_layout Enumerate The header line. This contains three items \emph on separated \emph default by spaces (0x20): \end_layout \begin_deeper \begin_layout Enumerate The five character string 'begin' (no quotes around it) \end_layout \begin_layout Enumerate Three digits, each in the range 0..7 i.e. an octal number \end_layout \begin_layout Enumerate The file name in ASCII (potential for trouble here!) \end_layout \begin_layout Standard The header line terminates with an endline. \end_layout \end_deeper \begin_layout Enumerate The body. This contains one or more lines, each ending with an endline. For all but the last data line, there should be 62 characters in a line: \end_layout \begin_deeper \begin_layout Enumerate A single character, usually the ASCII character M \end_layout \begin_layout Enumerate 60 characters representing an encoded string \end_layout \begin_layout Enumerate The endline \end_layout \begin_layout Standard For the last line, some variation is permitted: The first character can be in the range 0x20 to 0x5F. There's a FURTHER CHECK: the very last line of the body does NOT contain data and is simply made up of a single backtick character. \end_layout \begin_layout Standard \emph on In all cases \emph default : \end_layout \begin_layout Enumerate The first character represents the number of encoded characters, with 0x20 added! This is why all lines but the last should start with M: they contain 45 encoded characters (hex 0x3D). The ASCII representation of M is 5D, ie 0x3D + 0x20. \end_layout \begin_layout Enumerate Encoding of characters is done three-at-a-time. If there are less than three characters, we pad with hex zero (0x0). Encoding is as follows: \end_layout \begin_deeper \begin_layout Enumerate Divide the 3 bytes (3*8 = 24 bits) into four groups of 6 bits, working from left to right; \end_layout \begin_layout Enumerate This gives us four numbers between 0x0 and 0x3F; \end_layout \begin_layout Enumerate To each number, add 0x20, giving numbers in the range of 0x20--0x5F; \end_layout \begin_layout Enumerate Write the numbers as four ASCII characters to the output file. \end_layout \begin_layout Standard In other words, we output characters in the set of: \end_layout \end_deeper \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+!"#$%&'()*,-./:;<=>?@[ \backslash ]^_+ \end_layout \end_inset as well as plus, space, 0--9 and A--Z. \end_layout \end_deeper \begin_layout Enumerate The trailer line. This starts with the three character string `end' (No quotes). \end_layout \begin_layout Standard There are some frills: \end_layout \begin_layout Itemize Also permissible are ASCII characters $>$ 95 (5Fh) but only the rightmost 6 bits are relevant. \end_layout \begin_layout Itemize The three digit number on the first line is the file mode (read / write / execute) The first number is the octal representation of the read permission of the file, the next the write permission, and finally the execute permission. \end_layout \begin_layout Itemize Because some mailers used to strip off terminal blanks, it is usual (and perhaps wise) to pad such lines (with at least one terminal blank) with supplementary junk characters. The usual character is the backtick, 0x60, which has the added advantage that it translates to the otherwise illegal value 0x0 when the high bits are masked off. \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash newpage \end_layout \end_inset \end_layout \begin_layout Section Change log \end_layout \begin_layout Subsection Changes in version 2.0 \end_layout \begin_layout Standard The major changes in version 2.0 were related to the ability to shift sections down below other sections (defer writing of certain sections), waiting for all dependencies to be fulfilled before writing the code. Names are only resolved when all of the dependencies of that section have been met. \end_layout \begin_layout Standard It would be possible to keep a record of 'names already resolved' but this is a little silly. We are only interested in deferring the writing of code, so there's little point in bookkeeping to this extent. Just leave out the dependency if it's already resolved! \end_layout \begin_layout Standard If a child has no name, then the corresponding PENDINGNAME element is \begin_inset ERT status open \begin_layout Plain Layout ~ \backslash verb+''+ \end_layout \end_inset . We could decrease memory requirements for CHILDREN by deleting array elements once written; we might benefit from even removing all corresponding elements entirely (as we will resolve the name immediately and the element in DEPENDENCI ES is of course empty as well). \end_layout \begin_layout Standard We also introduced the concepts of line concatenation, chomping off line feeds and subsequent leading spaces. \begin_inset Foot status collapsed \begin_layout Plain Layout When using the WinEdt text editor, the default is to trim trailing spaces, which can be rather irritating. You have to uncheck Options|Preferences|defaults|Trim spaces, or in already created documents uncheck Document|document settings|trim spaces. \end_layout \end_inset \end_layout \begin_layout Standard Another amendment was allowing alteration of the initial comment string (formerly newComment, now startComment), the noWarn option to suppress irritating warnings (especially with multiple file writes), and OPTIONAL statements for a debugging version. \end_layout \begin_layout Standard We also introduced insertion of binary (uuencoded) files, by allowing the user to say \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+newTarget=`uudecode'+ \end_layout \end_inset . Usage of the Uudecode function is: \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash vskip 1mm \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+($filename, $mode, $outstring) = Uudecode();+ \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset ERT status open \begin_layout Plain Layout \backslash vskip 1mm \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset Note Note status open \begin_layout Plain Layout Several comments on the uudecoding option are (a) Should we check for and warn about executables? (b) At present permissions are disabled, so this isn't really an issue. (c) At some stage we should check on how robust the Perl unpack \begin_inset Quotes eld \end_inset u \begin_inset Quotes erd \end_inset option is!, and (d) the uuencoded line \emph on cannot \emph default start on the verbatim line but \emph on MUST \emph default start on the next line --- there can be NO unused lines at the start. \end_layout \end_inset \end_layout \begin_layout Subsection Changes in version 2.1 \end_layout \begin_layout Enumerate We allow file start and end code. This is really for PHP, where such code is vital, but also for included HTML. The directive we use, for example startFile=` \begin_inset Formula $<$ \end_inset ?php' must be in the same line as the file name specification, but we can specify the endFile='? \begin_inset Formula $>$ \end_inset ' directive any time before we terminate the file for which we require such terminal code. The length of either can be specified as zero using startFile=`' or endFile=`'. \series bold Note \series default that after each file is written, these text strings are reset to the null string, so the startFile and endFile values must be specified for \emph on each file \emph default in which they are used! \end_layout \begin_layout Enumerate We removed use of \begin_inset ERT status collapsed \begin_layout Plain Layout \backslash verb+=cut+ \end_layout \end_inset , as we had problems with some Perl versions, notably v5.8. \end_layout \begin_layout Enumerate We set the focus to the `Wag' button, so on running the program with a file argument, things are ready to run. \end_layout \begin_layout Enumerate We allowed comment closure (as in HTML, older versions of C), along the lines of \emph on endComment=`-- \begin_inset Formula $>$ \end_inset ' \emph default for HTML. The default closing comment is an empty string. Note that unlike startFile and endFile, startComment persist until changed. (As of version 4.0.0, applies to endComment too). \end_layout \begin_layout Enumerate We fixed a problem with multiple dependencies, where a section was printed after just one dependency was resolved owing to an error in testing the remaining list of dependencies! \end_layout \begin_layout Enumerate In minor version 2.1.1, if the user declines to overwrite a given file, we don't abort the whole Dogwagger process --- instead, we write the data to the file `JUNK.JUNK' and carry on! Note that we overwrite this file, and don't append, so if you decline to overwrite multiple files, only the last will be kept. \end_layout \begin_layout Enumerate In minor version 2.1.2, we remove the text \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+--+ \end_layout \end_inset from the end file and section annotations, to prevent conflict with HTML formatting checks. \end_layout \begin_layout Subsection Changes in version 3.0 \end_layout \begin_layout Standard Okay, basically just got rid of Tk, and rewrote things to accommodate this. \end_layout \begin_layout Subsubsection* Version 3.0.1 \end_layout \begin_layout Standard Fixed error with line counts. Note that in LyX, we can really mess things up by having a line continue with the ERT containing a verbatim statement, as this is now missed by DogWagger. \end_layout \begin_layout Standard Also print the name of the file being processed to stdout, and put in a carriage return before asking about "Overwrite\SpecialChar \ldots{} ?" \end_layout \begin_layout Subsection Version 4.0 \end_layout \begin_layout Standard A few `issues', sorted out on 2011-12-18 -- 2011-12-19. This started as a minor rewrite and expanded a bit, so the new version number seems justified. \end_layout \begin_layout Enumerate Because of issues with chomp, the section that used this to concatenate multiple lines into one ( \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+oneLine=`yes'+ \end_layout \end_inset ) has been rewritten. \end_layout \begin_layout Enumerate Allied to the preceding issue, different source documents will use different conventions for a new line. Conventions are: \end_layout \begin_deeper \begin_layout Itemize Macintosh (obsolete) 0D ( \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+ \backslash r+ \end_layout \end_inset ) \end_layout \begin_layout Itemize Unix/Linux, and Mac OS X: 0A ( \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+ \backslash n+ \end_layout \end_inset ) \end_layout \begin_layout Itemize MS Windows 0D,0A ( \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+ \backslash r \backslash n+ \end_layout \end_inset ) \end_layout \begin_layout Standard We will generally need to preserve the characteristics of a document faithfully, but should provide the option of recoding using a different convention ( \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+newLine=`whatever'+ \end_layout \end_inset ). \end_layout \end_deeper \begin_layout Enumerate If we had \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+noWarn=`yes'+ \end_layout \end_inset before any other parameterised statement, this failed, because we used greedy matching. Fixed. \end_layout \begin_layout Enumerate We really do need some mechanism of suppressing the header comments that are inserted by DogWagger. I thus introduced the option: \begin_inset Newline newline \end_inset \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+noHeader=`yes'+ \end_layout \end_inset \end_layout \begin_layout Enumerate While we're about it, let's add \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+noSections+ \end_layout \end_inset and \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+noTail+ \end_layout \end_inset too. \end_layout \begin_layout Enumerate Because suppression of header, sections and tail is against our basic philosophy , and we don't want any `surprises', we will reset these options to the default on closing any written file. The problem is that up till now, we have read several file-related parameters \begin_inset Quotes eld \end_inset on the fly \begin_inset Quotes erd \end_inset . These include: \end_layout \begin_deeper \begin_layout Itemize startComment / newComment \end_layout \begin_layout Itemize include \end_layout \begin_layout Itemize noWarn \end_layout \begin_layout Itemize endComment \end_layout \begin_layout Itemize startFile \end_layout \begin_layout Itemize endFile \end_layout \begin_layout Itemize noHeader \end_layout \begin_layout Itemize noTail \end_layout \begin_layout Standard We now do the honourable thing, and read these parameters (ReadTargetParams) when we encounter newTarget! This does raise the possibility that someone might wish to change these parameters within a file. Hmm. \end_layout \end_deeper \begin_layout Enumerate It's nice to have \begin_inset ERT status open \begin_layout Plain Layout \backslash verb+perl Dogwagger402.pl --help+ \end_layout \end_inset produce a list of options. (done). \end_layout \begin_layout Enumerate We now warn about unrecognised options. This includes default options that are automatically reset and thus should not be specified. \end_layout \begin_layout Enumerate Fixed the bug that permits commented-out verbatim statements from being included. \end_layout \begin_layout Enumerate Having newComment is quite confusing, so I deprecate this, and recommend simply using startComment consistently. \end_layout \begin_layout Enumerate The startComment / endComment retention predisposes to an unwanted endComment being retained after startComment has changed. We should thus automatically turn the endComment to \begin_inset Quotes erd \end_inset if the startComment is altered BUT the endComment is NOT! This change has been made in ReadTargetParams. \end_layout \begin_layout Enumerate Line counts now work after deferred code and uudecoding. \end_layout \begin_layout Enumerate We need the option to write to a different log file (distinct from the usual `WAGLOG.LOG'). I have therefore introduced the command line option of log=logfilename. \end_layout \begin_layout Standard I've also prettied up the code to get rid of the nasty text overruns in the PDF document, and made some minor amendments to neaten up the text. \end_layout \begin_layout Subsubsection* Version 4.0.1 \end_layout \begin_layout Enumerate Change from LaTeX to LyX, with a few frills (and a logo); \end_layout \begin_layout Enumerate A major revision of the documentation; \end_layout \begin_layout Enumerate Less picky about case in searching for \begin_inset Quotes eld \end_inset dogwagger \begin_inset Quotes erd \end_inset ; \end_layout \begin_layout Enumerate Cleaned up checking for `uudecode' string; \end_layout \begin_layout Enumerate Introduced ability to arbitrarily turn section headings on and off (not only at file start); \end_layout \begin_layout Enumerate Maintain (and print) counts of number of sections used, files encoded, etc. \end_layout \begin_layout Enumerate Prettied up (and standardised) log output. \end_layout \begin_layout Standard \begin_inset Note Note status open \begin_layout Subsubsection* Residual concerns \end_layout \begin_layout Itemize We might document better, including the tricks we need to document Dogwagger itself,splitting begin/verbatim statements. \end_layout \begin_layout Itemize Although the code is poorly written, this illustrates the value of Dogwagger! \end_layout \begin_layout Itemize The order of arguments is illogical for many functions, due to later clumsy amendments. \end_layout \begin_layout Itemize Note: tests must include attempts to write to a nonexistent subdirectory. \end_layout \begin_layout Itemize What about Python (indenting)? [check me] \end_layout \end_inset \end_layout \begin_layout Subsubsection* Version 4.0.2 \end_layout \begin_layout Standard A few bugs and amendments. \end_layout \begin_layout Enumerate noSections = `yes' fails in 4.0.1. This is because when I rapidly added the code to permit suppression/activation of individual sections, I failed to anticipate the following problem: the command is excised; section suppression is turned on but then immediately off (by default) at the start of the file; and the command is no longer visible when the new file parameters are read. Fix by checking for newTarget in Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sub:Not-hot" \end_inset . \begin_inset Note Note status open \begin_layout Plain Layout This illustrates the value of walkthecat, which would have picked this up like a shot, provided at development the requisite tests were instituted. \end_layout \end_inset \end_layout \begin_layout Enumerate Section \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref reference "sub:Use-Dogwagger-with-LyX" \end_inset rewritten to accommodate a message about the best location of the very first Dogwagger line (in the LaTeX preamble). \end_layout \begin_layout Enumerate Some reformatting. The use of Sans-serif throughout is just too in-your-face, so I've changed to Roman. The base font size is a bit problematic, so some of the sections have been rendered as \backslash footnotesize to make them fit. \end_layout \begin_layout Enumerate [Note that as things stand, uuencoded files cannot be stored to subdirectories. Should we fix this?] \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Standard \start_of_appendix \begin_inset ERT status open \begin_layout Plain Layout %dummy comment inserted by tex2lyx to ensure that this paragraph is not empty \end_layout \begin_layout Plain Layout \end_layout \end_inset \end_layout \begin_layout Section \begin_inset OptArg status open \begin_layout Plain Layout GNU GPL \end_layout \end_inset \size large Appendix: GNU GENERAL PUBLIC LICENSE \size default \begin_inset Newline newline \end_inset \size large Version 2, June 1991 \size default \begin_inset CommandInset label LatexCommand label name "sec:Appendix:-GNU-GPL" \end_inset \end_layout \begin_layout Standard Copyright (C) 1989, 1991 Free Software Foundation, Inc. \begin_inset Newline newline \end_inset 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \emph on Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. \end_layout \begin_layout Subsection* Preamble \end_layout \begin_layout Standard \size small The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too. \end_layout \begin_layout Standard \size small When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. \end_layout \begin_layout Standard \size small To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. \end_layout \begin_layout Standard \size small For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. \end_layout \begin_layout Standard \size small We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. \end_layout \begin_layout Standard \size small Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. \end_layout \begin_layout Standard \size small Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. \end_layout \begin_layout Standard \size small The precise terms and conditions for copying, distribution and modification follow. \end_layout \begin_layout Subsection* TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION \end_layout \begin_layout Enumerate This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modificat ion".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. \end_layout \begin_layout Enumerate You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropria tely publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. \end_layout \begin_layout Enumerate You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: \end_layout \begin_deeper \begin_layout Enumerate You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. \end_layout \begin_layout Enumerate You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. \end_layout \begin_layout Enumerate If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. \end_layout \begin_deeper \begin_layout Standard In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. \end_layout \end_deeper \end_deeper \begin_layout Enumerate You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: \end_layout \begin_deeper \begin_layout Enumerate Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, \end_layout \begin_layout Enumerate Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, \end_layout \begin_layout Enumerate Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. \end_layout \end_deeper \begin_layout Enumerate You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. \end_layout \begin_layout Enumerate You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. \end_layout \begin_layout Enumerate Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. \end_layout \begin_layout Enumerate If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. \end_layout \begin_deeper \begin_layout Standard If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. \end_layout \begin_layout Standard It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. \end_layout \begin_layout Standard This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. \end_layout \end_deeper \begin_layout Enumerate If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographic al distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. \end_layout \begin_layout Enumerate The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. \end_layout \begin_deeper \begin_layout Standard Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. \end_layout \end_deeper \begin_layout Enumerate If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. \begin_inset VSpace defskip \end_inset \end_layout \begin_deeper \begin_layout Standard \series bold NO WARRANTY \end_layout \end_deeper \begin_layout Enumerate \size small BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND / OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. \end_layout \begin_layout Enumerate \size small IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND / OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. \end_layout \begin_layout Standard (END OF TERMS AND CONDITIONS) \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section Appendix: A UUencoding program \begin_inset CommandInset label LatexCommand label name "sec:Appendix:-UUencoding-program" \end_inset \end_layout \begin_layout Standard For MS Windows users, here's a UUencoding program we found on the 'Net at digitalriver.com: \end_layout \begin_layout Standard \size footnotesize \begin_inset ERT status open \begin_layout Plain Layout % \end_layout \begin_layout Plain Layout % DogWagger newTarget=`uudecode' \end_layout \begin_layout Plain Layout \backslash begin{verbatim} \end_layout \begin_layout Plain Layout begin 644 uuencode.com \end_layout \begin_layout Plain Layout MZV,-"DEN<'5T('!A=&@O9FEL93H@($EN<'5T(&9I;&4@97)R;W(N3W5T<'5T \end_layout \begin_layout Plain Layout M(&9I;&4@97)R;W(N8`T*96YD#0I.;R!A8W1I;VX@97AIC$`>D]`>CB`7,QNOP#N;H`Z+,! \end_layout \begin_layout Plain Layout MN@(!N10`NP(`M$#-(;]_`,8%4(O7M`K-(>B[`7,*M`&Z00&Y"0#KQ+KH`XOR \end_layout \begin_layout Plain Layout MN``]S2%S`^EP`:-=`8O/* \backslash Y/L%S] \backslash J[ \backslash =`B+_H!]`3IU`D='B_>+UK^T`ZP* \end_layout \begin_layout Plain Layout MP'0#JNOXN`T*JU>+ \backslash K \backslash X!(O7K`K`=0*P+JH \backslash +G7TN'5UJ[AE`(D%, \backslash F`/F0! \end_layout \begin_layout Plain Layout M_W0EM$[-(3P"=!T \backslash $G0968O/* \backslash J[`@`#R[1`S2&Z2@&Y$P"P!>D]_[0 \backslash S2%9 \end_layout \begin_layout Plain Layout M

C1Z-'HJHKB \end_layout \begin_layout Plain Layout MK(K0T^BJBL*J@ \backslash 4#.S9A`7('@#YC`0!U%X/]+74%Z#D`L08[-F$!7P&T/LTAM$S-(5"T"2YF:6P@/%)%5%523CX- \end_layout \begin_layout Plain Layout M"G!R;V1U8V5S(&)I;F%R>2Y5544@;VX@8W5R2Y5544@9&]E2Y5544-"B14:&ES('!R;V=R86T@ FOO.uue \end_layout \end_inset \series default \begin_inset VSpace defskip \end_inset \end_layout \begin_layout Standard \align center \begin_inset Graphics filename images/Dogwagger.png lyxscale 25 width 4.125cm height 3cm \end_inset \end_layout \end_body \end_document