Contents

1 Introduction

You’ve solved your problem, it’s a beautifully simple piece of computer code, and you want to show the world. As an SWP user (and by ‘SWP’ I mean Scientific Word or Scientific WorkPlace), of course you want to include it as part the SWP/LaTeX document announcing your discovery. What are your options?

(For non-SWP users: there’s a much shorter discussion of how to set up lgrind available here ).

1.1 The simple solution

If all you want is to present your code in a monospaced font, possibly with numbered lines for reference purposes, then you should use the \listinginput macro from the moreverb package. To use this, you must first load the package: see Appendix A for a refresher on this. Then, to include your document with numbered lines, just insert an encapsulated TeX field at the point where you want the listing to appear: the contents of the TeX field are

\listinginput[n]{m]{filename}

where

n = increment: a line number will appear every n lines

m = first line to be numbered

filename = full name, including path, to your source file. Note that you must use Unix–style separators here ( / not \ ) or else LaTeX will become confused. You must provide the full path, since SWP typically makes a copy of your source document in a temporary directory and compiles the copy: thus you cannot rely on the source and the file to be included being in the same directory, even if they really are.

You can get \listinginput to turn off line numbering by setting m> number of lines in the source file, and n to be (say) 10m.

If you want to use a smaller monospaced font, you could say, for example

 
\small
\listinginput[n]{m}{filename}
\normalsize

One thing you should not do is use the \verbatiminput command in the verbatim package. The reason is that most versions of SWP have problems parsing documents which contain any non-standard commands beginning with \verb... and you may find that your file has been truncated when you next open it in SWP. If you save the truncated file, then the truncated material is lost. So using \verbatiminput can be dangerous and is not recommended.

1.2 Pretty printing

But suppose you want more than just a plain listing: you’d like, for example, keywords in the programming language to be bold-faced, comments to be in a special font, etc. The SWP documentation suggests the algorithms package; but that has a few disadvantages. First, you need to type the contents of your code into a TeX field: you can’t just read it in from the disk file. (Of course, you can paste it in, saving a bit of work). Second, this means that every time your computer code changes, you’ve got to update your document by hand. Third, you’ve got to enter special macros to get your code nicely formatted: for example, to get for all as a keyword in bold, you need to enter \FORALL. And finally, the set of keyword macros provided by algorithms may not match the keywords of your programming language. All in all, I think that using algorithms is a bit too complicated to be really useful.

There is another solution, which will relieve you of the need to enter the code into a TeX field, which is relatively simple to update when your code changes, and which will pretty-print it appropriately for a wide selection of computer languages: this is the lgrind system. The remainder of this note describes how to set up and use lgrind. Note that this is a command-line (DOS session) approach, somewhat inimical to the usual Windows approach to things.

1.3 Stop Press

No sooner had I finished the second draft of this note than I discovered the listings package. This appears to be able to do most (?everything) that lgrind can do, but without the need for pre-processing the files. That is, you can just read in the file containing the original program code, and it will be formatted appropriately in your SWP document. I’ve therefore added a new part on using this package; but be warned that it is very sketchy.

1.4 Acknowledgement

These instructions have benefited substantially from comments by Dick Startz at the University of Washington: it was in response to his request that I compiled a Win32 version of the lgrind.exe. His interest — reflected in the discussion below — was in processing Matlab files. Unfortunately, lgrind failed on the first file he wanted to work on, which contained a line with doubled comment characters. I have a couple of fixes for this see Appendix D.

2 Updates

This section lists updates to the write-up, for easy reference.

• May 12, 2004: initial public release
• May 20, 2004: it turns out that it is possible to handle inline code with the listings package. Section 4.3 explains how.

Part I
The listings Package 

As noted above, listings — NB: listings plural: there’s apparently another package called listing in the singular, which isn’t the one you want — is able to pretty-print your source code from a file without having to run it through a pre-processor like lgrind. It comes with a few more languages than lgrind does, and from a look at the files, it seems relatively straightforward to add new ones. The disadvantage of listings is that essentially everything is customizable, and it may take you some time to figure from the 50-page manual, just how to get the effect you want. For people who dislike entering LaTeX code, understanding and setting up the options may be a daunting task: for those people, lgrind may still be the best choice. On the other hand, lgrind is not as customizable, but in my limited experience, produces highly acceptable results out-of-the-box.

One slight additional advantage of listings is that it can cope with displayed listings, provided that you put them into an SWP TeX field: in this case, unlike algorithms, you don’t have to do any special formatting. With a bit of effort, it is also possible to type your code directly into an SWP doucment, and have listings format it correctly. Finally, note that listings can apparently not produce a floating listing of your on-disk code files (unlike lgrind). On the other hand, since floats can take up at most one page, it’s not clear, as a practical matter, just how useful the floating facility is.

3 Setting up listings

3.1 Get the files

You can get the latest edition of listings from a convenient CTAN node. You should choose a node which allows you to get the entire listings directory as a .zip file. This file will typically be named listings.zip. See Appendix B for details on how to do this.

3.2 Set up the files

Create a folder in the LaTeX tree for your files: I suggest <swp>/tcitex/tex/latex/contrib/supported/listings, where <swp> is your to-level SWP folder, eg c:/swp50. Unzip the CTAN archive to there. There are no subdirectories in this structure.

At this point you should certainly print out the manual, listings.pdf.

4 Using listings

Using the package involves two steps:

• Set up the languages and the formatting
• Then, either
  • Import your code document see section 4.2
  • Type in your indline code; but this requires a certain amount of preliminary setup. See section 4.3.

4.1 Set up the languages and formatting

I think that the easiest way to do this is to put it all into the Preamble: you could load the package through Options and Settings but since you will almost certainly need to do some setup in the preamble, you might as well do it all there.

To load the package, put into the preamble \RequirePackage{listings}

The package documentation recommends that you then pre-load the language support for the files you will be processing: you do this with the \lstloadlanguages command, whose argument is a comma-separated list of languages. Note that some of the languages have dialects which are specified by a proceeding argument in brackets; so you might have \lstloadlanguages{[visual]C++,matlab} for the Visual dialect of C++, and Matlab.

If you want your listings to have some common features, you can set them up with the \lstset command. The argument here is a comma-separated list of key=value pairs. You have a huge number of choices here. If you like the way lgrind formats your listings, then the following should coax listings to produce pretty much the same thing:

\lstset{basicstyle=\footnotesize,columns=fullflexible,frame=lines}

The setting that has the most effect here is columns=fullflexible. What this does is tell listingsnot to try and line up your code by columns. Since things like keywords are by default typeset in a proportional (Roman) font, I think that it looks a bit ugly to try to adjust the letter-spacing to get columns to line up; but your tastes may differ. You can even use the \lstdefinestyle to define several named style variants, and then refer to them later on by name when you import and print your code.

4.2 Import your program files

To have listings read and process your files insert an encapsulated TeX field at the place in your document where you want the code to appear. The minimal form of the contents of this field is

\lstinputlisting{filename}

where filename is the full path to the file, including the extension. (The full path is needed by SWP, since it typically makes a copy of your source in another directory and compiles the copy: you cannot rely on the main (.tex) document, and the code files being in the same place even if they in fact are). You must use Unix path separators here ( / , not \ ), or else LaTeX will become confused.

If you are using different languages you must tell listings which language your file is in: unlike lgrind, listings makes no attempt to guess the language from the extension. In this case you’d supply an optional argument to the \lstinputlisting macro and say something like

\lstinputlisting[language=matlab]{filename}

Note that if you’re using a dialect in an optional argument, as here, then the whole thing needs to be placed in braces: you’d need to say, eg, [language={[visual]basic}].

You can also use the optional part of the argument — the part in square brackets — to modify defaults or change previous settings. For example, if you really want column alignment just for this display, you could say

\lstinputlisting[language=matlab,columns=fixed]{filename}

4.3 Inline listings

It is possible to type your code directly into your SWP document, and have listings format it correctly. But it takes a bit of preliminary setup. Here’s what you need to do.

4.3.1 Prepare your .cst file

SWP gets its on-screen formatting instructions from a .cst file: each document you create references one of these: you can figure out which one it is by doing Tag -> Appearance and then in the resulting dialog, look at the entry in the Style File for Document at the bottom. It can sometimes happen that the information here is too long to fit into the provided box; you can also get it by tracking down the document shell (File -> Document Info, then look under the General tab) and looking in the shell file for a comment of the form %TCIDATA{CSTFile=genpap.cst}. At this point you need to search through SWP’s styles folder for this file. The first step is to add some new instructions to this file.

• Open the .cst file in a text editor. You should ensure that you have a clean backup before making the changes to be described, just in case something goes wrong.
• At the top, in the [FILTER] section (and before the line \TCIEnd) add the following line:

  \newverbatim{lstlisting}{}{}

• You’ll now add a new section at the end of the .cst file describing what happens when this tag is invoked. The simplest way to do this is to copy the section beginning [verbatim], paste it in again at the end of the file, and then change the tag name from [verbatim] to [lstlisting] and the ALIAS= setting from Body Verbatim to LstListing. You’ll end up with essentially this:

   
  [lstlisting]
  TAG_TYPE=PARA
  ALIAS=LstListing
  PARAGRAPH_INDENT_RIGHT=0
  PARAGRAPH_INDENT_LEFT=0
  TAG_BEHAVIOR=FORCESTEXT|PRESERVESPACES|NOLINEBREAK
  FONT_FACE=Courier New
  FONT_SIZE=10

  The tag will appear in the set of text tags (the set containing sectioning tags) under the name listed in the ALIAS setting. This, and the FONT_FACE and FONT_SIZE, can of course be altered to suit. Many of these — and other characteristics — are also modifiable via SWP’s Tag->Appearance dialog. It’s important not to alter the [lstlisting]since (a) it must match the \newverbatim at the top of the file; and (b) it names the environment that SWP will insert in your document, and of course this is not negotiable. (OK, strictly speaking it is negotiable: as the listings Reference Manual describes, it’s possible to define your own listings environments via \lstnewenvironment, which in principle could incorporate settings such as language: that is, you could define (say) an environment called pascal which could force usage of language=pascal. But for SWP use, this would mean adding settings to the .cst file for each such environment; and this probably isn’t worth it, unless perhaps you make lots of use of just one or two languages, and you want to avoid the bother of the encapsulated TeX fields).

• Save the .cst file. Note that you will need to make these changes in each .cst file in which you will be including inline code.

4.3.2 Change the shell document

If you try to typeset a document containing an instance of the new tag, LaTeX will complain about an unknown command. So you might as well make sure that your shell document loads the listings package before you use it. Strictly speaking, this isn’t necessary, provided you remember that you need to do load listings by hand in each document which uses it; and indeed it may be marginally faster not to load listings unless it’s actually needed. But if you’re forgetful and intolerant of LaTeX errors, it’s probably a good idea to take care of it once and for all. Alternatively, you could create a new shell (a clone of an existing shell) which you’d use just for documents containing code.

If you’re going to alter a shell, I think it’s easier to make the change by hand, rather than loading the document into SWP and then exporting it as a shell, partly because you still need to track down the location of the shell. So here’s how to modify a shell by hand.

• Track down the shell document: it will be somewhere in SWP’s shells folder.
• Open the shell in a text editor.
• After the line beginning %TCIDATA{CSTFile= add the following on a line of its own:

  \RequirePackage{listings}

• Save the file.
• Now open an instance of the modified shell in SWP (File -> New etc). On the Text Tags popup (alternatively, in the dialog via Tag -> Apply) you should see an entry for the listings tag: LstListing in our example. If you look at the Preamble (Typeset -> Preamble), you should see your \RequirePackage statement if you customized the shell. If you don’t, you’ve made an error somewhere, and you need to review the instructions.

4.3.3 Entering your inline code

First, you will almost certainly want to add a new entry to the Preamble describing what kind of code you’ll be working with: this is the \lstloadlanguages command described in section 4.1. You may also want to set up some default formatting via the \lstset command.

Then, the way you enter your code depends on whether you’ll be listing more than one language in your document.

• If you’re using just one language, just start a LstListing (or whatever you called it) item on the sectioning tags popup. Then type in your code. When you’re done, remember to reset the tag to Body Text.
• If you’re switching between languages, you need to precede your code with an instruction to change the language. This will be an encapsulated TeX field whose contents are, at minimum:

  \lstset{language=xxxx} or \lstset{language={[dialect]language}}]

  where the second form is required if you are using a dialect.

• Then start a LstListing tag and enter your code. When you’re done, remember to revert to Body Text.
• You will need to enter one of these TeX tags every time you change the language, otherwise the formatting conventions of the previous tag will be in force.

5 Runing the test example

When you set up the SWP support, you unzipped a couple of example files to a location containing your other SWP documents. Here’s how to use these files to test listings file inclusion within SWP.

• Start SWP, find and open swpexample2.tex.
• Take a look at the Preamble, where we load the package, and set up some formatting.
• Open the encapsulated TeX field and change the path to egcprog.c to match its location on your system. Remember to use Unix-style path separators, / not \.
• You should now be able to compile and preview and/or print this document. Note that compiling may take longer than you’re used to — this may be noticeable with longer listings — because the package has to do a lot of parsing in the fly.

Part II
The lgrind System

6 Setting up lgrind

Here’s how to set up the system. These instructions are aimed mostly at SWP users, but we provide terse instructions for users of other Win32 LaTeX systems, too.

6.1 Get the files

You will need the following files:

• An edition of lgrind from a convenient CTAN node. You should choose a node which allows you to get the entire lgrind directory as a .zip file. This file will typically be named lgrind.zip. See Appendix B for details on how to do this.
• The Win32 executable lgrind.exe is in lgrindswp.zip, available from here . This archive also contains an HTML copy of these instructions.

6.2 Set up the files

• Find an empty folder and unzip lgrindswp.zip there.
• You must now put some files into a folder “in your path”: this is a folder that will be automatically searched for executables when you call them from the command line. You can see what folders are in your path by stgarting a DOS session and doing a path command. I strongly recommend against using any folder set up by Windows itself, though in principle this is possible.

  If you don’t have a convenient folder in your path already, create one (say, c:\utility). See Appendix C for how to add it to your path.

  Now copy the following files to that folder:

  • lgrind.exe
  • lgrindx.bat
  • asm2tex.bat
  • c2tex.bat

  Note: the last two files have the same name as files in the lgrind distribution, but implement a slightly different strategy for naming the files created by lgrind: you provide the filename plus extension when you use lgrind. The output files will have a double extension: the extension .lg is appended to your original extension. Of course, you can use the versions in the lgrind distribution if you prefer.

• Set up a LaTeX directory: I suggest <swp>/tcitex/tex/latex/contrib/supported/lgrind, where <swp> is your top-level SWP folder, for example c:/swp50.It must be somewhere under <swp>/tcitex/tex.
• Extract the contents of the lgrind.zip file you got from CTAN to this folder, preserving subdirectories. You should see lgrind.ins in the top-level folder. Optional: you can delete the sources sub-folder.
• Copy lgrindef to the folder where you put lgrind.exe.
• You have an archive swpexample.zip containing a test of the setup. Extract its contents to somewhere with your other SWP documents (perhaps to a separate folder).

6.3 Create the style and documentation files

• Use the stand-alone TrueTeX formatter (initex32) to process lgrind.ins.
  • Start the stand-alone formatter from the SWP entry in the Programs listing.
  • The Open dialog should start automatically. When it does, navigate to the folder where you stored the lgrind files.
  • Note that this dialog is set up to show only .tex files. So you won’t see lgrind.ins in the dialog box. You can either enter lgrind.ins directly, or enter *.* which will show all files, and then select lgrind.ins.
  • Click on Open, and the formatter will run. This creates lgrind.sty.

• Use the stand-alone TrueTeX formatter to process lgrind.dtx in the same way. This produces the documentation, lgrind.dvi which you can read and/or print using the TrueTeX previewer.

6.4 Adjust lgrind.exe

You must now tell lgrind.exe where to find its definitions file, lgrindef, which in this case is in the same place as the executable. The problem is that there’s no user folder guaranteed to be in the path in all versions of Windows (otherwise I could have compiled lgrind.exe with that information embedded, andtold you to place the file in that folder). So we need to produce a customized version of lgrind.exe.

• Start a DOS session and cd to the folder containing lgrind.exe and lgrindef
• Run the following command:

  lgrind -d! c:/utility/lgrindef

  where of course you will replace c:/utility/ with the full name to the folder you’re now in (ie the one containing lgrind.exe). Note that there is an exclamation point after the d, a space after the exclamation point, and you must use Unix-style path separators: / not \ . This will create lgrind.new. Make sure that it does.

• Delete lgrind.exe
• Rename lgrind.new to lgrind.exe: ren lgrind.new lgrind.exe
• You can now close the DOS session.

7 Running the test example

When you set up the SWP support, you unzipped a couple of example files to a location containing your other SWP documents. Here’s how to use these files to test lgrind within SWP.

• Start SWP, find and open swpexample.tex. Note that it loads the lgrind package via a \RequirePackage statement in the preamble.
• Open the encapsulated TeX field and change the path to egcprog1.c.lg to match its location on your system. Remember to use Unix-style path separators, / not \.
• You should now be able to compile and preview and/or print this document.

You can also test the entire setup by running lgrind yourself:

• Start a DOS session, cd to the location of the example files.
• Run lgrindx egcprog.c This should produce egcprog.c.lg which should be identical to egcprog1.asm.lg except for a time-stamp.
• You can now edit the encapsulated TeX field in swpexample.tex and delete the digit “1” in the file name. The file should compile under SWP and give the same results as before.

8 Using lgrind

Using the system involves two steps:

• You must produce LaTeX versions of your code files, using lgrind.exe . Note that there’s no way to do this from within SWP itself, and you’ll need to recreate the LaTeX versions files every time you change the originals.
• You must tell LaTeX where to insert these code fragments in your document, using special macros

8.1 Producing the LaTeX source files

8.1.1 The simple strategy

lgrind can usually deduce the language of your source files from the extension (see toward the end of the lgrindef file for a list of known extensions: you can add to this list; of course, the extension must be unique).

• Start a DOS session and cd to the folder containing the program source files.
• Run lgrindx name-and-extension of your source. For example, if you’re working with Matlab files, you could say lgrindx myfile.m . As it runs, lgrind will report the language it thinks you mean, so you can make sure that your intention has been correctly understood. Watch this closely: if lgrind doesn’t know of your language, it will use C-language formatting, and will tell you that.
• This will produce a double-extension file, with the last extension being .lg. So running lgrindx on myfile.m will produce myfile.m.lg

8.1.2 The more complicated strategy

In this case we create a batch file which explicitly names the language that lgrind is to use. This will probably be necessary only (a) when you use an extension unknown to lgrind (but you can fix this by adding the extension in lgrindef); (b) when you have a case of multiple extensions for the same language: for example, Matlab and Maple might both use .m extensions; or (c) when you want to provide a substitution file (see section 9) which will not apply to all languages. Note that you’ve already installed language-specific batch files for the C (c2tex.bat) and assembly language (asm2tex.bat) languages.

Creating the batch file

Here I’ll assume you want to create a Matlab-specific batch file. We’ll use asm2tex.bat as a template.

• Make a copy of asm2tex.bat (in the same folder containing lgrind.exe) as (say) matlab2tex.bat.
• Open the copy in a text editor like NotePad.
  • Change all instances of .asm to the extension used for your program source files. The lines in which this will be necessary are:
    • the comment line beginning :: convert .asm ... 
    • the one beginning if not exist

    If your Matlab files have extension .m then you’d change .asm to .m in both these places.

  • You must now tell lgrind.exe which language definitions apply: this is the argument to the -l switch on the line calling lgrind. Find the line beginning

    lgrind -i -lmasm

    then change -lmasm to refer to the label of the Matlab section in lgrindef: in this case it happens to be matlab. So you’d say -lmatlab Note that the language name is not case-sensitive.

• Save the file.

Run your batch file

• Start a DOS session and cd to the folder containing the program source files.
• Run the batch file you just created: for example matlab2tex name-and-extension of your source. For example, if you’re working with Matlab files, you could say matlab2tex myfile.m .
• This will produce a double-extension file, with the last extension being .lg. So running lgrindx on myfile.m will produce myfile.m.lg

8.2 Referencing lgrind files within SWP

This section is aimed at SWP users only; the idea of “encapsulated TeX fields” doesn’t apply to others.

Setting up to produce typeset output from the lgrind files is straightforward: there are two things you need to do:

• Load the lgrind package; see Appendix A for a reminder of how to do this.
• To insert your pretty-printed code you will insert an encapsulated TeX field, naming your lgrind-produced file. You have two ways of doing this:
  1. Via the lgrindfile macro, which just inserts the code at the location that the macro appears. To insert code this way you insert an encapsulated TeX field whose contents is \lgrindfile{filename} where filename is the full path to the file, including the extension. (The full path is needed by SWP, since it typically makes a copy of your source in another directory and compiles the copy: you cannot rely on the main (.tex) document, and the code files being in the same place even if they in fact are). You must use Unix path separators here ( / , not \ ), or else LaTeX will become confused.
  2. Via the lagrind macro which arranges to have the code floated to the nearest convenient location, just like floating tables and figures. Remember that floats must fit on a single page, so you can’t use this for long sections of code. To use this option the contents of the encapsulated TeX field would be: \lagrind[x]{filename}{cap}{label} where
     • x (optional, defaults to t) is one of t,b,p or h, for placement options top-of-page, bottom-of-page, page-of its-own and here-if-possible respectively — these are the same options you can select for a floating figure in SWP. Note that this argument is in brackets, not braces.
     • filename is the is the full path to the file, including the extension. You must use Unix path separators here ( / , not \ ), or else LaTeX will become confused.
     • cap is a caption for your floating figure. May be empty.
     • label is a label which allows you to reference the figure. May be empty.

9 Advanced use of lgrind

9.1 Pseudo code

Suppose you have a bit of computer code which repeatedly uses the variable beta (for example, you’re programming a least-squares routine). Some people think that the printed version of the code would be easier to understand if instances of beta were replaced by the Geek letter . This of course makes the code into pseudo-code: it’s not usually what the compiler would expect to encounter.

lgrind allows you make this (and other) replacements. However, to use it you will need to know a bit of LaTeX: for example you’ll need to know that to typeset a , it must be in a math group. If you’re confident that you can handle this, you can set up a substitution file, which specifies the text to be found in your code and the LaTeX command that’s to replace it, and provide the name of the file to lgrind.exe either on the command line or else built-in to the batch file.

In addition, this will probably require you to do the conversion using a language-specific batch file: for example, you may want to translate “beta” as above in one programing context, but in another, where it might refer to a built-in language function computing (say) values of the Beta distribution, you probably want to leave it alone.

You provide the name of the substitution file via the -v switch. See subst in lgrind’s examples subdirectory for an example. For the beta example, you’d have a line in a substitution file saying beta=$\beta$. See the lgrind manual for more on this.

Part III
Appendices

Appendix A Adding Packages in SWP

There are two — OK, three — ways to do this.

1. The approved way is through the Options and Packages dialog. Do Typeset -> Options and Packages, and select the Package Options tab. Click on Go native. In the next dialog, start a new line and enter the name of the package in braces, preceded by any options, separated by commas, in square brackets. So to use the lgrind package with no options, you’d enter just {lgrind}. To use the package with the option leftno (line numbers on the left) you’d say [leftno]{[lgrind}.

   It’s possible to automate this a bit, by adding lgrind and all its options to the list of packages “known” to the dialog: see Document 280, “How to use an unlisted LaTeX package” on the Mackichan site: here’s a link to that discussion. But if you use lgrind only occasionally, this may be more trouble than it’s worth.

2. My preferred way is to enter it by hand in the Preamble dialog: do Typeset -> Preamble and then on a new line — I tend to put this near the top of the list — enter \RequirePackage[options]{package}. So in the example above we’d have \RequirePackage[leftno]{lgrind} . As I say, this is the way I generally do it; but purists frown on it.
3. The third way is to enter a \usepackage command into the preamble, instead of \RequirePackage. Otherwise the syntax is the same as the \RequirePackage command. If you do this, then the next time you load your source file, SWP will move the \usepackage command out of the preamble, and into the portion of the document accessed with the Options and packages dialog, so it’s a bit more cumbersome to change.

Appendix B Using CTAN

Here’s how to get files from CTAN, the Comprehensive TeX Archive Network: in this case we want the lgrind files.

• Go to a CTAN search page: there’s one at http://www.ctan.org/search/
• In the field Search CTAN for a keyword enter (say) lgrind and click Submit query
• When you get the response, pick the most general one, which is this case probably be the first one shown.
• On the right of the heading line (beginning Options for this directory), there’s a link for Get the entire directory. Click on it.
• On the next page, click on .zip. If this is your first time using CTAN’s directory fetching feature, or if you’ve disabled cookies in your browser, you’ll be asked to select a location (CTAN mirror). In the list you’re presented with, it’s important to select one with ‘zip’ following the name, since that’s the kind of file we’re after. If you’ve selected a mirror not supporting zip files, you’ll be told; and you can try again. You can always select a mirror by hand by clicking on choose a different mirror at the bottom of A few notes on this page.
• Eventually you’ll find a mirror supporting creation and transfer of zip files, and you’ll download the file.

Appendix C Changing your path

C.1 WinNT, Win2k, WinXP

• Open the Control Panel. If you don’t see a bunch of individual icons, one of which is System, then click on Switch to classic view at the upper left of the window. (This will probably necessary with a default WinXP setup).
• Click on the System icon
• Then:
  • Win XP/Win2k: In the new window, select the Advanced tab, the towards the bottom click on Environment variables
  • Win NT: select the Environment tab

• In the System variables box, select Path. Then:
  • Win XP/2k: click on Edit. In the new window, scroll to the end of the listing. Enter a semicolon (; ) to separate what you’re about to enter from what’s already there; and then type in your new path element. Note that here you’ll use the normal windows-style path separators: \ not /. Click OK to close the editing box, and then OK again to exit the Environment variables dialog, and then OK once more to exit the System dialog. Close the Control Panel.
  • Win NT: When you select Path, the current value will be shown in a box at the bottom of the dialog. scroll to the end of the listing. Enter a semicolon (; ) to separate what you’re about to enter from what’s already there; and then type in your new path element. Note that here you’ll use the normal windows-style path separators: \ not /. Click OK to accept the new entry and leave the System dialog.  

• At this point you can start a DOS session and type path. You should see that your entry shows up at the end of the listing. If it looks wrong, repeat the above procedure, but this time just edit the entry you’ve just provided.

C.2 Win95, Win 98

On these operating systems, the path is given in the file config.sys in your root directory.To change the path:

• Open c:\config.sys in a text editor like NotePad
• Find the line beginning path=
• At the end of this line add a semicolon and then the folder you want to add to your path. Path separators are the usual MS-DOS separators, \ not / .
• Save the file.
• You will need to restart Windows for this change to take effect.

Appendix D Matlab + lgrind

Here are a few for the double-comment (%%) problem noted by Dick Startz: the issue here is that lgrind sets up paired double-%%’s to delimit a TeX expression within a comment. So the easiest fix is to train yourself to use only a single comment character throughout your code.

Second, listings has no problem with doubled comments, so this might be a good excuse to try out this package.

Third, if neither of the above appeals to you, and if what you want is for doubled-%’s to be treated simply as comments, you can teach lgrind to treat them this way. Here’s how to do it:

• Open lgrindef in a text editor.
• Find the beginning of the Matlab section.
• Find the line containing the text :tb=%%:te=%% . Make a copy of this line and put a comment character ( # ) at the beginning of the copy: this preserves it if something goes wrong. Move the copy to before the start of the Matlab definitions, ie before the line MATLAB=\
• In the un-commented copy, delete the text :tb=%%:te=%% . Note that this is two bits of code, and that each bit begins with a colon.
• Save lgrindef

Finally, you might want to take a look at http://www.madic.org/download/matlab/highlight/ for a Matlab function which produces LaTeX. Given the availability of an lgrind fix and the fact that listings works out-of-the-box, it’s not clear that this is an optimal solution, but there it is.