He then turned over package maintenance to Brooks Moses, who had volunteered for the position while this procedure was going through. There is no intent to infringe; use is for the benefit of the trademark owner.
A minimal file
Typesetting listings
Like most examples, the following shows literal LATEX code on the right and the result on the left. To be compatible with such packages, all listing package commands and environments use the 'lst' prefix.
Figure out the appearance
Seduce to use
Other features There are still features that have not been mentioned so far: automatic breaking of long lines, the possibility to use LATEX code in listings, automated indexing or personal language definitions. But note that the output is not produced by the LATEX code on the right alone.
Alternatives
In addition, you can get line numbers on the left or right side, use any LATEX code in the source code, print symbols instead of word names, set the font, etc. It supports stand-alone files, text and display lists, and you can even nest commands/environments if, for example, you use LATEX code in comments.
Package loading
The key=value interface
You must use these keys within an optional environment argument or input command. If a value with an optional argument is used inside an optional argument, you must place parentheses around the value.
Programming languages
Preferences
All parameters set via '\lstset' keep their values until the end of the current environment or group. The optional parameters of the two pretty-print commands and the 'lstlisting' environment only take effect on the specific list, i.e.
Special characters
Similarly, if you use extended UTF-8 characters in a list, they must be escaped to LATEX. Also, section 8 has a few details on how to work with extended characters in the context of Λ.
Line numbers
If you use them, you must load fontenc, inputenc and/or another package that defines the characters. If you have an entry in a CJK environment and want to have CJK characters in the list, you can put them in a comment that escapes to LATEX - see section 4.3.13 for how to do that.
Layout elements
You might think that the lines should be drawn to the edge, but what about rounded corners. Note that frame round has been used with \lstset and so the value affects all subsequent lists in the same group or environment.
Emphasize identifiers
Even if your source code is highlighted as expected, there is no guarantee that this will still be the case if you change the order of your listings or if you use the next release of this package.
Indexing
Fixed and flexible columns . 23
It is obvious that a beautiful printing tool like this requires some kind of language selection and definition. However, it is very convenient to have the same for printing styles: in a central place in your document, they can be easily changed, and the changes will take effect in all lists.
Language definitions
The first has already been described and the latter is covered by the next section. This delimiter opens and closes the string and within a string it is either escaped by a backslash or it is doubled.
Delimiters
As you can see, you have the choice of specifying the style explicitly with LATEX commands or implicitly with other style keys. You can even have the package register keywords, comments, strings, and other delimiters inside the content.
Closing and credits
Therefore, [*] must be entered exactly as is, but [*] will just be * if you use this argument. If you want to enter one of the special characters {}#%\, this character must be escaped with a backslash.
Typesetting listings
This means that you should write \} for the single 'right curly brace' character, but not for the trailing parameter character, of course. Unlike the environment of the package literal, LATEX code is executed on the same line and after the end of the environment respectively.
Options
- Searching for files
- Space and placement
- The printed range
- Languages and styles
- Figure out the appearance . 32
- Captions
- Margins and line shape
- Frames
- Indexing
- Column alignment
- Escaping to L A TEX
See the class offset key in section 4.3.5 if you want to highlight the keywords of the languages differently. Note: The size of the quarter circles depends on the frame and is independent of the extra margins of a frame.
Interface to fancyvrb
About half of the comment line of the second example is set by this package and the rest is in "LATEX mode". Additionally, note that the first space begins a comment as defined at the beginning of the example.
Environments
If you use fancyvrbs command characters, you must tell the summary package how many arguments each command takes. So if you want to use\textcolor{red}{keyword}with thefancyvrb-listings interface, type\lstset{morefvcmdparams=\textcolor 2}.
Short Inline Listing Commands 45
The delimiter begins a comment line, which generally begins with the delimiter and ends at the end of the line. Each first-argument keyword starts a comment, and each second-argument keyword ends it (and also a semicolon); a comment that begins with any third-argument keyword ends with only the next semicolon.
Installation
Note that the listing requires at least version 1.10 of the keypack included in the graphics package by David Carlisle. A generic interface is completely outside the scope of this package - that's the job of a compiler, not a pretty printing tool.
Literate programming
The key could control whether function names are added to a special keyword class, which then appears in the "procname" style. Maybe the key(s) should work the same way as string and comment definitions, ie.
LGrind definitions
Instead of printing these characters, we use replacement text, which takes the width of length characters in the output. It can be annoying if empty or small boxes take up three or more lines in the output - think about scrolling down all the time.
Arbitrary linerange markers . 55
If you are facing a problem with the inventory package, there are some steps you should go through before filing a bug report. Submit a bug report to the address on the first page of this documentation and include the minimal file along with the generated .log file.
Listings inside arguments
If you are using a very specific package (ie one that is not on the CTAN), include the package as well if its software license allows it.
Listings with a background
If you did that, the compiler wouldn't see the LATEX code since it would be in a comment, and the list packages wouldn't print anything since the delimiters would be omitted and produce no printable output, but you could still reference the line number. Now, if you use Λ (Lambda, the LATEX variant for Omega) and want for example Arabic comment lines, you don't need to write \begin{arab}.
How to define lst-aspects
If you want to make additions to a specific document, just replace the surrounding '\lst@BeginAspect'. Therefore, it is defined between '\lst@BeginAspect{keywords}' and '\lst@EndAspect', which is not shown here.
Internal modes
The first command returns to \lst@nomode, but saves the current mode order on a special stack. No mode change is allowed if this boolean is true—except to exit the current mode.
Hooks
Note: \lst@ifmode is not deprecated as there is no relation between the boolean and the current mode. Every set command/environment calls this hook to initialize internals before setting any user-supplied key.
Character tables
However, if \lst@UM is equivalent to \@empty, the sharpness is extended to the '#' character (cat code 12). Furthermore, the argument can be arbitrary; sometimes it's the next character of the source code, sometimes it's some list package code, e.g.
On the output
We use two counters because this simplifies tab handling: \lst@posis non-positive representative of 'length of line printed so far' modulotabsize. The first order of the latter is initialized with hstyle initiif is not equivalent to \relax.
Delimiters
The arguments h2ndi and/orhresti are empty if the delimiter is strictly less than three characters. By default, the package takes the delimiter(s), makes the characters active, and places them after \lst@hnamei[DM]@htypei.
Getting the kernel run
Depending on whether the type chosen by the user begins with hextra prefixi, the first two or the last control sequences are used. For example, \lst@Extend \a \b merges the contents of the two macros and stores them globally in\a.
Character tables manipulated 82
At the beginning of each list we set the counter to zero, at the end of the list we display a message about the current value, and each processed point moves the counter by one. To distinguish procedure-like macros from data macros, procedure macro names use capital letters with each starting word, eg \lst@AddTo.
Flow of control
Catcode changes
Otherwise, we say that ^^A=chr(1) is the small version of the second character, and we test the next argument, and so on. This\endgroup restores the catcodes of chr(0)–chr(8), but not the catcodes of the characters inside\lst@MakeActive@, since they have already been read.
Applications to 13.3
The next definition has been used above to check for $..$ and the following prevents the math content from being converted.
Driver file handling*
We define the element (in case of need), and\endgroupsets some catcodes and \lst@if, i.e. we get the aspect argument and (if not empty) load the aspects immediately if called by a public command, or expand the list of required aspects, or simply ignore the argument if the element is left undefined.
Aspect commands
If and only if the boolean value is true, the hook material is executed globally. The first is not equivalent in case the second argument is a single control sequence (= non-closing), and the second is not in the case of a second argument with parentheses.
Interfacing with keyval
The equals sign has been added following a bug report from Bekir Karaoglu - babel's active equals sign conflicts with keyval's usage.
Internal modes
If we have reached \relax, we have also found the last element: we execute #1 and gobble{#2}={\relax}na\fi.
Diverse helpers
Now - this means after a bug report by Rolf Niepraschk - \lst@lastother is also saved and restored. Additionally we have\lst@lostspace which is the difference between the current and desired line widths.
Low- and mid-level output
Delaying output means storing the string somewhere and pushing it when needed. If it equals the stored definition, we place the delayed characters before the character string (concatenate them) since there was no letter-to- or letter-to-letter jump.
Column formats
Otherwise we locally reset the current string, concatenate this empty string with the delayed one and execute it. The fixed formats use\lst@leftinserand\lst@righthss, while the flexible formats require \lst@leftinserand\lst@rightinsert.
New lines
High-level output
Otherwise (no printed characters) we only need to move the \lst@lostspace inserted by\lst@OutputTokenabove and update the column.
Dropping the whole output . 113
In this section we define how the basic character classes behave before moving on to choosing character tables and how to specialize characters.
Whitespaces
If the line is empty, we check for characters in the output queue. Also, \lst@whitespacetrue has been moved after \lst@PrintToken so that the token printer can properly check whether it prints whitespace or not; this prevented the spaceflexiblecolumn setting from working correctly.
Character tables
- The standard table
- National characters
- Catcode problems
- Adjusting the table
In addition, we have \def\lst@um_{\lst@UM _}, where the second underscore has the usual meaning. We also need to use the '\lst@UMconstruction' here, as extended characters can often appear in word = identifiers.
Delimiters
Strings
Comments
PODs
Tags
Replacing input
Compared to the others, we set \lst@ifnotag and only enter tag mode when we are not in tag mode.
Escaping to L A TEX
1780\global\let\lst@ifsensitivedefed\iffalse % init % \global All keyword tests use the following three arguments. Note: The third last line uses the fact that keyword lists (not the keyword list list) are already capitalized if keywords are insensitive.
Installing tests
This way we can keep track of keywords: If keywords or sensitive keywords change, we define the old keywords (= . globally defined) and define the true ones. While we don't reach the end of the global list, we look to see if the keyword class#4#5 is still in use or should be undefined.
Classes and families
First we define keys and style keyhstyle nameiif and only if name is not empty. If we haven't reached the end of the class list, we define a temporary macro that removes all occurrences.
Main families and classes
Christian Schneider pointed out that the original implementation was broken when the identifier was preceded by an "other" character. Now we define a new delimiter for directives: We only go into 'directive mode' in the first column.
Keyword comments
We introduce a new string type (thanks to R. Isernhagen), which. 2207\lst@AddTo\lst@stringtypes{,directive}. is only active in \lst@CD: mode. Note the last argument\lst@InstallKeywords: The job test is installed in the Output hook and not in DetectKeywords.
Export of identifiers
The above default definition of \lst@indexstyle has been moved outside the hook following a bug report by Ulrich G. We are now dealing with commands used in defining and selecting programming languages, especially aliases.
Format definitions*
The parser uses \lst@fmtSplit to cut a format definition into items, items into 'input' and 'output', and 'output' into 'pre' and 'post'.
Line numbers
The label number is initialized and we ensure correct line numbers for continued listings. The counter advances each line and if that counter is zero, we print a line number and decrement the counter by\lst@stepnumber.
Line shape and line breaking 171
Added top corner after foul report from Magnus Lewis-Smith and Jos'e Romildo Malaquias respectively. A \raggedright above has been replaced by manually setting the values following a bug report from Morten Høgholm.
Macro use for make
The following code was moved here from the Init hook following a bug report by Rolf Niepraschko. The setting\lst@AddToHook{PreSet}{\let\lst@float\relax} was changed at the request of Tanguy Fautr´e.
Init and EOL
I added the \par\nointerlineskip (and later removed \nointerlineskip again) after receiving a bug report from Aidan Philip Heerdegen. Note that we test for FF (and tabs below) against a macro containing \lst@ProcessFormFeed.
List of listings
Any package that defines a list of floats adds a command to\float@addtolists, and then packages (such as the KOMA script document classes) that want to add things to all lists of floats can use it, without having to know all the possible lists that might exist.
Inline listings
Processing inline listings
In the first case, the given character ends the inline list, and EOL within such a list ends it immediately and produces an error message. In the second case, we get all characters up to #1, make those characters active, execute (typeset) them, and end the list (all via temporary macro).
Short inline listing envi-
The input command
The environment
Low-level processing
Defining new environments 205
Environments for notes
Extensions to doc
The lstsample environment 212
Scanning languages
Bubble sort
Omega support
LGrind
