Contents

1 Introduction

This note describes how to set up the lgrind system for Win32, when the underlying TeX system is not Scientific Word or Scientific WorkPlace, collectively, ‘SWP’. I’ll generally assume that the TeX system is MiKTeX. For SWP users, there is a more extensive discussion, which also describes other options for including programming code in your document, available here .  

2 Setting up lgrind

Here’s how to set up the system. Note that the Win32 support contains a number of files aimed specifically at SWP; you’ll just ignore those.

2.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 A 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 (as well as the instructions for SWP users).

2.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 starting 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. A simple solution is to put these files with the other TeX executables, since these will presumably already be in your path. For MiKTeX, this folder is typically <texmf>/miktex/bin.

  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.

• Create a folder for the lgrind files in the latex tree of your system. For MiKTeX one possibility is <texmf>/latex/lgrind.It must be somewhere in the LaTeX tree.
• 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.

2.3 Create the style and documentation files

• Start a DOS session and cd to the folder in the LaTeX tree with the lgrind files.
• Run latex lgrind.ins . This creates lgrind.sty
• Run latex lgrind.dtx . This creates lgrind.dvi which you can read and/or print using your system’s previewer (eg yap for MiKTeX).
• Finally, you must refresh the filename database. For MikTeX, you can do this before you close the DOS session by running the command

  mktexlsr -u

  from the command line. Alternatively, do Start -> Programs -> MiKTeX ->MiKTeX Options. This opens a dialgo window with various MiKTeX settings. Select the General tab, and under Refresh filename database click Refresh now.

• Close the DOS session.

2.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.

3 Using lgrind

There are two approaches to pre-processing your code files using lgrind.

3.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

3.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 the lgrind manual) 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

Appendix A 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 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 B Changing your path

B.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
• 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.

B.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.