Directory macros/latex/contrib/progkeys

This directory contains files that allow to generate two style
files: 'programs.sty' and 'keywords.sty'.

The 'demo' subdirectory contains an example of what can be done with
these two styles ('demo.tex' can be compiled either with LaTeX or with
LaTeX2.09 -- see the corresponding directory under macros/latex209/contrib). 

The two files in this archive may be used independently or in
conjunction, according to your wish.
The file 'programs.sty' is intended to allow a parameterized way of
typesetting programs with TeX/LaTeX commands inside.
The file 'keywords.sty' allows use and define sets of keywords that
will be typeset with different fonts, according to the wish of the
user. 
The purpose of these two files, when used in conjunction, is to allow
a user to write only one program and to print it differently,
according to the document where it must be put (ex: keywords in
english/french, keywords underlined, boldfaced, programs
indented, no indented, numbered, unnumbered, etc). Of course, the
algorithm will be written only once.

Below I give a short description of the files and the way to generate
them.

------------
programs.sty
------------
I have written a style file for typesetting programs.
Its particularities are:

- TABS are replaced by simple SPACES as in the 'astyped.sty' style
- and you can use emphasized fonts, math formulae, etc.
- programs may be numbered or unnumbered
- line numbers may appear in the left side or right side margin,
  or in both sides, or inside the text body (on the left of the text)
- line numbers may be refered to with \label / \ref
- the first line of a numbered program is by default 1, but it is
  possible to change this first value in two manners:
	o by specifying a particular first number
	o by indicating that the next program will start at the line
	  number that follows the last line of the last previous
	  program typed 
- programs may be globally indented, but a particular occurrence may
  have a different indentation

By default, 7 environments are provided, according to the font size:

		program		normal size
		programs	small size
		programf	footnote size
		programsc	scriptsize
		programt	tiny size
		programl	large size
		programL	Large size

For each environment, there exist to file inclusion commands that work
in a manner similar to the \verbatimfile and \verbatimlisting commands
of the 'verbatimfiles.sty' file: 

	\fprogram?	inclusion of unnumbered program
	\lprogram?	inclusion of numbered program

where '?' stands for nothing, or for one string in "s", "f", "sc",
"t", "l" and "L", according to the font size desired.

It is possible to define new environments. For instance

		\NewProgram{FOO}{LARGE}

will define the environment FOO with font size set to LARGE, and to
file inclusion commands: \fFOO and \lFOO.

Extract the package file from its '.dtx' file as follows:

		latex programs.ins

And get the documented source by:

		latex programs.drv
		latex programs.drv
		latex programs.drv
		makeindex -s programs.ist programs.idx
		latex programs.drv

------------
keywords.sty
------------
As a companion to the style programs.sty, here follows a style called
keywords.sty whose main purpose is to provide a parameterized way to
typeset keywords. This style may be used in conjunction with the
programs.sty file, but this is not necessary.

What you can do is, for instance, to type a program where keywords
will appear boldfaced. It suffices to issue the \ProgKeywords command
(global scope), and then to type the text, for instance:

	\BEGIN 
		\FOR I := 1 \TO 10 \DO
			....
		\ENDDO
	\END

In this example, the keywords are commands defined in the second part
of the keywords.sty file. If the environment is such that spaces are
obeyed (like in the verbatim environment or by using the programs.sty
file), then keywords can be typed as is; otherwise (i.e. in normal
text) they must be typed followed by a "\" character
(e.g.: \BEGIN\ ...).

Assume now, that you want that the program above is typed with
keywords written with an emphazised font and underlined, and that
words appear in French instead of English.
Then take the same program, but just change the "\ProgKeywords"
command that precedes it to "\UFAlgoKeywords" (for: Underlined French
AlgoKeywords).

I have sorted keywords in lexicographic order.
If you need to change or add a definition go anywhere among the
keywords and type (e.g. definition of the keyword FOO):

#1{\FOO}{this is an example}[bla bla]%

Then if you chose commands where the 'F' does not appear in the
beginning of the name, any occurrence of "\FOO" is replaced by the
sentence "this is an example"; otherwise, the sentence "bla bla" will
be used.

If your wish is that the same expansion is performed for all the
commands, the omit tht fourth parameter:

#1{\FOO}{this is an example}


The commands provided are:

 -------------------------------------------------------------------------
				English keywords 	French keywords 
 -------------------------------------------------------------------------
 \tt BOLDFACE DISPLAY 		\ProgKeywords		\FProgKeywords
 \tt NORMAL DISPLAY 		\ttKeywords		\FttKeywords
 \em DISPLAY 			\AlgoKeywords		\FAlgoKeywords
 underlined \em DISPLAY 	\UAlgoKeywords		\UFAlgoKeywords
 normal (\rm) DISPLAY 		\NormalKeywords		\FNormalKeywords
 -------------------------------------------------------------------------

As I am French, I have used English and French languages; however you
can use any couple of languages you want. I recall that if parameter 4
in keyword definition is omitted, then only the first language is
used.

The file terminates by a command that selects the default mode (in the
current case this is \UFAlgoKeywords).

Extract the package file from its '.dtx' file as follows:

		latex keywords.ins

And get the documented source by:

		latex keywords.drv
		latex keywords.drv
		latex keywords.drv
		makeindex -s keywords.ist keywords.idx
		latex keywords.drv


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Miguel ALABAU
LaBRI, Universite BORDEAUX I
351, cours de la Liberation   33405 TALENCE Cedex (FRANCE)      
e-mail: Miguel.Alabau@labri.u-bordeaux.fr
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~