From a494a509f3f4a13a450c898488155f7aa5353bd3 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Thu, 1 Feb 2024 03:00:51 +0000 Subject: CTAN sync 202402010300 --- support/TeX4ht/source/ChangeLog | 9 + support/TeX4ht/source/tex4ht-html4.tex | 6 +- support/TeX4ht/source/tex4ht-mathml.tex | 4 +- support/latexmk/CHANGES | 11 + support/latexmk/INSTALL | 2 +- support/latexmk/README | 4 +- support/latexmk/latexmk.1 | 14 +- support/latexmk/latexmk.pdf | Bin 230284 -> 230287 bytes support/latexmk/latexmk.pl | 1143 +++---- support/latexmk/latexmk.txt | 3362 ++++++++++----------- support/splint/INSTALL | 10 +- support/splint/Makefile | 33 +- support/splint/README | 7 +- support/splint/TODO | 22 +- support/splint/VERSION | 2 +- support/splint/cweb/Makefile | 131 +- support/splint/cweb/bo.w | 582 ++-- support/splint/cweb/bs.w | 60 +- support/splint/cweb/checklists.w | 2 +- support/splint/cweb/common.w | 38 +- support/splint/cweb/fk.w | 4 +- support/splint/cweb/fo.w | 185 +- support/splint/cweb/lo.w | 100 +- support/splint/cweb/mkeparser.w | 8 +- support/splint/cweb/mkscanner.w | 2 +- support/splint/cweb/np.w | 34 +- support/splint/cweb/philosophy.w | 37 +- support/splint/cweb/references.w | 2 +- support/splint/cweb/so.w | 133 +- support/splint/cweb/splint.w | 258 +- support/splint/cweb/ssffo.w | 123 - support/splint/doc/ldman.pdf | Bin 718042 -> 745685 bytes support/splint/doc/splint.pdf | Bin 1141608 -> 1157534 bytes support/splint/examples/count/count.sty | 2 +- support/splint/examples/expression/Makefile | 4 +- support/splint/examples/expression/etoks.sty | 2 +- support/splint/examples/expression/expression.sty | 2 +- support/splint/examples/expression/expression.w | 18 +- support/splint/examples/ld/Makefile | 47 +- support/splint/examples/ld/ldexample.hw | 16 +- support/splint/examples/ld/ldgram.w | 108 +- support/splint/examples/ld/ldgramo.w | 9 +- support/splint/examples/ld/ldint.sty | 9 +- support/splint/examples/ld/ldlex.w | 519 ++-- support/splint/examples/ld/ldlexo.w | 14 +- support/splint/examples/ld/ldman.w | 297 +- support/splint/examples/ld/ldnp.w | 49 +- support/splint/examples/ld/ldnump.w | 10 +- support/splint/examples/ld/ldtexlex.sty | 4 +- support/splint/examples/ld/ldunion.sty | 242 +- support/splint/examples/ld/lstokenset.sty | 2 +- support/splint/examples/ld/ltokenset.sty | 2 +- support/splint/examples/symbols/Makefile | 8 +- support/splint/examples/symbols/slimbo.sty | 2 +- support/splint/examples/symbols/symbols.w | 46 +- support/splint/examples/symbols/symfm.sty | 2 +- support/splint/examples/symbols/symmap.sty | 5 +- support/splint/examples/symbols/symtoks.sty | 2 +- support/splint/examples/symbols/symtricks.sty | 2 +- support/splint/examples/types/Makefile | 2 +- support/splint/examples/types/basic.sty | 2 +- support/splint/examples/types/test.sty | 2 +- support/splint/examples/types/tree.sty | 2 +- support/splint/examples/xxpression/Makefile | 8 +- support/splint/examples/xxpression/xtoks.sty | 3 +- support/splint/examples/xxpression/xxpression.sty | 2 +- support/splint/examples/xxpression/xxpression.w | 39 +- support/splint/examples/xxpression/xymmap.sty | 5 +- support/splint/extras/texmf/macros/protcode.tex | 83 - support/splint/makefile.inc | 60 +- support/splint/other/texmf/macros/protcode.tex | 83 + support/splint/scripts/bindx.pl | 30 +- support/splint/scripts/brack.pl | 213 +- support/splint/scripts/cslist.pl | 2 +- support/splint/scripts/misccw.pl | 2 +- support/splint/scripts/unline.pl | 21 +- support/splint/tex/btokenset.sty | 8 +- support/splint/tex/dcols.sty | 454 ++- support/splint/tex/flex.sty | 124 +- support/splint/tex/fonts/idssbx10.vpl | 911 ++++++ support/splint/tex/fonts/idssbx12.vpl | 908 ++++++ support/splint/tex/fonts/idssbx5.vpl | 908 ++++++ support/splint/tex/fonts/idssbx6.tfm | Bin 0 -> 1280 bytes support/splint/tex/fonts/idssbx6.vf | Bin 0 -> 828 bytes support/splint/tex/fonts/idssbx6.vpl | 1310 ++++++++ support/splint/tex/fonts/idssbx7.tfm | Bin 0 -> 1296 bytes support/splint/tex/fonts/idssbx7.vf | Bin 0 -> 828 bytes support/splint/tex/fonts/idssbx7.vpl | 913 ++++++ support/splint/tex/fonts/idssbx8.tfm | Bin 0 -> 1280 bytes support/splint/tex/fonts/idssbx8.vf | Bin 0 -> 828 bytes support/splint/tex/fonts/idssbx8.vpl | 1310 ++++++++ support/splint/tex/fonts/idssbx9.tfm | Bin 0 -> 1296 bytes support/splint/tex/fonts/idssbx9.vf | Bin 0 -> 828 bytes support/splint/tex/fonts/idssbx9.vpl | 1310 ++++++++ support/splint/tex/fretokenset.sty | 2 +- support/splint/tex/ftokenset.sty | 3 +- support/splint/tex/gindex.sty | 164 +- support/splint/tex/grabstates.sty | 16 +- support/splint/tex/hext.sty | 16 + support/splint/tex/limbo.sty | 454 ++- support/splint/tex/noweb.sty | 186 +- support/splint/tex/stokenset.sty | 3 +- support/splint/tex/trt1.sty | 4 +- support/splint/tex/xarithm.sty | 4 +- support/splint/tex/yxunion.sty | 33 - support/splint/tex/yy.sty | 26 +- support/splint/tex/yybootstrap.sty | 7 +- support/splint/tex/yycommon.sty | 716 ++++- support/splint/tex/yydebug.sty | 18 +- support/splint/tex/yyfaststack.sty | 94 +- support/splint/tex/yyinit.sty | 520 +--- support/splint/tex/yyinput.sty | 219 +- support/splint/tex/yymisc.sty | 435 +-- support/splint/tex/yynested.sty | 2 +- support/splint/tex/yyparse.sty | 78 +- support/splint/tex/yypretty.sty | 7 +- support/splint/tex/yystype.sty | 5 +- support/splint/tex/yytexlex.sty | 208 +- support/splint/tex/yyunion.sty | 1314 +++++--- 119 files changed, 15435 insertions(+), 5565 deletions(-) delete mode 100644 support/splint/cweb/ssffo.w delete mode 100644 support/splint/extras/texmf/macros/protcode.tex create mode 100644 support/splint/other/texmf/macros/protcode.tex create mode 100644 support/splint/tex/fonts/idssbx10.vpl create mode 100644 support/splint/tex/fonts/idssbx12.vpl create mode 100644 support/splint/tex/fonts/idssbx5.vpl create mode 100644 support/splint/tex/fonts/idssbx6.tfm create mode 100644 support/splint/tex/fonts/idssbx6.vf create mode 100644 support/splint/tex/fonts/idssbx6.vpl create mode 100644 support/splint/tex/fonts/idssbx7.tfm create mode 100644 support/splint/tex/fonts/idssbx7.vf create mode 100644 support/splint/tex/fonts/idssbx7.vpl create mode 100644 support/splint/tex/fonts/idssbx8.tfm create mode 100644 support/splint/tex/fonts/idssbx8.vf create mode 100644 support/splint/tex/fonts/idssbx8.vpl create mode 100644 support/splint/tex/fonts/idssbx9.tfm create mode 100644 support/splint/tex/fonts/idssbx9.vf create mode 100644 support/splint/tex/fonts/idssbx9.vpl delete mode 100644 support/splint/tex/yxunion.sty (limited to 'support') diff --git a/support/TeX4ht/source/ChangeLog b/support/TeX4ht/source/ChangeLog index a268359b24..427adcd3d4 100644 --- a/support/TeX4ht/source/ChangeLog +++ b/support/TeX4ht/source/ChangeLog @@ -1,3 +1,12 @@ +2024-01-30 Michal Hoftich + + * tex4ht-html4.tex (html4.4ht): fixed nested links in footnotes. + https://tex.stackexchange.com/a/708335/2891 + + * tex4ht-mathml.tex (mathml.4ht): prevent spurious opening

tags + in \boxed commands. + https://tex.stackexchange.com/a/708306/2891 + 2024-01-29 Michal Hoftich * tex4ht-ooffice.tex (ooffice-mml.4ht), diff --git a/support/TeX4ht/source/tex4ht-html4.tex b/support/TeX4ht/source/tex4ht-html4.tex index 82cd70f74a..38ac28f4d8 100644 --- a/support/TeX4ht/source/tex4ht-html4.tex +++ b/support/TeX4ht/source/tex4ht-html4.tex @@ -1,4 +1,4 @@ -% $Id: tex4ht-html4.tex 1453 2024-01-24 22:08:34Z karl $ +% $Id: tex4ht-html4.tex 1457 2024-01-30 20:48:28Z michal_h21 $ % Compile 4 times: latex tex4ht-html4 % Copy html4.4ht into the work directory before all but the last compilation. % @@ -5119,8 +5119,8 @@ The `index=i' provides the initial setting. \<<< \Configure{footnotetext} {|% - |\Link{}{|}% - \NoFonts\AnchorLabel + |\AnchorLabel\Link{}{|}% + \NoFonts% } {\EndNoFonts \EndLink|} {|} diff --git a/support/TeX4ht/source/tex4ht-mathml.tex b/support/TeX4ht/source/tex4ht-mathml.tex index b5cc838ebd..acdc463ecb 100644 --- a/support/TeX4ht/source/tex4ht-mathml.tex +++ b/support/TeX4ht/source/tex4ht-mathml.tex @@ -1,4 +1,4 @@ -% $Id: tex4ht-mathml.tex 1455 2024-01-29 13:45:00Z michal_h21 $$ +% $Id: tex4ht-mathml.tex 1456 2024-01-30 16:31:58Z michal_h21 $$ % compile 3 times: latex tex4ht-mathltx % or xhlatex tex4ht-mathltx "html,3,sections+" % @@ -5012,7 +5012,7 @@ tail>>> \<<< \Configure{boxed} {\ifmathml \Tg<\a:mathml menclose \a:mathml notation="box">\Tg<\a:mathml mrow>% - \else \HCode{}\IgnorePar\fi} + \else \HCode{}\fi\IgnorePar} {\ifmathml \Tg\Tg% \else \HCode{}\fi} \Css{.boxed{border: 1px solid black; padding-left:2px; diff --git a/support/latexmk/CHANGES b/support/latexmk/CHANGES index 84a8944de9..1a2cc620fd 100644 --- a/support/latexmk/CHANGES +++ b/support/latexmk/CHANGES @@ -895,3 +895,14 @@ From v. 4.82 to 4.82a about "Use of uninitialized value $_" were given, and some corresponding dependencies were incorrectly treated. +From v. 4.82a to 4.83 + Fix bug that sometimes biber is incorrectly run after a *latex run + results in an error, with biber then giving an error. + Fix problem that if -gg is used with multiple files specified on command + line, then generated files are deleted for all by the last file + compiled. (So that -gg wasn't working as intended in this case.) + Fixed some bugs with incorrect variable scope. (These bugs gave + incomprehensible error messages about undefined variables!) + Restrict warning diagnostics about ^^ constructs in aux file to those + involving non-trivial Unicode characters, as against things like ^^M. + diff --git a/support/latexmk/INSTALL b/support/latexmk/INSTALL index 8e7a73304a..1eca0ad101 100644 --- a/support/latexmk/INSTALL +++ b/support/latexmk/INSTALL @@ -1,6 +1,6 @@ INSTALLING latexmk ================== - (Version 4.82a, 10 Jan. 2024) + (Version 4.83, 31 Jan. 2024) John Collins Physics Department diff --git a/support/latexmk/README b/support/latexmk/README index 4d34afe9ff..466ea9e3d1 100644 --- a/support/latexmk/README +++ b/support/latexmk/README @@ -1,5 +1,5 @@ -Latexmk, version 4.82a, 10 Jan 2024 ------------------------------------ +Latexmk, version 4.83, 31 Jan 2024 +---------------------------------- Latexmk completely automates the process of generating a LaTeX document. Essentially, it is a highly specialized cousin of the diff --git a/support/latexmk/latexmk.1 b/support/latexmk/latexmk.1 index cac97f47f1..85fc6ed20e 100644 --- a/support/latexmk/latexmk.1 +++ b/support/latexmk/latexmk.1 @@ -1,10 +1,10 @@ -.TH LATEXMK 1 "10 January 2024" "" +.TH LATEXMK 1 "31 January 2024" "" .SH NAME latexmk \- generate LaTeX document .SH SYNOPSIS .B latexmk [options] [file ...] .SH DESCRIPTION -.I Latexmk +.I Latexmk completely automates the process of compiling a LaTeX document. Essentially, it is like a specialized relative of the general \fImake\fR utility, but one which determines dependencies @@ -12,7 +12,7 @@ automatically and has some other very useful features. In its basic mode of operation \fIlatexmk\fR is given the name of the primary source file for a document, and it issues the appropriate sequence of commands to generate a .dvi, .ps, .pdf and/or hardcopy version of the -document. +document. .PP By default \fIlatexmk\fR will run the commands necessary to generate a .dvi file, which copies the behavior of earlier versions when only @@ -167,7 +167,7 @@ the behavior of \fIlatex\fR etc, and deals with problems that occasionally result from filenames that have been incorrectly quoted on the command line. \fIIn addition\fR, under Microsoft Windows, the forward slash character "\\" is a directory separator, so \fIlatexmk\fR replaces it -by a backward slash "/", which is also a legal directory separator in +by a forward slash "/", which is also a legal directory separator in Windows, and is accepted by \fIlatex\fR etc. .TP @@ -2226,7 +2226,7 @@ Array of regular expressions specifying messages in log file that are officially treated as warnings rather than errors by *latex, but which a user may treat as errors: See \fI$bad_warning_is_error\fR. -Currently the default set of these warnings is those about \\end occuring +Currently the default set of these warnings is those about \\end occurring inside constructs. .TP @@ -2776,7 +2776,7 @@ look at the definition of \fI@file_not_found\fR in the latexmk.pl file. In the regular expression, the string for the name of the missing file should be enclosed in parentheses. That carries the implication that after -latexmk gets a succesful match to the pattern, the variable $1 is set to +latexmk gets a successful match to the pattern, the variable $1 is set to the filename, which is then picked up by latexmk. If you happen to encounter a package that gives a missing file message of a @@ -4469,7 +4469,7 @@ e-mail addresses are not written in their standard form to avoid being harvested too easily.) .SH AUTHOR Current version, by John Collins -(Version 4.82a). +(Version 4.83). Report bugs etc to his e-mail (jcc8 at psu.edu). Released version can be obtained from CTAN: diff --git a/support/latexmk/latexmk.pdf b/support/latexmk/latexmk.pdf index f18c22657c..19f863e8c7 100644 Binary files a/support/latexmk/latexmk.pdf and b/support/latexmk/latexmk.pdf differ diff --git a/support/latexmk/latexmk.pl b/support/latexmk/latexmk.pl index 0b7e0ecb32..44ee6a05a7 100755 --- a/support/latexmk/latexmk.pl +++ b/support/latexmk/latexmk.pl @@ -1,12 +1,8 @@ #!/usr/bin/env perl use warnings; +use strict; - -# 9, 10 Jan 2024 Fix localization of $_ in while loops that read file. -# That fixes problems with use of %hash_calc_ignore_pattern, -# which gave uninitialized $_ warnings. - -## Copyright John Collins 1998-2023 +## Copyright John Collins 1998-2024 ## (username jcc8 at node psu.edu) ## (and thanks to David Coppit (username david at node coppit.org) ## for suggestions) @@ -45,13 +41,14 @@ use warnings; ## 20 = probable bug ## or retcode from called program. +our ($my_name, $My_name, $version_num, $version_details); BEGIN { # Make sure the following are available when printing diagnostics in BEGIN # blocks. $my_name = 'latexmk'; $My_name = 'Latexmk'; - $version_num = '4.82a'; - $version_details = "$My_name, John Collins, 10 Jan. 2024. Version $version_num"; + $version_num = '4.83'; + $version_details = "$My_name, John Collins, 31 Jan. 2024. Version $version_num"; } use Config; @@ -63,7 +60,7 @@ use File::Spec::Functions qw( catfile file_name_is_absolute rel2abs ); # It's either File::Glob::bsd_glob or File::Glob::glob # The first does not exist in old versions of Perl, while the second # is deprecated in more recent versions and will be removed -$have_bsd_glob = 0; +our $have_bsd_glob = 0; use File::Glob; if ( eval{ File::Glob->import('bsd_glob'); 1; } ) { # Success in importing bsd_glob @@ -116,7 +113,8 @@ BEGIN { # use Encode qw( decode encode ); use Unicode::Normalize; -use utf8; # For UTF-8 strings in **this** script +use utf8; # Strings are coded in UTF-8 in this file, stored internally + # decoded into Perl's internal character representation. use feature 'unicode_strings'; use feature 'say'; @@ -149,8 +147,7 @@ use feature 'say'; # My default CSs: UTF-8 -our $CS_system; -$CS_system = 'UTF-8'; +our $CS_system = 'UTF-8'; # Quick short cut for tests of whether conversions needed: our $no_CP_conversions = 1; @@ -205,138 +202,13 @@ END { ######################################################## -#************************************************************ -#************************************************************ -# Unicode manipuation and normalization -# Notes about Perl strings: -# 1. Strings have a flag utf8. -# a. If the utf8 flag is on, the string is to be interpreted as a sequence -# of code points. -# When "use utf8;" is used, a string containing non-ASCII characters -# has the utf8 flag set. -# If 'no bytes;' is in effect, the ordinal value for each item in the -# string is the Unicode code point value. -# b. If the utf8 flag is off for a string, the string is a sequence of -# bytes, to be interpreted according to whatever CS the user happens -# to choose to use. -# c. The utf8 flag is NOT to be interpreted as saying that the string is -# encoded as UTF-8, even though under the hood that may be the case. -# d. Indeed, setting 'use bytes;' appears to expose the internal -# byte-level representation of a string with the utf8 flag set, and -# that appears to be UTF-8. -# 2. The utf8 flag is quite confusing in its meaning. -# 3. When encode is applied to a string whose utf8 flag is on, the result -# is a string with the utf8 flag off, and the result consists of a sequence -# of bytes in the chosen encoding scheme, which may be chosen as UTF-8. -# 4. Strings received from the command line have the utf8 flag off and are -# encoded in whatever CS the OS/terminal is using. -# 5. When a string is supplied to print (or c), by default: -# a. If the utf8 flag is off or if 'use bytes;' is in effect, then the -# string is sent as a sequence of bytes. They are UTF-8 coded if -# the utf8 flag is on and 'use bytes;' is in effect. -# b. If the utf8 flag is on and if 'no bytes;' is in effect, then mostly -# garbage results for non-ASCII characters; the string must first be -# encoded as a byte string, in the CS suitable for the OS. -# c. Correct results are obtained when the utf8 flag is on and 'no bytes' -# is used when the binmode for the file handle is set suitably. -# 6. Generally OS calls and interactions with the OS need encoded byte strings. -# 7. Even more generally, interaction with the external world, including file -# contents is in terms of byte strings, with some CS chosen by default, by -# the user, or the OS. Unix-like OSs: Default is UTF-8, but as much by -# convention as by a requirement of the OS. - -#------------------------------------- - -sub utf8_to_mine { - # Given string encoded in UTF-8, return encoded string in my current CS. - # Don't use Encode::from_to, which does in-place conversion. - if ($no_CP_conversions) { return $_[0]; } - else { return encode( $CS_system, decode('UTF-8', $_[0])); } -} - -#------------------------------------- - -sub utf8_to_mine_errors { - # Given string encoded in UTF-8, return encoded string in my current CS. - # Don't use Encode::from_to, which does in-place conversion. - # Assume coding of input string is correctly UTF-8, but - # check for correct encoding in CS_system. - # Error message is returned in $@. No error => $@ is null string. - # (Same style as eval!) - $@ = ''; - if ($no_CP_conversions) { return $_[0]; } - else { - my $result = ''; - eval { - $result = encode( $CS_system, - decode('UTF-8', $_[0]), - Encode::FB_CROAK | Encode::LEAVE_SRC - ); - }; - return $result; - } -} - -#------------------------------------- - -sub config_to_mine { - # Ensure that configuration strings about files and directories are - # encoded in system CS. - # Configuration strings set in an rc file SHOULD either be: - # a. ASCII only, with Perl's utf8 flag off. - # b. Containing non-ASCII characters, with utf8 flag on. - # These need to be converted to encoded strings in system CS (and - # hence with utf8 flag off). - # Configuration variables set from the command line, e.g., from an - # -outdir=... option, are already in the system CS, because that is - # how strings are passed on the command line. - # So we just need to do a conversion for strings with utf8 flag on: - foreach ( $out_dir, $aux_dir, @default_files, @default_excluded_files ) { - if (utf8::is_utf8($_)) { $_ = encode( $CS_system, $_ ); } - } -} #END config_to_mine - -#************************************************************ - -sub mine_to_utf8 { - # Given string encoded in my current CS, return utf-8 encoded string. - # Don't use Encode::from_to, which does in-place conversion. - if ($no_CP_conversions) { return $_[0]; } - else { return encode( 'UTF-8', decode($CS_system, $_[0])); } -} - -#------------------------------------- - -sub is_valid_utf8 { - eval { decode( 'UTF-8', $_[0], (Encode::FB_CROAK | Encode::LEAVE_SRC ) ); }; - if ($@) { return 0; } - else { return 1; } -} - -#------------------------------------- - -sub fprint8 { - # Usage: fprint8( handle, data array) - # Write to file converting from my CS to UTF-8 - my $fh = shift; - print $fh mine_to_utf8( join( '', @_ ) ); -} - -#------------------------------------- - -################################################################ - - - - ################################################################ ################################################################ #============ Deal with how I'm invoked: name and CL args: # Name that I'm invoked with indicates default behavior (latexmk # v. pdflatexmk, etc): -(our $invoked_name) = fileparseA($0); - +our ($invoked_name) = fileparseA($0); # Save name, since I override it if I don't recognize it our $invoked_kind = $invoked_name; print "$My_name: Invoked as '$invoked_name'\n" @@ -347,7 +219,7 @@ print "$My_name: Invoked as '$invoked_name'\n" # rc files and CL args, no values are set for any of these variables. # Thus default compilation for latexmk is by latex, # for pdflatexmk is by pdflatex, etc. -%compilation_defaults = +our %compilation_defaults = ( 'latexmk' => [1,0,0,0], 'lualatexmk' => [0,0,4,0], 'pdflatexmk' => [0,0,1,0], @@ -360,17 +232,13 @@ unless (exists $compilation_defaults{$invoked_name}) { $invoked_name = 'latexmk' ################################################################ ################################################################ -# The following variables are assigned once and then used in symbolic -# references, so we need to avoid warnings 'name used only once': -use vars qw( $dvi_update_command $ps_update_command $pdf_update_command - $aux_dir_requested $out_dir_requested ); # Translation of signal names to numbers and vv: -%signo = (); -@signame = (); +our %signo = (); +our @signame = (); if ( defined $Config{sig_name} ) { my $i = 0; - foreach $name (split('\s+', $Config{sig_name})) { + foreach my $name (split('\s+', $Config{sig_name})) { $signo{$name} = $i; $signame[$i] = $name; $i++; @@ -384,11 +252,11 @@ else { # Line length in log file that indicates wrapping. # This number EXCLUDES line-end characters, and is one-based. # It is the parameter max_print_line in the TeX program. (tex.web) -$log_wrap = 79; +our $log_wrap = 79; # Expected biggest construct in log file in bytes. # Use to limit number of (potentially) wrapped lines to combine into single line. -$max_log_construct = 600; +our $max_log_construct = 600; # Whether to search for ^^ notation in log file for non-7-bit characters, # and convert to bytes. (Note: ^^ notation is produced by hilatex in @@ -397,7 +265,7 @@ $max_log_construct = 600; # gives it if -translate-file=empty is used.) # Should also do same with aux files, but I've not done that yet. ???? # fls file is always UTF-8. -$conv_hathat = 1; +our $conv_hathat = 1; ######################################################################### ## Default parsing and file-handling settings @@ -410,7 +278,7 @@ $conv_hathat = 1; ## Add items by push, e.g., ## push @file_not_found, '^No data file found `([^\\\']*)\\\''; ## will give match to line starting "No data file found `filename'" -@file_not_found = ( +our @file_not_found = ( '^No file\\s+(.*)\\.$', '^No file\\s+(.+)\s*$', '^\\! LaTeX Error: File `([^\\\']*)\\\' not found\\.', @@ -428,13 +296,13 @@ $conv_hathat = 1; # that we will call bad warnings. They are not treated as errors by # *latex, but depending on the $bad_warning_is_error setting # we will treat as if they were actual errors. -@bad_warnings = ( +our @bad_warnings = ( # Remember: \\ in perl inside single quotes gives a '\', so we need # '\\\\' to get '\\' in the regexp. '^\(\\\\end occurred when .* was incomplete\)', '^\(\\\\end occurred inside .*\)', ); -$bad_warning_is_error = 0; +our $bad_warning_is_error = 0; # Characters that we won't allow in the name of a TeX file. # Notes: Some are disallowed by TeX itself. @@ -442,12 +310,12 @@ $bad_warning_is_error = 0; # '$' results in possible variable substitution by kpsewhich called from tex. # '"' gets special treatment. # See subroutine test_fix_texnames and its call for their use. -$illegal_in_texname = "\x00\t\f\n\r\$%\\~\x7F"; +our $illegal_in_texname = "\x00\t\f\n\r\$%\\~\x7F"; # Whether to normalize aux_dir and out_dir where possible. # This is important when these directories aren't subdirectories of the cwd, # and TeXLive's makeindex and/or bibtex are used. -$normalize_names = 2; # Strongest kind. +our $normalize_names = 2; # Strongest kind. ## Hash mapping file extension (w/o period, e.g., 'eps') to a single regexp, # whose matching by a line in a file with that extension indicates that the @@ -463,13 +331,13 @@ $normalize_names = 2; # Strongest kind. # or (b) its hash changes # So it is useful to ignore lines in the hash calculation only if they # are of a fixed size (as with a date/time stamp). -%hash_calc_ignore_pattern =(); +our %hash_calc_ignore_pattern =(); # Specification of templates for extra rules. # See subroutine rdb_initialize_rules for examples of rule templates, and # how they get used to construct rules. # (Documentation obviously needs to be improved!) -%extra_rule_spec = (); +our %extra_rule_spec = (); #??????? !!!!!!!!! If @aux_hooks and @latex_file_hooks are still needed, @@ -513,42 +381,44 @@ $hooks{latex_file_hooks} = \@latex_file_hooks; ## Which TeX distribution is being used ## E.g., "MiKTeX 2.9", "TeX Live 2018" ## "" means not determined. Obtain from first line of .log file. -$tex_distribution = ''; +our $tex_distribution = ''; # List of known *latex rules: -%possible_primaries = ( 'dvilualatex' => 'primary', 'hilatex' => 'primary', +our %possible_primaries = ( 'dvilualatex' => 'primary', 'hilatex' => 'primary', 'latex' => 'primary', 'lualatex' => 'primary', 'pdflatex' => 'primary', - 'xelatex' => 'primary' ); + 'xelatex' => 'primary' ); +# Command strings for them: +our ($dvilualatex, $hilatex, $latex, $lualatex, $pdflatex, $xelatex ); std_tex_cmds(); # Possible code to execute by *latex before inputting source file. # Not used by default. -$pre_tex_code = ''; +our $pre_tex_code = ''; ## Default switches: -$hilatex_default_switches = ''; -$latex_default_switches = ''; -$pdflatex_default_switches = ''; -$dvilualatex_default_switches = ''; -$lualatex_default_switches = ''; +our $hilatex_default_switches = ''; +our $latex_default_switches = ''; +our $pdflatex_default_switches = ''; +our $dvilualatex_default_switches = ''; +our $lualatex_default_switches = ''; # Note that xelatex is used to give xdv file, not pdf file, hence # we need the -no-pdf option. -$xelatex_default_switches = '-no-pdf'; +our $xelatex_default_switches = '-no-pdf'; ## Switch(es) to make them silent: -$hilatex_silent_switch = '-interaction=batchmode'; -$latex_silent_switch = '-interaction=batchmode'; -$pdflatex_silent_switch = '-interaction=batchmode'; -$dvilualatex_silent_switch = '-interaction=batchmode'; -$lualatex_silent_switch = '-interaction=batchmode'; -$xelatex_silent_switch = '-interaction=batchmode'; +our $hilatex_silent_switch = '-interaction=batchmode'; +our $latex_silent_switch = '-interaction=batchmode'; +our $pdflatex_silent_switch = '-interaction=batchmode'; +our $dvilualatex_silent_switch = '-interaction=batchmode'; +our $lualatex_silent_switch = '-interaction=batchmode'; +our $xelatex_silent_switch = '-interaction=batchmode'; # Whether to emulate -aux-directory, so we can use it on system(s) (TeXLive) # that don't support it: -$emulate_aux = 1; +our $emulate_aux = 1; # Whether emulate_aux had to be switched on during a run: -$emulate_aux_switched = 0; +our $emulate_aux_switched = 0; #-------------------- # Specification of extensions/files that need special treatment, @@ -557,25 +427,25 @@ $emulate_aux_switched = 0; # %input_extensions maps primary_rule_name to pointer to hash of file extensions # used for extensionless files specified in the source file by constructs # like \input{file} \includegraphics{file} -%input_extensions = (); +our %input_extensions = (); set_input_ext( 'latex', 'tex', 'eps' ); set_input_ext( 'pdflatex', 'tex', 'jpg', 'pdf', 'png' ); $input_extensions{lualatex} = $input_extensions{pdflatex}; $input_extensions{xelatex} = $input_extensions{pdflatex}; # Save these values as standards to be used when switching output, # i.e., when actual primary rule differs from standard. -%standard_input_extensions = %input_extensions; +our %standard_input_extensions = %input_extensions; # Possible extensions for main output file of *latex: -%allowed_output_ext = ( ".dvi" => 1, ".xdv" => 1, ".pdf" => 1 ); +our %allowed_output_ext = ( ".dvi" => 1, ".xdv" => 1, ".pdf" => 1 ); # Extensions etc, of special use by latexmk -$save_error_suffix = '-SAVE-ERROR'; # Suffix to be added to filename, when an +our $save_error_suffix = '-SAVE-ERROR'; # Suffix to be added to filename, when an # erroneous file is saved insted of being deleted. -$fdb_ext = 'fdb_latexmk'; # Extension for the file for latexmk's +our $fdb_ext = 'fdb_latexmk'; # Extension for the file for latexmk's # file-database # Make it long to avoid possible collisions. -$fdb_ver = 4; # Version number for kind of fdb_file. +our $fdb_ver = 4; # Version number for kind of fdb_file. # Variables relevant to specifying cleanup. @@ -609,28 +479,28 @@ $fdb_ver = 4; # Version number for kind of fdb_file. # bbl files get special treatment because their deletion is conditional # and because of the possibility of extra bibtex/biber rules with # non-standard basename. -@generated_exts = ( 'aux', 'bcf', 'bcf'.$save_error_suffix, 'fls', +our @generated_exts = ( 'aux', 'bcf', 'bcf'.$save_error_suffix, 'fls', 'idx', 'ind', 'lof', 'lot', 'out', 'run.xml', 'toc', 'blg', 'ilg', 'log', 'xdv' ); # N.B. 'out' is generated by hyperref package -$clean_ext = ""; # For backward compatibility: Space separated +our $clean_ext = ""; # For backward compatibility: Space separated # extensions to be added to @generated_exts after # startup (and rc file reading). # Extensions of files to be deleted by -C, but aren't normally included # in the small clean up by -c. Analogous to @generated_exts and $clean_ext, # except that pattern rules (with %R) aren't applied. -@final_output_exts = ( 'dvi', 'dviF', 'hnt', 'ps', 'psF', 'pdf', +our @final_output_exts = ( 'dvi', 'dviF', 'hnt', 'ps', 'psF', 'pdf', 'synctex', 'synctex.gz' ); -$clean_full_ext = ""; +our $clean_full_ext = ""; # Set of extra specific files to be deleted in small cleanup. These are # ones that get generated under some kinds of error conditions. All cases: # Relative to current directory, and relative to aux and out directories. -@std_small_cleanup_files = ( 'texput.log', "texput.aux", "missfont.log" ); +our @std_small_cleanup_files = ( 'texput.log', "texput.aux", "missfont.log" ); #------------------------- @@ -639,8 +509,8 @@ $clean_full_ext = ""; # Option without arg. maps to itself. # Option with arg. maps the option part to the full specification # e.g., -kpathsea-debug => -kpathsea-debug=NUMBER -%allowed_latex_options = (); -%allowed_latex_options_with_arg = (); +our %allowed_latex_options = (); +our %allowed_latex_options_with_arg = (); foreach ( ##### # TeXLive options @@ -770,21 +640,21 @@ foreach ( # These need to be stored until after the command line parsing is finished, # in case the values of $latex and/or $pdflatex change after an option # is added. -@extra_dvilualatex_options = (); -@extra_hilatex_options = (); -@extra_latex_options = (); -@extra_pdflatex_options = (); -@extra_lualatex_options = (); -@extra_xelatex_options = (); +our @extra_dvilualatex_options = (); +our @extra_hilatex_options = (); +our @extra_latex_options = (); +our @extra_pdflatex_options = (); +our @extra_lualatex_options = (); +our @extra_xelatex_options = (); ## Command to invoke biber & bibtex -$biber = 'biber %O %S'; -$bibtex = 'bibtex %O %S'; +our $biber = 'biber %O %S'; +our $bibtex = 'bibtex %O %S'; # Switch(es) to make biber & bibtex silent: -$biber_silent_switch = '--onlylog'; -$bibtex_silent_switch = '-terse'; -$bibtex_use = 1; # Whether to actually run bibtex to update bbl files. +our $biber_silent_switch = '--onlylog'; +our $bibtex_silent_switch = '-terse'; +our $bibtex_use = 1; # Whether to actually run bibtex to update bbl files. # This variable is also used in deciding whether to # delete bbl files in clean up operations. # 0: Never run bibtex. @@ -802,7 +672,7 @@ $bibtex_use = 1; # Whether to actually run bibtex to update bbl files. # # In any event bibtex is only run if the log file # indicates that the document uses bbl files. -$bibtex_fudge = 1; # Whether or not to cd to aux dir when running bibtex. +our $bibtex_fudge = 1; # Whether or not to cd to aux dir when running bibtex. # If the cd is not done, and bibtex is passed a # filename with a path component, then it can easily # happen that (a) bibtex refuses to write bbl and blg @@ -812,10 +682,10 @@ $bibtex_fudge = 1; # Whether or not to cd to aux dir when running bibtex. # method fails. ## Command to invoke makeindex -$makeindex = 'makeindex %O -o %D %S'; +our $makeindex = 'makeindex %O -o %D %S'; # Switch(es) to make makeinex silent: -$makeindex_silent_switch = '-q'; -$makeindex_fudge = 1; # Whether or not to cd to aux dir when running makeindex. +our $makeindex_silent_switch = '-q'; +our $makeindex_fudge = 1; # Whether or not to cd to aux dir when running makeindex. # Set to 1 to avoid security-related prohibition on # makeindex writing to aux_dir when it is not specified # as a subdirectory of cwd. @@ -823,73 +693,95 @@ $makeindex_fudge = 1; # Whether or not to cd to aux dir when running makeindex. ## Command to convert dvi file to pdf file directly. # Use option -dALLOWPSTRANSPARENCY so that it works with documents # using pstricks etc: -$dvipdf = 'dvipdf -dALLOWPSTRANSPARENCY %O %S %D'; +our $dvipdf = 'dvipdf -dALLOWPSTRANSPARENCY %O %S %D'; # N.B. Standard dvipdf runs dvips and gs with their silent switch, so for # standard dvipdf $dvipdf_silent_switch is unneeded, but innocuous. # But dvipdfmx can be used instead, and it has a silent switch (-q). # So implementing $dvipdf_silent_switch is useful. -$dvipdf_silent_switch = '-q'; +our $dvipdf_silent_switch = '-q'; ## Command to convert dvi file to ps file: -$dvips = 'dvips %O -o %D %S'; +our $dvips = 'dvips %O -o %D %S'; ## Command to convert dvi file to ps file in landscape format: -$dvips_landscape = 'dvips -tlandscape %O -o %D %S'; +our $dvips_landscape = 'dvips -tlandscape %O -o %D %S'; # Switch(es) to get dvips to make ps file suitable for conversion to good pdf: # (If this is not used, ps file and hence pdf file contains bitmap fonts # (type 3), which look horrible under acroread. An appropriate switch # ensures type 1 fonts are generated. You can put this switch in the # dvips command if you prefer.) -$dvips_pdf_switch = '-P pdf'; +our $dvips_pdf_switch = '-P pdf'; # Switch(es) to make dvips silent: -$dvips_silent_switch = '-q'; +our $dvips_silent_switch = '-q'; ## Command to convert ps file to pdf file. # Use option -dALLOWPSTRANSPARENCY so that it works with documents # using pstricks etc: -$ps2pdf = 'ps2pdf -dALLOWPSTRANSPARENCY %O %S %D'; +our $ps2pdf = 'ps2pdf -dALLOWPSTRANSPARENCY %O %S %D'; ## Command to convert xdv file to pdf file -$xdvipdfmx = 'xdvipdfmx -E -o %D %O %S'; -$xdvipdfmx_silent_switch = '-q'; +our $xdvipdfmx = 'xdvipdfmx -E -o %D %O %S'; +our $xdvipdfmx_silent_switch = '-q'; ## Command to search for tex-related files -$kpsewhich = 'kpsewhich %S'; +our $kpsewhich = 'kpsewhich %S'; ## Command to run make: -$make = 'make'; +our $make = 'make'; ##Printing: -$print_type = 'auto'; # When printing, print the postscript file. +our $print_type = 'auto'; # When printing, print the postscript file. # Possible values: 'dvi', 'ps', 'pdf', 'auto', 'none' # 'auto' ==> set print type according to the printable # file(s) being made: priority 'ps', 'pdf', 'dvi' # Viewers. These are system dependent, so default to none: +our ( $pdf_previewer, $ps_previewer, $ps_previewer_landscape, $dvi_previewer, + $dvi_previewer_landscape, $hnt_previewer ); $pdf_previewer = $ps_previewer = $ps_previewer_landscape = $dvi_previewer = $dvi_previewer_landscape = $hnt_previewer = "NONE"; -$dvi_update_signal = undef; -$ps_update_signal = undef; -$pdf_update_signal = undef; +# The following variables are assigned once and then used in symbolic +# references, so we need to avoid warnings 'name used only once': +our ( $aux_dir_requested, $out_dir_requested ); + +our $dvi_update_signal = undef; +our $ps_update_signal = undef; +our $pdf_update_signal = undef; -$dvi_update_command = undef; -$ps_update_command = undef; -$pdf_update_command = undef; +our $dvi_update_command = undef; +our $ps_update_command = undef; +our $pdf_update_command = undef; + # Viewer update methods: + # 0 => auto update: viewer watches file (e.g., gv) + # 1 => manual update: user must do something: e.g., click on window. + # (e.g., ghostview, MSWIN previewers, acroread under UNIX) + # 2 => send signal. Number of signal in $dvi_update_signal, + # $ps_update_signal, $pdf_update_signal + # 3 => viewer can't update, because it locks the file and the file + # cannot be updated. (acroread under MSWIN) + # 4 => run a command to force the update. The commands are + # specified by the variables $dvi_update_command, + # $ps_update_command, $pdf_update_command +our $dvi_update_method = 1; +our $hnt_update_method = 1; +our $ps_update_method = 1; +our $pdf_update_method = 1; -$allow_subdir_creation = 1; +our $allow_subdir_creation = 1; -$new_viewer_always = 0; # If 1, always open a new viewer in pvc mode. +our $new_viewer_always = 0; # If 1, always open a new viewer in pvc mode. # If 0, only open a new viewer if no previous # viewer for the same file is detected. # Commands for use in pvc mode for compiling, success, warnings, and failure; # they default to empty, i.e., not to use: -$compiling_cmd = $success_cmd = $warning_cmd = $failure_cmd = ""; +our ($compiling_cmd, $success_cmd, $warning_cmd, $failure_cmd) = + ( '', '', '', '' ); # Commands for printing are highly system dependent, so default to NONE: -$lpr = 'NONE $lpr variable is not configured to allow printing of ps files'; -$lpr_dvi = 'NONE $lpr_dvi variable is not configured to allow printing of dvi files'; -$lpr_pdf = 'NONE $lpr_pdf variable is not configured to allow printing of pdf files'; +our $lpr = 'NONE $lpr variable is not configured to allow printing of ps files'; +our $lpr_dvi = 'NONE $lpr_dvi variable is not configured to allow printing of dvi files'; +our $lpr_pdf = 'NONE $lpr_pdf variable is not configured to allow printing of pdf files'; # The $pscmd below holds a **system-dependent** command to list running @@ -898,24 +790,24 @@ $lpr_pdf = 'NONE $lpr_pdf variable is not configured to allow printing of pdf fi # process number and the command line of the processes, since the # relevant process is identified by the name of file to be viewed. # Its use is not essential. -$pscmd = 'NONE $pscmd variable is not configured to detect running processes'; -$pid_position = -1; # offset of PID in output of pscmd. +our $pscmd = 'NONE $pscmd variable is not configured to detect running processes'; +our $pid_position = -1; # offset of PID in output of pscmd. # Negative means I cannot use ps -$quote_filenames = 1; # Quote filenames in external commands +our $quote_filenames = 1; # Quote filenames in external commands -$del_dir = ''; # Directory into which cleaned up files are to be put. +our $del_dir = ''; # Directory into which cleaned up files are to be put. # If $del_dir is '', just delete the files in a clean up. -@rc_system_files = (); +our @rc_system_files = (); ######################################################################### ################################################################ ## Special variables for system-dependent fudges, etc. # ???????? !!!!!!!!!! -$log_file_binary = 0; # Whether to treat log file as binary +our $log_file_binary = 0; # Whether to treat log file as binary # Normally not, since the log file SHOULD be pure text. # But Miktex 2.7 sometimes puts binary characters # in it. (Typically in construct \OML ... after @@ -923,7 +815,7 @@ $log_file_binary = 0; # Whether to treat log file as binary # Sometimes there is ctrl/Z, which is not only non-text, # but is end-of-file marker for MS-Win in text mode. -$MSWin_fudge_break = 1; # Give special treatment to ctrl/C and ctrl/break +our $MSWin_fudge_break = 1; # Give special treatment to ctrl/C and ctrl/break # in -pvc mode under MSWin # Under MSWin32 (at least with perl 5.8 and WinXP) # when latexmk is running another program, and the @@ -953,14 +845,14 @@ $MSWin_fudge_break = 1; # Give special treatment to ctrl/C and ctrl/break ## Substitute backslashes in file and directory names for ## MSWin command line -$MSWin_back_slash = 0; +our $MSWin_back_slash = 0; ## Separator of elements in search_path. Default is unix value -$search_path_separator = ':'; +our $search_path_separator = ':'; # Directory for temporary files. Default to current directory. -$tmpdir = "."; +our $tmpdir = "."; # Latexmk does tests on whether a particular generated file, e.g., log or @@ -1051,6 +943,7 @@ our $filetime_offset_report_threshold = 10; # Threshold beyond which filetime of # are those of Windows. (The test for USERNAME as well as USER was # to make latexmk work under MSYS's perl.) # +our $start_NT = 'NONE'; if ( $^O eq "MSWin32" ) { # Pure MSWindows configuration @@ -1075,20 +968,6 @@ if ( $^O eq "MSWin32" ) { $dvi_previewer = 'start %O %S'; $dvi_previewer_landscape = "$dvi_previewer"; $hnt_previewer = 'start %O %S'; - # Viewer update methods: - # 0 => auto update: viewer watches file (e.g., gv) - # 1 => manual update: user must do something: e.g., click on window. - # (e.g., ghostview, MSWIN previewers, acroread under UNIX) - # 2 => send signal. Number of signal in $dvi_update_signal, - # $ps_update_signal, $pdf_update_signal - # 3 => viewer can't update, because it locks the file and the file - # cannot be updated. (acroread under MSWIN) - # 4 => run a command to force the update. The commands are - # specified by the variables $dvi_update_command, - # $ps_update_command, $pdf_update_command - $dvi_update_method = 1; - $hnt_update_method = 1; - $ps_update_method = 1; $pdf_update_method = 3; # acroread locks the pdf file } elsif ( $^O eq "cygwin" ) { @@ -1187,9 +1066,6 @@ elsif ( $^O eq "cygwin" ) { # $ps_update_signal, $pdf_update_signal # 3 => viewer can't update, because it locks the file and the file # cannot be updated. (acroread under MSWIN) - $dvi_update_method = 1; - $hnt_update_method = 1; - $ps_update_method = 1; $pdf_update_method = 3; # acroread locks the pdf file } elsif ( $^O eq "msys" ) { @@ -1335,8 +1211,8 @@ else { } ## default parameters -$auto_rc_use = 1; # Whether to read rc files automatically -$user_deleted_file_treated_as_changed = 0; # Whether when testing for changed +our $auto_rc_use = 1; # Whether to read rc files automatically +our $user_deleted_file_treated_as_changed = 0; # Whether when testing for changed # files, a user file that changes status from existing # to non-existing should be regarded as changed. # Value 1: only in non-preview-continuous mode. @@ -1345,7 +1221,7 @@ $user_deleted_file_treated_as_changed = 0; # Whether when testing for changed # compilation of .tex file tests for file existence and # adjusts behavior accordingly, instead of simply giving an # error. -$max_repeat = 5; # Maximum times I repeat latex. Normally +our $max_repeat = 5; # Maximum times I repeat latex. Normally # 3 would be sufficient: 1st run generates aux file, # 2nd run picks up aux file, and maybe toc, lof which # contain out-of-date information, e.g., wrong page @@ -1363,18 +1239,18 @@ $max_repeat = 5; # Maximum times I repeat latex. Normally # usually an indication of a problem; further # runs may not resolve the problem, and # instead could cause an infinite loop. -@cus_dep_list = (); # Custom dependency list -@default_files = ( '*.tex' ); # Array of LaTeX files to process when +our @cus_dep_list = (); # Custom dependency list +our @default_files = ( '*.tex' ); # Array of LaTeX files to process when # no files are specified on the command line. # Wildcards allowed # Best used for project specific files. -@default_excluded_files = ( ); +our @default_excluded_files = ( ); # Array of LaTeX files to exclude when using # @default_files, i.e., when no files are specified # on the command line. # Wildcards allowed # Best used for project specific files. -$texfile_search = ""; # Specification for extra files to search for +our $texfile_search = ""; # Specification for extra files to search for # when no files are specified on the command line # and the @default_files variable is empty. # Space separated, and wildcards allowed. @@ -1383,7 +1259,7 @@ $texfile_search = ""; # Specification for extra files to search for # This variable is obsolete, and only in here for # backward compatibility. -$jobname = ''; # Jobname: as with current tex, etc indicates +our $jobname = ''; # Jobname: as with current tex, etc indicates # basename of generated files. Defined so # that --jobname=STRING on latexmk's command # line has same effect as with current tex, @@ -1396,33 +1272,35 @@ $jobname = ''; # Jobname: as with current tex, etc indicates # dependent on name of main TeX file; this is # useful when a jobname is used and latexmk is # invoked on multiple files. -$out_dir = ''; # Directory for output files. +our $out_dir = ''; # Directory for output files. # Cf. --output-directory of current *latex # Blank means default, i.e., cwd. -$aux_dir = ''; # Directory for aux files (log, aux, etc). +our $aux_dir = ''; # Directory for aux files (log, aux, etc). # Cf. --aux-directory of current *latex in MiKTeX. # Blank means default, i.e., same as $out_dir. # Note that these values get modified when # processing a .tex file. +# Corresponding forms that can be concatenated (e.g., when $aux_dir is '.', $aux_dir1 is './'). +our $aux_dir1 = ''; +our $out_dir1 = ''; ## default flag settings. -$recorder = 1; # Whether to use recorder option on latex/pdflatex -$silent = 0; # Whether fo silence latex's messages (and others) -$warnings_as_errors = 0;# Treat warnings as errors and exit with non-zero exit code -$silence_logfile_warnings = 0; # Do list warnings in log file +our $recorder = 1; # Whether to use recorder option on latex/pdflatex +our $silent = 0; # Whether fo silence latex's messages (and others) +our $warnings_as_errors = 0;# Treat warnings as errors and exit with non-zero exit code +our $silence_logfile_warnings = 0; # Do list warnings in log file # The warnings reported are those about undefined refs # and citations, and the like. -$max_logfile_warnings = 7; # Max. # number of log file warnings to report -$rc_report = 1; # Whether to report on rc files read -$aux_out_dir_report = 0; # Whether to report on aux_dir & out_dir after +our $max_logfile_warnings = 7; # Max. # number of log file warnings to report +our $rc_report = 1; # Whether to report on rc files read +our $aux_out_dir_report = 0; # Whether to report on aux_dir & out_dir after # initialization and normalization. # When $aux_out_dir_report is set to 2, latexmk # does no further processing after the report of # the aux and out directories. -$kpsewhich_show = 0; # Show calls to and results from kpsewhich -$landscape_mode = 0; # default to portrait mode -$analyze_input_log_always = 1; # Always analyze .log for input files in the +our $kpsewhich_show = 0; # Show calls to and results from kpsewhich +our $analyze_input_log_always = 1; # Always analyze .log for input files in the # <...> and (...) constructions. Otherwise, only # do the analysis when fls file doesn't exist or is # out of date. @@ -1442,7 +1320,7 @@ $analyze_input_log_always = 1; # Always analyze .log for input files in the # To keep backward compatibility with older versions # of latexmk, the default is to set # $analyze_input_log_always to 1. -$fls_uses_out_dir = 0; # Whether fls file is to be in out directory (as with +our $fls_uses_out_dir = 0; # Whether fls file is to be in out directory (as with # pre-Oct-2020 MiKTeX), or in aux directory (as with # newer versions of MiKTeX). # If the implementation of *latex puts the fls file in @@ -1452,7 +1330,7 @@ $fls_uses_out_dir = 0; # Whether fls file is to be in out directory (as with # Which kinds of file do I have requests to make? our ($dvi_mode, $hnt_mode, $pdf_mode, $postscript_mode, $xdv_mode, - $cleanup_mode, $force_mode, $go_mode, $landscape_mode, $preview_mode, $preview_continuous_mode, $printout_mode ); + $landscape_mode ); # If no requests at all are made, then I will make dvi file # If particular requests are made then other files may also have to be # made. E.g., ps file requires a dvi file @@ -1472,59 +1350,60 @@ $pdf_mode = 0; # No pdf file requested to be made by pdflatex # 4 to create pdf file by lualatex # 5 to create pdf file by xelatex + xdvipdfmx $xdv_mode = 0; # No xdv file requested +$landscape_mode = 0; # default to portrait mode -$view = 'default'; # Default preview is of highest of dvi, ps, pdf -$min_sleep_time = 0.01; # Minimum non-zero sleep time -$sleep_time = 2; # time to sleep b/w checks for file changes in -pvc mode -$banner = 0; # Non-zero if we have a banner to insert -$banner_scale = 220; # Original default scale -$banner_intensity = 0.95; # Darkness of the banner message -$banner_message = 'DRAFT'; # Original default message -$do_cd = 0; # Do not do cd to directory of source file. +our $view = 'default'; # Default preview is of highest of dvi, ps, pdf +our $min_sleep_time = 0.01; # Minimum non-zero sleep time +our $sleep_time = 2; # time to sleep b/w checks for file changes in -pvc mode +our $banner = 0; # Non-zero if we have a banner to insert +our $banner_scale = 220; # Original default scale +our $banner_intensity = 0.95; # Darkness of the banner message +our $banner_message = 'DRAFT'; # Original default message +our $do_cd = 0; # Do not do cd to directory of source file. # Thus behave like latex. -$dependents_list = 0; # Whether to display list(s) of dependencies -$dependents_phony = 0; # Whether list(s) of dependencies includes phony targets +our $dependents_list = 0; # Whether to display list(s) of dependencies +our $dependents_phony = 0; # Whether list(s) of dependencies includes phony targets # (as with 'gcc -MP'). -$deps_file = '-'; # File for dependency list output. Default stdout. -$rules_list = 0; # Whether to display list(s) of dependencies +our $deps_file = '-'; # File for dependency list output. Default stdout. +our $rules_list = 0; # Whether to display list(s) of dependencies # Kind of escaping in names of files written to deps file. -$deps_escape = 'none'; +our $deps_escape = 'none'; # Allowed kinds of escape: -%deps_escape_kinds = ( 'none' => ' ', 'unix' => '\ ', 'nmake' => '^ '); +our %deps_escape_kinds = ( 'none' => ' ', 'unix' => '\ ', 'nmake' => '^ '); -@dir_stack = (); # Stack of pushed directories, each of form of +our @dir_stack = (); # Stack of pushed directories, each of form of # pointer to array [ cwd, good_cwd ], where # good_cwd differs from cwd by being converted # to native MSWin path when cygwin is used. -$cleanup_mode = 0; # No cleanup of nonessential LaTex-related files. +our $cleanup_mode = 0; # No cleanup of nonessential LaTex-related files. # $cleanup_mode = 0: no cleanup # $cleanup_mode = 1: full cleanup # $cleanup_mode = 2: cleanup except for dvi, # dviF, pdf, ps, psF & xdv -$cleanup_fdb = 0; # On normal run, no removal of file for latexmk's file-database -$cleanup_only = 0; # When doing cleanup, do not go on to making files -$cleanup_includes_generated = 0; +our $cleanup_fdb = 0; # On normal run, no removal of file for latexmk's file-database +our $cleanup_only = 0; # When doing cleanup, do not go on to making files +our $cleanup_includes_generated = 0; # Determines whether cleanup deletes files generated by # *latex (found from \openout lines in log file). # It's more than that. BUG -$cleanup_includes_cusdep_generated = 0; +our $cleanup_includes_cusdep_generated = 0; # Determines whether cleanup deletes files generated by # custom dependencies -$diagnostics = 0; -$dvi_filter = ''; # DVI filter command -$ps_filter = ''; # Postscript filter command +our $diagnostics = 0; +our $dvi_filter = ''; # DVI filter command +our $ps_filter = ''; # Postscript filter command -$force_mode = 0; # =1: to force processing past errors -$go_mode = 0; # =1: to force processing regardless of time-stamps +our $force_mode = 0; # =1: to force processing past errors +our $go_mode = 0; # =1: to force processing regardless of time-stamps # =2: full clean-up first # =3: Just force primary rule(s) to run -$preview_mode = 0; -$preview_continuous_mode = 0; -$printout_mode = 0; # Don't print the file +our $preview_mode = 0; +our $preview_continuous_mode = 0; +our $printout_mode = 0; # Don't print the file ## Control pvc inactivity timeout: -$pvc_timeout = 0; -$pvc_timeout_mins = 30; +our $pvc_timeout = 0; +our $pvc_timeout_mins = 30; # Timing information # Whether to report processing time: @@ -1542,39 +1421,42 @@ our ( $clock1, $processing_time1, $processing_time0, @timings1, @timings0); &init_timing_all; -$use_make_for_missing_files = 0; # Whether to use make to try to make missing files. +our $use_make_for_missing_files = 0; # Whether to use make to try to make missing files. # Do we make view file in temporary then move to final destination? # (To avoid premature updating by viewer). -$always_view_file_via_temporary = 0; # Set to 1 if viewed file is always +our $always_view_file_via_temporary = 0; # Set to 1 if viewed file is always # made through a temporary. -$pvc_view_file_via_temporary = 1; # Set to 1 if only in -pvc mode is viewed +our $pvc_view_file_via_temporary = 1; # Set to 1 if only in -pvc mode is viewed # file made through a temporary. # State variables initialized here: -$updated = 0; # Flags whether something has been remade in this round +our $updated = 0; # Flags whether something has been remade in this round # of compilation. -$waiting = 0; # Flags whether we are in loop waiting for an event +our $failure = 0; # Set nonzero to indicate failure at some point of + # a make. Use value as exit code if I exit. +our $failure_msg = ''; # Indicate reason for failure +our $waiting = 0; # Flags whether we are in loop waiting for an event # Used to avoid unnecessary repeated o/p in wait loop # The following are used for some results of parsing log file # Global variables, so results can be reported in main program. -$reference_changed = 0; -$mult_defined = 0; -$bad_reference = 0; -$bad_character = 0; -$bad_citation = 0; -@primary_warning_summary = (); +our $reference_changed = 0; +our $mult_defined = 0; +our $bad_reference = 0; +our $bad_character = 0; +our $bad_citation = 0; +our @primary_warning_summary = (); # Cache of expensive-to-compute state variables, e.g., cwd in form # fixed to deal with cygwin issues. -%cache = (); +our %cache = (); &cache_good_cwd; # Set search paths for includes. # Set them early so that they can be overridden -$BIBINPUTS = $ENV{'BIBINPUTS'}; +our $BIBINPUTS = $ENV{'BIBINPUTS'}; if (!$BIBINPUTS) { $BIBINPUTS = '.'; } # ???!!! @@ -1594,7 +1476,7 @@ if (!$BIBINPUTS) { $BIBINPUTS = '.'; } # directory. After these operations, @BIBINPUTS should # have all the directories that need to be searched # -@BIBINPUTS = find_dirs1( $BIBINPUTS ); +our @BIBINPUTS = find_dirs1( $BIBINPUTS ); our @BIBINPUTS_SAVE = @BIBINPUTS; our $BIBINPUTS_ENV_SAVE = $ENV{BIBINPUTS}; @@ -1713,34 +1595,34 @@ our $BIBINPUTS_ENV_SAVE = $ENV{BIBINPUTS}; # Hashes, whose keys give names of particular kinds of rule, and targets. # We use hashes for ease of lookup. -%possible_one_time = ( 'view' => 1, 'print' => 1, 'update_view' => 1, ); -%target_files = (); # Hash for target files. +our %possible_one_time = ( 'view' => 1, 'print' => 1, 'update_view' => 1, ); +our %target_files = (); # Hash for target files. # The keys are the filenames and the value is # currently irrelevant. -%target_rules = (); # Hash for target rules beyond those corresponding to files. +our %target_rules = (); # Hash for target rules beyond those corresponding to files. # The keys are the rule names and the value is # currently irrelevant. # The target **files** can only be set inside the FILE loop. -$current_primary = 'latex'; # Rule to compile .tex file. +our $current_primary = 'latex';# Rule to compile .tex file. # It will be overridden at rule-initialization time, and # is subject to document-dependent override if .tex document # uses metcommands and obeying them is implemented/enabled. -$pdf_method = ''; # How to make pdf file. '' if not requested, +our $pdf_method = ''; # How to make pdf file. '' if not requested, # else 'ps2pdf', 'dvipdf', 'pdflatex', 'lualatex' or 'xelatex' # Subject to document-dependent override if .tex document #uses \pdfoutput or c. -%requested_filetypes = (); # Hash of requested file types (dvi, dviF, etc) -%one_time = (); # Hash for requested one-time-only rules, currently +our %requested_filetypes = (); # Hash of requested file types (dvi, dviF, etc) +our %one_time = (); # Hash for requested one-time-only rules, currently # possible values 'print' and 'view'. -%actives = (); # Hash of active rules +our %actives = (); # Hash of active rules -$allow_switch = 1; # Allow switch of rule structure to accommodate +our $allow_switch = 1; # Allow switch of rule structure to accommodate # changed output file name of primary. Even if # this flag is set on, the switch may be # prohibited by other issues. -%rule_db = (); # Database of all rules: +our %rule_db = (); # Database of all rules: # Hash: rulename -> [array of rule data] # Rule data: # 0: [ cmd_type, ext_cmd, int_cmd, no_history, @@ -1948,10 +1830,10 @@ $allow_switch = 1; # Allow switch of rule structure to accommodate # The aim of this item is for flexible # rule-dependent add-ons. -%fdb_current = (); # Hash of information for all files used. +our %fdb_current = (); # Hash of information for all files used. # It maps filename to a reference to an array # (time, size, md5_checksum). -@nofile = (0,-1,0); # What we use for initializing a new entry in fdb +our @nofile = (0,-1,0); # What we use for initializing a new entry in fdb # or flagging non-existent file. # The following are variables which are set by the routine rdb_set_rule_net. @@ -1960,25 +1842,33 @@ $allow_switch = 1; # Allow switch of rule structure to accommodate # information is in a form useful for using the network of rules. # For recursing backwards through the network of rules: -%from_rules = (); # This maps file names to rule names. +our %from_rules = (); # This maps file names to rule names. # $from_rules{'File'} is the name of the rule that # generates file 'File'. If there is no rule to # generate the file, then $from_rules{'File'} is # not defined (or possibly the null string ''). # Classification of rules, for determining order of application -@pre_primary = (); # Array of rules that are thought of as pre-primary, +our @pre_primary = (); # Array of rules that are thought of as pre-primary, # Should be in an appropriate order for invoking # them, to optimize making. -@post_primary = (); # Array of rules that are thought of as post-primary. +our @post_primary = (); # Array of rules that are thought of as post-primary. # In suitable order for invocation -@unusual_one_time = (); # Array of rules that are special cases of +our @unusual_one_time = ();# Array of rules that are special cases of # one-time rules. # Currently not used. - +# Variables set in applying rules: +our ($rule, $PA_extra_gen, $PAint_cmd, $PArule_data, $Pbase, $Pchanged, + $Pcheck_time, $Pcmd_type, $Pdest, $Pext_cmd, + $PHdest, $PHextra, $PHrewritten_before_read, $PHsource, $PHsource_rules, + $Plast_message, $Plast_result, $Plast_result_info, + $Pno_history, $Pout_of_date, $Pout_of_date_user, $Prun_time, $Psource, + $file, $PAfile_data, $Ptime, $Psize, $Pmd5, $DUMMY, $Pcorrect_after_primary +); + # User's home directory -$HOME = ''; +our $HOME = ''; if (exists $ENV{'HOME'} ) { $HOME = $ENV{'HOME'}; } @@ -1986,7 +1876,7 @@ elsif (exists $ENV{'USERPROFILE'} ) { $HOME = $ENV{'USERPROFILE'}; } # XDG configuration home -$XDG_CONFIG_HOME = ''; +our $XDG_CONFIG_HOME = ''; if (exists $ENV{'XDG_CONFIG_HOME'} ) { $XDG_CONFIG_HOME = $ENV{'XDG_CONFIG_HOME'}; } @@ -2000,8 +1890,8 @@ elsif ($HOME ne '') { #================================================== # Which rc files did I read? -@rc_files_read = (); # In order of reading -%rc_files_read2 = (); # Map **abs** filename to 1; used to check duplicate reads. +our @rc_files_read = (); # In order of reading +our %rc_files_read2 = (); # Map **abs** filename to 1; used to check duplicate reads. # Options that are to be obeyed before rc files are read: # Also under MSWin32 and msys, CL arguments sometimes get quotes in them. @@ -2064,7 +1954,7 @@ if ( $auto_rc_use ) { } if ( $auto_rc_use && ($HOME ne "" ) ) { # User rc file: - @user_rc = (); + my @user_rc = (); if ( $XDG_CONFIG_HOME ) { push @user_rc, "$XDG_CONFIG_HOME/latexmk/latexmkrc"; } @@ -2083,12 +1973,13 @@ if ( $auto_rc_use ) { ## Process command line args. -@command_line_file_list = (); -$bad_options = 0; +our @command_line_file_list = (); +our $bad_options = 0; + while (defined(local $_ = $ARGV[0])) { # Make -- and - equivalent at beginning of option, # but save original for possible use in *latex command line - $original = $_; + my $original = $_; s/^--/-/; shift; if ( /^-aux-directory=(.*)$/ || /^-auxdir=(.*)$/ ) { @@ -2265,7 +2156,7 @@ while (defined(local $_ = $ARGV[0])) { $pre_tex_code = $1; } elsif (/^-print=(.*)$/) { - $value = $1; + my $value = $1; if ( $value =~ /^dvi$|^ps$|^pdf$|^auto$/ ) { $print_type = $value; $printout_mode = 1; @@ -2314,7 +2205,7 @@ while (defined(local $_ = $ARGV[0])) { "appear in the following list\n", "NOTE ALSO: Not all of these options are supported by all versions of *latex.\n", "\n"; - foreach $option ( sort( keys %allowed_latex_options, keys %allowed_latex_options_with_arg ) ) { + foreach my $option ( sort( keys %allowed_latex_options, keys %allowed_latex_options_with_arg ) ) { if (exists $allowed_latex_options{$option} ) { print " $allowed_latex_options{$option}\n"; } if (exists $allowed_latex_options_with_arg{$option} ) { print " $allowed_latex_options_with_arg{$option}\n"; } } @@ -2475,6 +2366,7 @@ if ( $texfile_search ne "" ) { # (OS detected as cygwin) # (3) UNIX Don't glob (cmd interpreter does it) # (Currently, I assume this is everything else) +our @file_list; if ( ($^O eq "MSWin32") || ($^O eq "cygwin") ) { # Preserve ordering of files @file_list = glob_list1(@command_line_file_list); @@ -2529,8 +2421,8 @@ else { } } -$num_files = $#file_list + 1; -$num_specified = $#command_line_file_list + 1; +our $num_files = $#file_list + 1; +our $num_specified = $#command_line_file_list + 1; #print "Command line file list:\n"; #for ($i = 0; $i <= $#command_line_file_list; $i++ ) { print "$i: '$command_line_file_list[$i]'\n"; } @@ -2746,7 +2638,7 @@ if ( $printout_mode ) { } if ( $preview_continuous_mode || $preview_mode ) { $one_time{'view'} = 1; } -$can_switch = $allow_switch; +our $can_switch = $allow_switch; if ( $dvi_mode || $hnt_mode || $postscript_mode || $xdv_mode || ( $printout_mode && ($print_type eq 'ps') || ($print_type eq 'dvi') ) || ( ($preview_mode || $preview_continuous_mode) && ( ($view eq 'ps') || ($view eq 'dvi') ) ) @@ -2792,15 +2684,15 @@ push @final_output_exts, split('\s+',$clean_full_ext); # Convert the arrays to hashes, for ease of deletion: # Keep extension without period! -%generated_exts = (); +our %generated_exts = (); foreach (@generated_exts ) { $generated_exts{$_} = 1; } -$quell_uptodate_msgs = $silent; +our $quell_uptodate_msgs = $silent; # Whether to quell informational messages when files are uptodate # Will turn off in -pvc mode -$failure_count = 0; -@failed_primaries = (); +our $failure_count = 0; +our @failed_primaries = (); if ($deps_file eq '' ) { # Standardize name used for stdout @@ -2826,7 +2718,7 @@ if ( ($cleanup_mode > 0) && $dependents_list && ( $deps_file ne '-' ) ) { # been opened and therefore being available to be written to after # compiling a file. -$deps_handle = undef; +our $deps_handle = undef; if ( $dependents_list && ! $preview_continuous_mode && ( ($cleanup_mode == 0) || ($go_mode == 2) ) @@ -2840,17 +2732,30 @@ if ( $dependents_list # Deal with illegal and problematic characters in filename: test_fix_texnames( @file_list ); -$quote = $quote_filenames ? '"' : ''; - +our $quote = $quote_filenames ? '"' : ''; +# Primary filename and path are variables of overall context, and hence global. +our $filename; +our $path; +# Other globals +our ( @default_includes, $texfile_name, $root_filename, $log_name, + $tex_basename, $fls_name, $fls_name_alt, $fdb_name, $aux_main, + $dvi_name, $dviF_name, $hnt_name, $ps_name, $psF_name, $pdf_name, + $xdv_name, + $dvi_final, $hnt_final, $ps_final, $pdf_final, $xdv_final, + $view_file, + %rule_list, + $missing_dvi_pdf, $switched_primary_output +); FILE: foreach $filename ( @file_list ) { # Global variables for making of current file: $updated = 0; - $failure = 0; # Set nonzero to indicate failure at some point of - # a make. Use value as exit code if I exit. + $failure = 0; # Set nonzero to indicate failure at some point of + # a make. Use value as exit code if I exit. $failure_msg = ''; # Indicate reason for failure + my $path = ''; if ( $do_cd ) { # Use my fileparse routine rather than the built-in one, otherwise # under msys, a directory separator \ won't be recognized by fileparse. @@ -2864,9 +2769,6 @@ foreach $filename ( @file_list ) if !$silent; pushd( dirname_no_tail( $path ) ); } - else { - $path = ''; - } # Localize the following, because they may get changed because of # conditions specific to the current tex file, notably: @@ -2958,12 +2860,12 @@ foreach $filename ( @file_list ) if ($go_mode == 3) { # Force primaries to be remade. if (!$silent) { print "Force *latex to be remade.\n"; } - rdb_for_some( [keys %possible_primaries], sub{$$Pout_of_date=1;} ); + rdb_for_some( [keys %possible_primaries], sub{$$Pout_of_date = 'go_mode=3';} ); } elsif ($go_mode) { # Force everything to be remade. if (!$silent) { print "Force everything to be remade.\n"; } - rdb_recurse( [ &rdb_target_array], sub{$$Pout_of_date=1;} ); + rdb_recurse( [ &rdb_target_array], sub{$$Pout_of_date = 'go_mode';} ); } @@ -2997,7 +2899,6 @@ foreach $filename ( @file_list ) $failure_msg = ''; &init_timing1; - if ($compiling_cmd) { Run_subst( $compiling_cmd ); } $failure = rdb_make(); if ( ( $failure <= 0 ) || $force_mode ) { rdb_for_some( [keys %one_time], \&rdb_run1 ); @@ -3023,7 +2924,7 @@ continue { # mode, since the rules list has already been printed. if ($rules_list && ! $preview_continuous_mode) { rdb_list(); } # Handle any errors - $error_message_count = rdb_show_rule_errors(); + my $error_message_count = rdb_show_rule_errors(); if ( ($error_message_count == 0) || ($failure > 0) ) { if ( $failure_msg ) { #Remove trailing space @@ -3179,6 +3080,7 @@ sub set_tex_cmds { # Usage, e.g., set_tex_cmds( '%O %S' ) # or set_tex_cmds( '%C-dev %O %S' ) my $args = $_[0]; + no strict "refs"; foreach my $cmd ( keys %possible_primaries ) { my $spec = $args; if ( $spec =~ /%C/ ) { $spec =~ s/%C/$cmd/g; } @@ -3504,6 +3406,7 @@ sub fix_cmds { sub add_option { # Call add_option( $opt, \$cmd ... ) # Add option to one or more commands + no strict "refs"; my $option = shift; while (@_) { if ( ${$_[0]} !~ /%/ ) { &fix_cmds; } @@ -3585,7 +3488,7 @@ sub rdb_initialize_rules { if ($hnt_mode) { $current_primary = 'hilatex'; } rdb_activate( $current_primary ); - + if ($dvi_mode) { $target_files{$dvi_final} = 1; } if ($hnt_mode) { $target_files{$hnt_final} = 1; } if ($postscript_mode) { $target_files{$ps_final} = 1; } @@ -3628,7 +3531,8 @@ sub rdb_set_rule_templates { my $viewer_update_signal = undef; my $viewer_update_command = undef; - if ( ($view eq 'dvi') || ($view eq 'hnt') || ($view eq 'pdf') || ($view eq 'ps') ) { + if ( ($view eq 'dvi') || ($view eq 'hnt') || ($view eq 'pdf') || ($view eq 'ps') ) { + no strict "refs"; $view_file = ${$view.'_final'}; $viewer = ${$view.'_previewer'}; $viewer_update_method = ${$view.'_update_method'}; @@ -3642,7 +3546,7 @@ sub rdb_set_rule_templates { %rule_list = ( 'dvilualatex' => [ 'primary', "$dvilualatex", '', "%T", $dvi_name, "%R", 1, [$aux_main, $log_name], [$aux_main] ], - 'hilatex' => [ 'primary', "$hilatex", '', "%T", $hnt_name, "%R", 1, [$aux_main, $log_name], [$aux_main] ], + 'hilatex' => [ 'primary', "$hilatex", '', "%T", $hnt_name, "%R", 1, [$aux_main, $log_name], [$aux_main] ], 'latex' => [ 'primary', "$latex", '', "%T", $dvi_name, "%R", 1, [$aux_main, $log_name], [$aux_main] ], 'lualatex' => [ 'primary', "$lualatex", '', "%T", $pdf_name, "%R", 1, [$aux_main, $log_name], [$aux_main] ], 'pdflatex' => [ 'primary', "$pdflatex", '', "%T", $pdf_name, "%R", 1, [$aux_main, $log_name], [$aux_main] ], @@ -3679,6 +3583,7 @@ sub rdb_set_rule_net { # it doesn't exist. Later a rule is created by latexmk to make that # file. Then the rule's main destination file should have priority # over non-main generated files from other rules. + our %from_rules_old; local %from_rules_old = %from_rules; %from_rules = (); # File to rule. rdb_for_actives( \&set_file_links_for_rule ); @@ -3738,6 +3643,7 @@ sub rdb_set_source_rules { # in rdb_make etc. # my ($base, $path, $ext) = fileparseA( $$Psource ); + our %from_rules_old; if ( ($ext eq '.dvi') || ($ext eq '.dviF') || ($ext eq '.xdv') ) { # Rules that use .dvi, .dviF, .xdv don't get all dependencies, # notably about included graphics files. @@ -3774,7 +3680,8 @@ sub rdb_classify_rules { # @unusual_one_time # Array of rules # @pre_primary and @post_primary are in natural order of application. - local @requested_targets = &rdb_target_array; + my @requested_targets = &rdb_target_array; + our (@classify_stack, $state); local $state = 0; # Post-primary local @classify_stack = (); @@ -3806,6 +3713,7 @@ sub rdb_classify1 { # Helper routine for rdb_classify_rules # Applied as rule_act1 in recursion over rules # Assumes rule context, and local variables from rdb_classify_rules + our (@classify_stack, $state, $depth); push @classify_stack, [$state]; if ( exists $possible_one_time{$rule} ) { # Normally, we will have already extracted the one_time rules, @@ -3836,6 +3744,7 @@ sub rdb_classify2 { # Helper routine for rdb_classify_rules # Applied as rule_act2 in recursion over rules # Assumes rule context + our (@classify_stack, $state); ($state) = @{ pop @classify_stack }; } #END rdb_classify2 @@ -3856,15 +3765,15 @@ sub set_trivial_aux_fdb { open( my $aux_file, '>', $aux_main ) or die "Cannot write file '$aux_main'\n"; - fprint8 $aux_file, "\\relax \n"; + fprint8( $aux_file, "\\relax \n" ); # The following is added by recent versions of latex for a # one page document - fprint8 $aux_file, "\\gdef \\\@abspage\@last{1}\n"; + fprint8( $aux_file, "\\gdef \\\@abspage\@last{1}\n" ); close($aux_file); foreach my $rule (keys %possible_primaries ) { rdb_one_rule( $rule, - sub{ $$Pout_of_date = 1; } + sub{ $$Pout_of_date = 'Initial setup'; } ); } &rdb_write( $fdb_name ); @@ -3879,7 +3788,7 @@ sub do_cleanup { my $kind = $_[0]; if (! $kind ) { return; } my @files_to_delete = (); - @dirs = ($aux_dir1); + my @dirs = ($aux_dir1); if ($out_dir1 ne $aux_dir1) { push @dirs, $out_dir1; } push @files_to_delete, &get_small_cleanup; @@ -3888,7 +3797,7 @@ sub do_cleanup { push @files_to_delete, cleanup_get1( $dir1, @final_output_exts ); } } - # show_array( "Files to delete", sort @files_to_delete ); + # show_array( "Files to delete", sort @files_to_delete ); # Names of contents of directory are longer than the name of the directory, # but contain the directory name as an initial segment. @@ -3896,8 +3805,6 @@ sub do_cleanup { # sort deletes contents of directory before attempting to delete the # directory: unlink_or_move( reverse sort @files_to_delete ); - - # If the fdb file (or log, fls and/or aux files) exist, it/they will have # been used to make a changed rule database. But a cleanup implies @@ -3936,6 +3843,8 @@ sub cleanup_get1 { sub get_small_cleanup { # Get list of files to be deleted in a small cleanup. # Assume dependency information from previous run has been obtained. + + my @files = (); my %other_generated = (); my %cusdep_generated = (); my @index_bibtex_generated = (); @@ -4066,6 +3975,7 @@ sub do_cusdep { # argument is the name of the subroutine to apply my $func_name = $_[0]; my $return = 0; + no strict "refs"; if ( !-e $$Psource ) { # Source does not exist. Users of this rule will need to turn # it off when custom dependencies are reset @@ -4217,12 +4127,12 @@ sub find_basename { # Returns non-zero if tex file does not exist my $fail = 0; - local ( $given_name, $base_name, $ext, $path, $tex_name, $source_name ); + my ( $given_name, $base_name, $ext, $path, $tex_name, $source_name ); $given_name = $_[0]; + $source_name = ''; $tex_name = $given_name; # Default name if I don't find the tex file ($base_name, $path, $ext) = fileparseB( $given_name ); - # Treatment of extensions (in TeXLive 2019), with omission of path search: # Exists: always means exists as a file, i.e., not as a directory. # A. Finding of tex file: @@ -4245,7 +4155,6 @@ sub find_basename { # file # 4. If that also fails, report non-existent tex file. - if ( ($ext eq '.tex') && (-f $given_name) ) { $tex_name = "$given_name"; } @@ -4315,10 +4224,10 @@ sub make_preview_continuous { my $viewer_running = 0; # No viewer known to be running yet # Get information from update_view rule - local $viewer_update_method = 0; + my $viewer_update_method = 0; # Pointers so we can update the following: - local $Pviewer_process = undef; - local $Pneed_to_get_viewer_process = undef; + my $Pviewer_process = undef; + my $Pneed_to_get_viewer_process = undef; rdb_one_rule( 'update_view', sub{ $viewer_update_method = $$PAint_cmd[1]; $Pviewer_process = \$$PAint_cmd[3]; @@ -4361,9 +4270,6 @@ CHANGE: # $MSWin_fudge_break. $SIG{BREAK} = $SIG{INT} = 'IGNORE'; } - if ($compiling_cmd) { - Run_subst( $compiling_cmd ); - } $failure = rdb_make(); if ( $MSWin_fudge_break && ($^O eq "MSWin32") ) { @@ -4391,7 +4297,7 @@ CHANGE: "------------\n"; } } - local $retcode = 0; + my $retcode = 0; rdb_one_rule( 'view', sub { $retcode = &rdb_run1;} ); if ( $retcode != 0 ) { if ($force_mode) { @@ -4477,7 +4383,8 @@ CHANGE: # command line to work: # latexmk -pvc foo; cleanup; &catch_break; - $have_break = 0; + our $have_break; + local $have_break = 0; $last_action_time = time(); $waiting = 1; rdb_for_some( @@ -4504,8 +4411,8 @@ CHANGE: # Don't count waiting time in processing: $processing_time1 = processing_time(); # Does this do this job????!!! - local $new_files = 0; - rdb_for_some( [keys %current_primaries], sub{ $new_files += &rdb_find_new_files } ); + my $new_files = 0; + rdb_for_some( [$current_primary], sub{ $new_files += &rdb_find_new_files } ); if ($new_files > 0) { print "$My_name: New file(s) found.\n"; last WAIT; @@ -4597,6 +4504,8 @@ sub process_rc_file { } my $BOM = Encode::encode( 'UTF-8', "\N{U+FEFF}" ); $code =~ s/^$BOM//; + no strict; + # !!!??? For backward compatibility, turn off strictness for evaluating rc files. eval $code; } else { @@ -4628,7 +4537,10 @@ sub execute_code_string { print "$My_name: Executing initialization code specified by -e:\n", " '$code'...\n" if $diagnostics; + { + no strict; eval $code; + } # The return value from the eval is not useful, since it is the value of # the last expression evaluated, which could be anything. # The correct test of errors is on the value of $@. @@ -5003,8 +4915,7 @@ sub after_biber { our ( $rule, $Pbase, $Pdest, $PHextra, $Plast_message, $Plast_result, $Pout_of_date, $Psource, $PHsource ); # Global variables used - our ( %current_primaries, $diagnostics, $My_name, $save_error_suffix, - $silent ); + our ( $diagnostics, $My_name, $save_error_suffix, $silent ); my $Preturn = $_[0]; my @biber_datasource = ( ); my @biber_remote = (); @@ -5024,7 +4935,7 @@ sub after_biber { print "Source '$$Psource' for '$rule' doesn't exist,\n", "so I'll force *latex to run to try and make it.\n"; } - rdb_for_some( [keys %current_primaries], sub{ $$Pout_of_date = 1; } ); + rdb_for_some( [$current_primary], sub{ $$Pout_of_date = "to make '$$Psource' for '$rule'"; } ); } rdb_set_source_here( @biber_datasource, $$Psource ); @@ -5034,7 +4945,7 @@ sub after_biber { print "$My_name: bibtex control file missing. Since that can\n", " be recreated, I'll try to do so.\n"; $$Preturn = -2; - rdb_for_some( [keys %current_primaries], sub{ $$Pout_of_date = 1; } ); + rdb_for_some( [$current_primary], sub{ $$Pout_of_date = "to make missing control file"; } ); } elsif ($retcode == 4) { $$Plast_result = 2; @@ -5125,8 +5036,8 @@ sub check_biber_log { my $control_file_malformed = 0; my @not_found = (); # Files, normally .bib files, not found. my @missing_citations = (); - - while (local $_= <$blg_file>) { + + while (local $_ = <$blg_file>) { $_ = utf8_to_mine($_); if (/> WARN /) { print "Biber warning: $_"; @@ -5303,7 +5214,7 @@ sub after_bibtex { our ( $rule, $Pbase, $Pdest, $Plast_message, $Plast_result, $Pout_of_date, $Psource ); # Global variables used - our ( %current_primaries, $diagnostics, $failure, $My_name, $silent ); + our ( $diagnostics, $failure, $My_name, $silent ); my $Preturn = $_[0]; my $retcode = check_bibtex_log($$Pbase); @@ -5315,7 +5226,7 @@ sub after_bibtex { print "Source '$$Psource' for '$rule' doesn't exist,\n", "so I'll force *latex to run to try and make it.\n"; } - rdb_for_some( [keys %current_primaries], sub{ $$Pout_of_date = 1; } ); + rdb_for_some( [$current_primary], sub{ $$Pout_of_date = "to make '$$Psource' for '$rule'"; } ); } if ($retcode == 3) { $$Plast_result = 2; @@ -5359,7 +5270,7 @@ sub check_bibtex_log { # Variable used in context of a rule action our ( $Pout_of_date ); # Global variables used - our ( %current_primaries, $My_name ); + our ( $My_name ); my $base = $_[0]; my $blg_name = "$base.blg"; @@ -5371,6 +5282,7 @@ sub check_bibtex_log { my @missing_aux = (); my @missing_bib = (); my $error_count = 0; + while (local $_ = <$blg_file>) { $_ = utf8_to_mine($_); if (/^Warning--/) { @@ -5398,7 +5310,7 @@ sub check_bibtex_log { # Need to make the missing files. print "$My_name: One or more aux files is missing for bibtex. I'll try\n", " to get *latex to remake them.\n"; - rdb_for_some( [keys %current_primaries], sub{ $$Pout_of_date = 1; } ); + rdb_for_some( [$current_primary], sub{ $$Pout_of_date = "to get missing aux file(s) made"; } ); } #print "Bibtex errors = $error_count, missing aux files and citations = $missing\n"; if ($have_error && ($error_count <= $weak_errors ) @@ -5536,7 +5448,7 @@ sub set_names { if ( length($ps_filter) > 0) { $ps_final = $psF_name; } -} +} #END set_names #************************************************** @@ -5551,6 +5463,9 @@ sub correct_locations { # of -aux-directory option. This is to be done first, since a run of # *latex always produces a log file unless there is a bad error, so # this gives the best chance of diagnosing errors. + + # Assumes rule context. + my $where_log = &find_set_log; if ( $emulate_aux && ($aux_dir ne $out_dir) ) { # Move output files from aux_dir to out_dir @@ -5558,8 +5473,8 @@ sub correct_locations { # Omit 'xdv', that goes to aux_dir (as with MiKTeX). It's not final output. foreach my $ext ( 'fls', 'dvi', 'hnt', 'pdf', 'ps', 'synctex', 'synctex.gz' ) { if ( ($ext eq 'fls') && ! $fls_uses_out_dir ) {next;} - my $from = "$aux_dir1$root_filename.$ext"; - my $to = "$out_dir1$root_filename.$ext" ; + my $from = "$aux_dir1$$Pbase.$ext"; + my $to = "$out_dir1$$Pbase.$ext" ; if ( test_gen_file_time( $from ) ) { if (! $silent) { print "$My_name: Moving '$from' to '$to'\n"; } my $ret = move( $from, $to ); @@ -5572,7 +5487,7 @@ sub correct_locations { if ($recorder) { # Deal with following special cases: # 1. Some implemenations of *latex give fls files of name latex.fls - # or pdflatex.fls instead of $root_filename.fls. + # or pdflatex.fls instead of $$Pbase.fls. # 2. In some implementations, the writing of the fls file (memory # of old implementations) may not respect the -output-directory # and -aux-directory options. @@ -5606,7 +5521,7 @@ sub correct_locations { push @other_fls_names, "latex.fls"; } if ( $aux_dir1 ne '' ) { - push @other_fls_names, "$root_filename.fls"; + push @other_fls_names, "$$Pbase.fls"; # The fls file may be in the opposite directory to the # one configured by $fls_uses_out_dir: push @other_fls_names, $fls_name_alt; @@ -5636,6 +5551,7 @@ sub correct_locations { sub find_log { # Locate log file generated on this run. + # Usage find_log( $log_aux, $log_out, $log_cwd) # Side effect: measure filetime offset if necessary. # Don't take other actions. # Returns @@ -5649,11 +5565,9 @@ sub find_log { # (only applies if $emulate_aux off) # 6 log file is in ., but out-of-date - + # Assumes rule context. + my ( $log_aux, $log_out, $log_cwd ) = @_; my $where_log = -1; # Nothing analyzed yet - my $log_aux = "$aux_dir1$root_filename.log"; - my $log_out = "$out_dir1$root_filename.log"; - my $log_cwd = "./$root_filename.log"; # Basic tests first that assume accuracy of time of file system: if ( test_gen_file_time( $log_aux ) ) { @@ -5699,7 +5613,9 @@ sub find_log { return 6; } return 0; -} +} #END find_log + +#--------------------- sub find_set_log { # Locate the log file, generated on this run. @@ -5734,13 +5650,11 @@ sub find_set_log { # Cases: 0, 4, 5, 6 are error conditions to be handled by caller # 2 is to be handled by caller by a rerun # 1 is success. + my $log_aux = "$aux_dir1$$Pbase.log"; + my $log_out = "$out_dir1$$Pbase.log"; + my $log_cwd = "./$$Pbase.log"; - - my $log_aux = "$aux_dir1$root_filename.log"; - my $log_out = "$out_dir1$root_filename.log"; - my $log_cwd = "./$root_filename.log"; - - my $where_log = &find_log; + my $where_log = find_log( $log_aux, $log_out, $log_cwd ); my $good_log_found = 0; if ($where_log == 1 ) { @@ -5752,7 +5666,7 @@ sub find_set_log { " But emulate_aux is off. So I'll turn it on.\n", " I'll copy the log file to the correct place.\n", " The next run of *latex **SHOULD** not have this problem.\n"; - copy( "$out_dir1$root_filename.log", "$aux_dir1$root_filename.log" ); + copy( $log_out, $log_aux ); $where_log = 2; $emulate_aux = 1; $emulate_aux_switched = 1; @@ -5768,8 +5682,8 @@ sub find_set_log { # .log file is not in out_dir nor in aux_dir, but is in cwd. # Presumably there is a configuration error # that prevents the directories from being used by latex. - die "$My_name: The log file found was '$root_filename.log' instead of\n", - " '$aux_dir1$root_filename.log'. Probably a configuration error\n", + die "$My_name: The log file found was '$log_cwd' instead of\n", + " '$log_aux'. Probably a configuration error\n", " prevented the use of the -aux-directory and/or the -output-directory\n", " options with the *latex command.\n", " I'll stop.\n"; @@ -5800,7 +5714,7 @@ sub find_set_log { $failure = 1; $$Plast_result = 2; $failure_msg - = "*LaTeX didn't generate the expected log file '$log_name'\n"; + = "*LaTeX didn't generate the expected log file '$log_aux'\n"; } return $where_log; @@ -5865,8 +5779,9 @@ sub parse_log { # # Input globals: $primary_out, $fls_file_analyzed # - my ($log_name, $PAlines, $PHinfo) = @_; + our ( $primary_out, $fls_file_analyzed, %generated_log, %idx_files, + %dependents, @bbl_files, %log_info, @missing_subdirs, %conversions ); # Give a quick way of looking up custom-dependency extensions my %cusdep_from = (); @@ -5899,7 +5814,8 @@ sub parse_log { my $tex_distribution = $$PHinfo{distribution}; # Now analyze the result: - $line_num = 0; + my $line_num = 0; + my @pwd_log = (); # Working directory as reported. !!?? CHECK CORRECTNESS my $state = 0; # 0 => before ** line, # 1 => after **filename line, before next line (first file-reading line) # 2 => pwd_log determined. @@ -5915,6 +5831,8 @@ sub parse_log { # data structure until block is ended.) my %new_conversions = (); my $log_silent = ($silent || $silence_logfile_warnings); + my $source_log; #Name of tex file that .log file reports as being on cmd line + our @warning_list; @warning_list = (); # Warnings about undefined citations and the like LINE: @@ -6398,7 +6316,7 @@ LINE: # Default includes are always definitive: foreach (@default_includes) { $dependents{$_} = 4; } - my @misparsed = (); + my @misparse = (); my @missing = (); my @not_found = (); @@ -7069,10 +6987,11 @@ sub parse_aux { # Return 3 if I couldn't locate all the bib_files # Set @new_aux_files to aux files parsed + our $Paux_files; my $aux_file = $_[0]; - local $Pbib_files = $_[1]; + my $Pbib_files = $_[1]; local $Paux_files = $_[2]; - local $Pbst_files = $_[3]; + my $Pbst_files = $_[3]; # Default return values @$Pbib_files = (); @$Pbst_files = (); @@ -7080,6 +6999,7 @@ sub parse_aux { # Map file specs (in \bibdata and \bibstyle lines) to actual filenames: + our ( %bib_files, %bst_files, @bad_bib_data ); local %bib_files = (); local %bst_files = (); @@ -7152,6 +7072,7 @@ sub parse_aux1 # Return 1 if success in opening $aux_file_name and parsing it # Return 0 if fail to open it { + our ( %bib_files, %bst_files, @bad_bib_data, $Paux_files ); my $aux_file = $_[0]; my $aux_fh; if (! open($aux_fh, $aux_file) ) { @@ -7159,9 +7080,10 @@ sub parse_aux1 return 0; } push @$Paux_files, $aux_file; + AUX_LINE: while (local $_ = <$aux_fh>) { - if ( /\^\^/ ) { + if ( /\^\^[[:xdigit:]]{2}/ ) { warn "$My_name: Line in '$aux_file' uses ^^ notation, which may\n". " cause trouble to bibtex:\n $_"; # At least I need to be able to handle the line: @@ -7234,7 +7156,6 @@ sub parse_bcf { # Win32 platform. To avoid requiring the installation, just search the # .bcf file for the relevant lines. # - # !!!!!!!!!!!!!!!!!??????????? Allow for remote bib files. use strict; # Global variables used @@ -7490,7 +7411,9 @@ sub rdb_read { # may/should be in the future.) # (e) Something else, e.g., copying/editing of fdb_latexmk file. # - local ($in_name, $inhibit_output_switch) = @_; + + our ( $dest, $run_time, $check_time, $inhibit_output_switch, $last_result ); + ( my $in_name, local $inhibit_output_switch ) = @_; my $in_handle; if ( ! -e $in_name ) { @@ -7499,7 +7422,7 @@ sub rdb_read { return -2; } if ( ! open( $in_handle, '<', $in_name ) ) { - warn "$My_name: Couldn't read '$fdb_name' even though it exists\n"; + warn "$My_name: Couldn't read '$in_name' even though it exists\n"; return -1; } print "$My_name: Examining fdb file '$fdb_name' for cached rules ...\n" @@ -7515,11 +7438,11 @@ sub rdb_read { my $rule = ''; local $run_time = 0; local $last_result = -1; - local $source = ''; + my $source = ''; local $dest = ''; my $base = ''; my %old_actives = (); # Hash: keys are rules in fdb_latexmk file - local %new_sources = (); # Hash: rule => { file=>[ time, size, md5, fromrule ] } + my %new_sources = (); # Hash: rule => { file=>[ time, size, md5, fromrule ] } my $new_source = undef; # Reference to hash of sources for current rule LINE: while (local $_ = <$in_handle>) { @@ -7633,6 +7556,7 @@ LINE: print "$My_name: File-database '$in_name': setting rule '$rule'\n" if $diagnostics; my $cmd_type = 'external'; + no strict "refs"; my $ext_cmd = ${$rule_generic}; print " Rule kind = '$rule_generic'; ext_cmd = '$ext_cmd';\n", " int_cmd = '$int_cmd';\n", @@ -7718,8 +7642,10 @@ LINE: sub rdb_read_set_rule { # Makes some settings for rule from data as read from .fdb_latexmk. # Rule context assumed. Implicit passing of $dest, $run_time, $check_time, - # $in_name used as local variables in calling routine rdb_read. + # $inhibit_output_switch, $last_result used as local variables in calling + # routine rdb_read. # + our ( $dest, $run_time, $check_time, $inhibit_output_switch, $last_result ); $$Pno_history = 0; $$Prun_time = $run_time; $$Pcheck_time = $check_time; @@ -7784,9 +7710,9 @@ sub rdb_write { # Writes to the given file name the database of file and rule data # for all rules needed to make final output # Returns 1 on success, 0 if file couldn't be opened. - local $out_name = $_[0]; + my $out_name = $_[0]; - local $out_handle; + my $out_handle; if ( ($out_name eq "") || ($out_name eq "-") ) { # Open STDOUT open( $out_handle, '>-' ); @@ -7807,7 +7733,7 @@ sub rdb_write { # Omit data on a unused and never-run primary rule: if ( ($$Prun_time == 0) && exists( $possible_primaries{$rule} ) - && ! exists( $current_primaries{$rule} ) + && ($rule ne $current_primary ) ) { return; @@ -7945,12 +7871,11 @@ sub rdb_set_latex_deps { # see pythontex-latexmk) for subroutine called to process a .tex to add items to # %PHdest. So initializing here is too late. - local ($inhibit_output_switch) = @_; - # Rules should only be primary + my ($inhibit_output_switch) = @_; if ( $$Pcmd_type ne 'primary' ) { warn "\n$My_name: ==========$My_name: Probable BUG======= \n ", " rdb_set_latex_deps called to set files ", - "for non-primary rule '$rule'\n\n"; + "for non-latex-like rule '$rule'\n\n"; return; } @@ -7959,6 +7884,9 @@ sub rdb_set_latex_deps { # Parse fls and log files to find relevant filenames # Result in the following variables: + our ( %dependents, @bbl_files, %idx_files, %generated_log, %generated_fls, + %source_fls, %first_read_after_write, %log_info, $pwd_latex, $primary_out, + @missing_subdirs, %conversions ); local %dependents = (); # Maps files to status local @bbl_files = (); local %idx_files = (); # Maps idx_file to (ind_file, base) @@ -7966,8 +7894,8 @@ sub rdb_set_latex_deps { local %generated_fls = (); # Lists generated files found in fls file local %source_fls = (); # Lists source files found in fls file local %first_read_after_write = (); # Lists source files that are only read - # after being written (so are not true - # source files). + # after being written (so are not true + # source files). local $primary_out = $$Pdest; # output file (dvi or pdf) local %conversions = (); # *latex-performed conversions. # Maps output file created and read by *latex @@ -7976,7 +7904,7 @@ sub rdb_set_latex_deps { local $pwd_latex = undef; # Cwd as reported in fls file by *latex - local %created_rules = (); # Maps files to rules existing or created to + my %created_rules = (); # Maps files to rules existing or created to # make them. Use to avoid misunderstood # dependencies when a package creates a # missing file during *latex compliation @@ -7999,7 +7927,7 @@ sub rdb_set_latex_deps { # can be set to use another program.) our $tex_distribution = ''; local %log_info = (); # Info. returned by get_log_file - local @log_lines = (); # Lines in log file after unwrapping and converting + my @log_lines = (); # Lines in log file after unwrapping and converting # to use my internal CS. # Get lines from log file now, with side effect of setting $engine and # $tex_distribution, so parse_fls can adjust its behavior if necessary). @@ -8012,11 +7940,11 @@ sub rdb_set_latex_deps { $tex_distribution = $log_info{distribution}; } - - + # Analyze fls file first. It tells us the working directory as seen by *latex # But we'll use the results later, so that they take priority over the findings # from the log file. + our $fls_file_analyzed; local $fls_file_analyzed = 0; if ($recorder && test_gen_file_time($fls_name) ) { $fls_file_analyzed = @@ -8187,7 +8115,7 @@ sub rdb_set_latex_deps { $created_rules{$ind_file} = $from_rule; } # end IDX_FILE - local %processed_aux_files = (); + my %processed_aux_files = (); BBL_FILE: foreach my $bbl_file ( uniqs( @bbl_files ) ) { my ($bbl_base, $bbl_path, $bbl_ext) = fileparseA( $bbl_file ); @@ -8351,7 +8279,6 @@ NEW_SOURCE: rdb_one_file( $new_source, sub{ $$Pcorrect_after_primary = 1; } ); } elsif ( $dependents{$new_source} == 8 ) { - print "================= REWRITE '$new_source'\n"; # File was read only after being written # and the file existed at the beginning of the run rdb_ensure_file( $rule, $new_source ); @@ -8494,6 +8421,7 @@ sub test_gen_file { # file being listed in %generated_log or %generated_fls # Assumes context for primary rule. my $file = shift; + our ( %generated_fls, %generated_log ); return exists $generated_log{$file} || $generated_fls{$file} || test_gen_file_time($file); } @@ -8601,7 +8529,7 @@ MISSING_FILE: # if ( $file =~ /\"/ ) {next; } my $stripped = $file; $stripped =~ s{^\./}{}; - if ( exists $PHsource{$file} ) { + if ( exists $$PHsource{$file} ) { delete $new_includes{$file}; } else { @@ -8621,6 +8549,7 @@ MISSING_FILE: sub rdb_set_dependents { # Call rdb_set_dependents( rules ...) # Returns array (sorted), of new source files for the given rules. + our ( @new_sources, @deletions ); local @new_sources = (); local @deletions = (); @@ -8664,7 +8593,8 @@ sub rdb_one_dep { if ( (! exists $possible_primaries{$rule}) && ($rule !~ /^cusdep/) ) { return; } - local $new_dest = $file; + our ( @new_sources, @deletions ); + my $new_dest = $file; if ($$PHdest{$new_dest} ) { # We already have a way of making the file. # No need to find another one. @@ -8697,13 +8627,13 @@ DEP: rdb_ensure_file( $rule, $new_new_dest ); $new_dest = $new_new_dest; } - local @PAnew_cmd = ( 'do_cusdep', $func_name ); + my @Anew_cmd = ( 'do_cusdep', $func_name ); if ( !-e $new_dest ) { push @new_sources, $new_dest; } if (! rdb_rule_exists( $from_rule ) ) { print "$My_name: === Creating rule '$from_rule'\n" if $diagnostics; - rdb_create_rule( $from_rule, 'cusdep', '', \@PAnew_cmd, 3, + rdb_create_rule( $from_rule, 'cusdep', '', \@Anew_cmd, 3, $source, $new_dest, $base_name, 0 ); } return; @@ -8748,10 +8678,10 @@ DEP: push @new_sources, $new_dest; print "$My_name: Ensuring rule for '$from_rule', to make '$new_dest'\n" if $diagnostics > -1; - local @PAnew_cmd = ( 'do_cusdep', $func_name ); + my @Anew_cmd = ( 'do_cusdep', $func_name ); if (! rdb_rule_exists( $from_rule ) ) { print "$My_name: === Creating rule '$from_rule'\n" if $diagnostics; - rdb_create_rule( $from_rule, 'cusdep', '', \@PAnew_cmd, 3, + rdb_create_rule( $from_rule, 'cusdep', '', \@Anew_cmd, 3, $source, $new_dest, $base_name, 0 ); } rdb_ensure_file( $rule, $new_dest, $from_rule ); @@ -8794,7 +8724,7 @@ DEP: push @deletions, [$rule, $file]; # Flag need for a new run of *latex despite # the error due to a missing file. - $$Pout_of_date_user = 1; + $$Pout_of_date_user = "Missing file '$new_dest' now exists"; return; } } @@ -8808,7 +8738,7 @@ sub rdb_list { # Call: rdb_list() # List rules and their source files print "===Rules:\n"; - local $count_rules = 0; + my $count_rules = 0; my @accessible_all = &rdb_accessible; rdb_for_some( \@accessible_all, @@ -8833,7 +8763,7 @@ sub deps_list { # Call: deps_list(fh) # List dependent files to file open on fh my $fh = $_[0]; - fprint8 $fh, "#===Dependents, and related info, for $filename:\n"; + fprint8( $fh, "#===Dependents, and related info, for $filename:\n" ); my @dest_exts = (); if ($pdf_mode) {push @dest_exts, '.pdf';} if ($dvi_mode) {push @dest_exts, '.dvi';} @@ -8843,7 +8773,7 @@ sub deps_list { my $deps_space = ' '; if ($deps_escape eq 'unix' ) { $deps_space = '\ '; } elsif ($deps_escape eq 'nmake' ) { $deps_space = '^ '; } - $Pescape = sub { + my $Pescape = sub { my $name = shift; $name =~ s/ /$deps_space/g; return $name; @@ -8876,19 +8806,19 @@ sub deps_list { # deps file out-of-date are the same as those that make the real # target file (e.g., .pdf) out-of-date. So the GNU method seems # completely unnecessary. - fprint8 $fh, &$Pescape(${out_dir1}.${root_filename}.${ext}), " :"; + fprint8( $fh, &$Pescape(${out_dir1}.${root_filename}.${ext}), " :" ); foreach (sort keys %source) { - fprint8 $fh, "\\\n ", &$Pescape($_); + fprint8( $fh, "\\\n ", &$Pescape($_) ); } - fprint8 $fh, "\n"; + fprint8( $fh, "\n" ); } - fprint8 $fh, "#===End dependents for $filename:\n"; + fprint8( $fh, "#===End dependents for $filename:\n" ); if ($dependents_phony) { - fprint8 $fh, "\n#===Phony rules for $filename:\n\n"; + fprint8( $fh, "\n#===Phony rules for $filename:\n\n" ); foreach (sort keys %source) { - fprint8 $fh, "$_ :\n\n"; + fprint8( $fh, "$_ :\n\n" ); } - fprint8 $fh, "#===End phony rules for $filename:\n"; + fprint8( $fh, "#===End phony rules for $filename:\n" ); } } #END deps_list @@ -8899,7 +8829,7 @@ sub rdb_show { # Displays contents of rule data base. # Side effect: Exercises access routines! print "===Rules:\n"; - local $count_rules = 0; + my $count_rules = 0; rdb_for_actives( sub{ $count_rules++; my @int_cmd = @$PAint_cmd; @@ -8943,7 +8873,7 @@ sub rdb_accessible { # Call: &rdb_accessible # Returns array of rules accessible from target rules and rules to make target files - local %accessible_rules = &rdb_target_hash; + my %accessible_rules = &rdb_target_hash; rdb_recurse( [keys %accessible_rules], sub{ $accessible_rules{$rule} = 1; } ); return keys %accessible_rules; } #END rdb_accessible @@ -9167,9 +9097,11 @@ sub rdb_make { # they are run by the calling routines, since the needs may be # quite special. - # ???!!! Overkill? + if ($compiling_cmd) { Run_subst( $compiling_cmd ); } + # ???!!! Overkill? No. $compiling_cmd might have injected something. &rdb_set_rule_net; + our %pass; local %pass = (); # Counts runs on each rule: Used for testing for # exceeding maximum runs and for determining # whether to run rules that have a list of source @@ -9187,12 +9119,14 @@ sub rdb_make { } ); + our ($runs, $runs_total, $too_many_passes, $newrule_nofile); local $failure = 0; # General accumulated error flag local $missing_dvi_pdf = ''; # Did primary run fail to make its output file? local $runs = 0; local $runs_total = 0; local $too_many_passes = 0; local $switched_primary_output = 0; + our @warning_list; local @warning_list = (); # Undef refs etc reported in last primary run my $retry_msg = 0; # Did I earlier say I was going to attempt # another pass after a failure? @@ -9275,7 +9209,7 @@ sub rdb_make { continue { # Re-evaluate rule classification and accessibility, # but do not change primaries. - # Problem is that %current_primaries gets altered + # Problem is that $current_primary gets altered &rdb_set_rule_net; } #End PASS @@ -9412,21 +9346,14 @@ sub rdb_make { print "$My_name: Errors, so I did not complete making targets\n"; } else { -# local @dests = ( keys %current_primaries, @pre_primary, @post_primary, @unusual_one_time ); - local @rules = ( keys %current_primaries, @post_primary, @unusual_one_time ); - local @dests = (); +# local @dests = ( $current_primary, @pre_primary, @post_primary, @unusual_one_time ); + my @rules = ( $current_primary, @post_primary, @unusual_one_time ); + my @dests = (); rdb_for_some( [@rules], sub{ push @dests, $$Pdest if ($$Pdest); } ); print "$My_name: All targets (@dests) are up-to-date\n"; } } - # ???!!! Rethink use of %pass, and it's scoping. - # Currently %pass is local in rdb_make and is used only to determine - # whether a rule needs to be run because a source rule has been run, - # and this would be within the same call to rdb_make. - # OLD COMMENT: Update source_rules. Is this too late? I don't think so, it's - # internal to make and to multiple calls to it (pvc). Is this - # necessary? rdb_for_some( [keys %rule_db], sub{ foreach my $s_rule (keys %$PHsource_rules) { @@ -9440,8 +9367,8 @@ sub rdb_make { #------------------- sub rdb_show_rule_errors { - local @errors = (); - local @warnings = (); + my @errors = (); + my @warnings = (); rdb_for_actives( sub { my $message_tail = ""; @@ -9489,7 +9416,8 @@ sub rdb_make1 { # Assumes contexts for recursion, make, and rule, and # assumes that source files for the rule are to be considered # up-to-date. - our $rule; + our ($rule, %pass, $runs, $runs_total, $too_many_passes, $newrule_nofile); + if ($diagnostics) { print " Make for rule '$rule'\n"; } # Is this needed? Yes; rdb_make1 is called on a sequence of rules and # if one gives an error, then it provides source files directly or @@ -9620,7 +9548,7 @@ sub rdb_run1 { $$Plast_result_info = 'CURR'; $$Plast_message = ''; my $latex_like = ($$Pcmd_type eq 'primary'); - + # Return value for external command: my $return = 0; @@ -9663,6 +9591,7 @@ sub rdb_run1 { if ($int_cmd) { print "For rule '$rule', use internal command '\&$int_cmd( @int_args_for_printing )' ...\n" if $diagnostics; + no strict "refs"; $return = &$int_cmd( @int_args ); } elsif ($$Pext_cmd) { @@ -9689,7 +9618,7 @@ sub rdb_run1 { # $$Pout_of_date = $$Pout_of_date_user = 0; if ($latex_like) { - &correct_locations; + correct_locations(); run_hooks( 'after_xlatex' ); $return = analyze_latex_run( $return ); run_hooks( 'after_xlatex_analysis' ); @@ -9838,7 +9767,7 @@ sub analyze_latex_run { if (-e $$Pdest) { $missing_dvi_pdf = '';} # Find current set of source files: - my ($missing_dirs, $PA_missing_subdirs, $bad_warnings) = &rdb_set_latex_deps; + my ($missing_dirs, $PA_missing_subdirs, $bad_warnings) = rdb_set_latex_deps(); if ($bad_warning_is_error && $bad_warnings) { warn "$My_name: Serious warnings in .log configured to be errors\n"; $return ||= $bad_warnings; @@ -9965,7 +9894,8 @@ sub rdb_user_changes { @{$changes_rule{changed_user}}; push @{$$PHchanges{rules_to_apply}}, $rule; $user_changes = 1; - $$Pout_of_date = $$Pout_of_date_user = $user_changes; + if ($user_changes) { $$Pout_of_date = $$Pout_of_date_user = 'Changed user file'; } + else { $$Pout_of_date = $$Pout_of_date_user = 0; } } } ); @@ -9989,15 +9919,12 @@ sub rdb_rerun_needed { # make_preview_continuous. Otherwise use rerun criterion suitable for # with rdb_make's looping through rules. # - # ???!!!! - # Check all uses!!!!!!!!!!!!! our ($rule, %pass); local our $PHchanges = shift; local our $outside_make_loop = shift; my $bibx_rule = ( $rule =~ /^(biber|bibtex)/ ); - # File level routine reports its results in %$PHchanges: maps kind of # change to ref to array of files with that kind of change. @@ -10010,7 +9937,7 @@ sub rdb_rerun_needed { my $rerun_needed = $$Pout_of_date; if ($rerun_needed) { push @{$$PHchanges{other}}, - "Rerun of '$rule' forced or previously required"; + "Rerun of '$rule' forced or previously required:\n Reason or flag: '$rerun_needed'"; goto rdb_rerun_needed_CLEAN_UP; } @@ -10022,6 +9949,7 @@ sub rdb_rerun_needed { $$Pcheck_time = time(); + our $dest_mtime; local $dest_mtime = 0; $dest_mtime = get_mtime($$Pdest) if ($$Pdest); @@ -10106,15 +10034,7 @@ sub rdb_rerun_needed { # rerun rule until there's a change in source file(s), which # presumably contain the cause of the error. # But there are other reasons for not rerunning: - if ( $$Psource && (! -e $$Psource) - && ( $$Pcmd_type ne 'primary' ) - ) { - # Main source file doesn't exist, and rule is NOT primary. - # No action, since a run is pointless. Primary is different: - # file might be found elsewhere (by kpsearch from *latex), - # while non-existence of main source file is a clear error. - } - elsif ( $$Pcmd_type eq 'delegated' ) { + if ( $$Pcmd_type eq 'delegated' ) { # Delegate to destination rule } elsif ( $$PHextra{bibx_vetoed} ) { @@ -10129,16 +10049,19 @@ sub rdb_rerun_needed { } rdb_rerun_needed_CLEAN_UP: + if ( $$Psource && (! -e $$Psource) && ( $$Pcmd_type ne 'primary' ) ) { + # Main source file doesn't exist, and rule is NOT primary. + # No action, since a run is pointless. Primary is different: + # file might be found elsewhere (by kpsearch from *latex), + # while non-existence of main source file is a clear error. + $rerun_needed = 0; + } foreach my $file ( @{$$PHchanges{changed}} ) { if ( ! $from_rules{$file} ) { push @{$$PHchanges{changed_user}}, $file; } } $$Pno_history = 0; # See comments in definition of %rule_db. - if ( $$Psource && (! -e $$Psource) ) { -# print "================In '$rule', no source '$$Psource'\n"; - } - if ( $bibx_rule ) { # Check whether run of biber/bibtex rule is to be vetoed. # Default to no veto: @@ -10184,7 +10107,7 @@ sub rdb_file_change1 { # Call: &rdb_file_change1 # Assumes rule and file context. Assumes $dest_mtime set. # Flag whether $file in $rule has changed or disappeared. - our ($rule, $file, $PHchanges); + our ($rule, $file, $PHchanges, $outside_make_loop, $dest_mtime); my $check_time_argument = ($outside_make_loop ? 0 : max($$Pcheck_time, $$Prun_time) ); @@ -10367,6 +10290,7 @@ sub rdb_recurse { # This routine sets a context for anything recursive, with @heads, # %visited and $depth being set as local variables. + our ($depth, @heads, %visited); local @heads = (); my $rules = shift; @@ -10417,6 +10341,7 @@ sub rdb_for_some { # Rule data and file data are made available in local variables # for access by the subroutines. + our (@heads); local @heads = (); my $rules = shift; # Distinguish between single rule (a string) and a reference to an @@ -10430,18 +10355,6 @@ sub rdb_for_some { } } #END rdb_for_some -#************************************************************ - -sub rdb_for_one_file { - # Use : rdb_for_one_file( rule, file, ref to action subroutine ) - my $rule = shift; - # Avoid name collisions with general recursion and iteraction routines: - local $file1 = shift; - local $action1 = shift; - rdb_for_some( $rule, sub{rdb_one_file($file1,$action1)} ); -} #END rdb_for_one_file - - #************************************************************ # Routines for inner part of recursion and iterations @@ -10455,10 +10368,13 @@ sub rdb_recurse_rule { # the sources of the rules. # Assumes recursion context, i.e. that %visited, @heads, $depth. # We are overriding actions: - my ($rule, $rule_act1, $new_file_act1, $new_file_act2, $rule_act2) + our (%visited, @heads, $depth); + our ($rule, $rule_act1, $new_file_act1, $new_file_act2, $rule_act2); + local ($rule, $rule_act1, $new_file_act1, $new_file_act2, $rule_act2) = @_; if (! rdb_is_active($rule)) { return; } # and must propagate the file actions: + our ( $file_act1, $file_act2 ); local $file_act1 = $new_file_act1; local $file_act2 = $new_file_act2; # Prevent loops: @@ -10481,6 +10397,7 @@ sub rdb_recurse_file { # This has no arguments, since it is used as an action subroutine, # passed as a reference in calls in higher-level subroutine. # Assumes contexts set for: Recursion, rule, and file + our ( $file_act1, $file_act2, $rule_act1, $rule_act2 ); &$file_act1 if $file_act1; my $from_rule = $from_rules{$file} || ''; rdb_recurse_rule( $from_rule, $rule_act1, $file_act1, $file_act2, @@ -10494,9 +10411,9 @@ sub rdb_recurse_file { sub rdb_do_files { # Assumes rule context, including $PHsource. # Applies an action to all the source files of the rule. - local $file_act = shift; + my $file_act = shift; my @file_list = sort keys %$PHsource; - foreach my $file ( @file_list ){ + foreach my $file ( @file_list ) { rdb_one_file( $file, $file_act ); } } #END rdb_do_files @@ -10514,7 +10431,8 @@ sub rdb_one_rule { # Sets context for rule and carries out the actions. #===== Accesses rule part of database structure ======= - local ( $rule, $rule_act1, $file_act, $rule_act2 ) = @_; + local $rule = shift; + my ( $rule_act1, $file_act, $rule_act2 ) = @_; if ( (! $rule) || ! rdb_rule_exists($rule) ) { die_trace( "$My_name: BUG in call to rdb_one_rule: non-existent rule '$rule'" ); } @@ -10592,7 +10510,8 @@ sub rdb_one_file { # Call: rdb_one_file($file, $file_act) # Sets context for file and carries out the action. # Assumes $rule context set. -#===== Accesses file part of database structure ======= + #===== Accesses file part of database structure ======= + our $file_act; local ($file, $file_act) = @_; if ( (!$file) ||(!exists ${$PHsource}{$file}) ) { return; } local $PAfile_data = ${$PHsource}{$file}; @@ -10645,6 +10564,7 @@ sub rdb_create_rule { foreach ( $needs_making, $run_time, $check_time, $DUMMY ) { if (! defined $_) { $_ = 0; } } + if ($needs_making) {$needs_making = 'Initial set up of rule'; } foreach ( $cmd_type, $ext_cmd, $PAint_cmd, $source, $dest, $base, $set_file_not_exists ) { if (! defined $_) { $_ = ''; } @@ -10758,8 +10678,7 @@ sub rdb_ensure_file { # (2) When initializing rules, when there is no previous # known run under the control of latexmk. #============ NOTE: rule and file data set here =============================== - my $rule = shift; - local ( $new_file, $new_from_rule, $set_not_exists ) = @_; + my ( $rule, $new_file, $new_from_rule, $set_not_exists ) = @_; if ( ! rdb_rule_exists( $rule ) ) { die_trace( "$My_name: BUG in call to rdb_ensure_file: non-existent rule '$rule'" ); } @@ -10799,18 +10718,19 @@ sub rdb_ensure_files_here { # as is appropriate if the file was read in latest run of rule use strict; our ($rule, $My_name, $PHsource, $Prun_time); - foreach (@_) { - if ( /\"/ ) { + foreach my $file (@_) { + # Use $file, not $_, since called subroutine may change it! + if ( $file =~ /\"/ ) { warn "$My_name: in rdb_ensure_files_here for rule '$rule', there\n", - " is a double quote in the filename: '$_'.\n", + " is a double quote in the filename: '$file'.\n", " I cannot handle this, will ignore this file.\n"; next; } - if (! exists ${$PHsource}{$_} ) { - ${$PHsource}{$_} = [fdb_get($_, $$Prun_time), '', 0]; + if (! exists ${$PHsource}{$file} ) { + ${$PHsource}{$file} = [fdb_get($file, $$Prun_time), '', 0]; } } -} #DN rdb_ensure_files_here +} #END rdb_ensure_files_here #************************************************************ @@ -10822,18 +10742,18 @@ sub rdb_ensure_new_files_here { # as is appropriate if the file is new to the rule use strict; our ($rule, $My_name, $PHsource, @nofile); - foreach (@_) { - if ( /\"/ ) { + foreach my $file (@_) { + if ( $file =~ /\"/ ) { warn "$My_name: in rdb_ensure_new_files_here for rule '$rule', there\n", - " is a double quote in the filename: '$_'.\n", + " is a double quote in the filename: '$file'.\n", " I cannot handle this, will ignore this file.\n"; next; } - if (! exists ${$PHsource}{$_} ) { - ${$PHsource}{$_} = [@nofile, '', 0]; + if (! exists ${$PHsource}{$file} ) { + ${$PHsource}{$file} = [@nofile, '', 0]; } } -} +} #END rdb_ensure_new_files_here #************************************************************ @@ -10842,7 +10762,7 @@ sub rdb_remove_files { # Removes file(s) for the rule. my $rule = shift; if (!$rule) { return; } - local @files = @_; + my @files = @_; rdb_one_rule( $rule, sub{ foreach (@files) { delete ${$PHsource}{$_}; } } ); @@ -10943,7 +10863,7 @@ sub rdb_file_exists { # Call rdb_file_exists($rule, $file): # Returns whether source file item in rule exists. local ( $rule, $file ) = @_; - local $exists = 0; + my $exists = 0; rdb_one_rule( $rule, sub{ $exists = exists( ${$PHsource}{$file} ) ? 1:0; } ); @@ -10985,12 +10905,12 @@ sub rdb_update1 { #************************************************************ sub rdb_set_file1 { - # Call: fdb_file1(rule, file, new_time, new_size, new_md5) - # Sets file time, size and md5. - my $rule = shift; - my $file = shift; - local @new_file_data = @_; - rdb_for_one_file( $rule, $file, sub{ ($$Ptime,$$Psize,$$Pmd5)=@new_file_data; } ); + # Call: rdb_set_file1(rule, file, new_time, new_size, new_md5) + # Sets file time, size and md5, in rule data. + my ( $rule, $file, @new_file_data ) = @_; + rdb_for_some( $rule, + sub{ rdb_one_file($file, sub{ ($$Ptime,$$Psize,$$Pmd5)=@new_file_data; } ); } + ); } #************************************************************ @@ -11045,11 +10965,11 @@ sub cus_dep_require_primary_run { # It is assumed that the resulting file will be read by the # primary run. - local $cus_dep_target = $$Pdest; + my $cus_dep_target = $$Pdest; # Loop over all active rules and source files: rdb_for_actives( 0, sub { if ($file eq $cus_dep_target) { - $$Pout_of_date = 1; + $$Pout_of_date = "A new file has been made"; $$Pcorrect_after_primary = 1; } } @@ -11499,7 +11419,7 @@ sub kpsewhich { $cmd =~ s/%[RBTDO]//g; $cmd =~ s/%S/@args/g; my @found = (); - local $fh; + my $fh; if ( $kpsewhich_show || $diagnostics ) { print "$My_name.kpsewhich: Running '$cmd'...\n"; } @@ -11576,8 +11496,9 @@ sub find_cus_dep { #################################################### sub add_hook { - # Usage: add_book( name of stack, name of orpointer to subroutine ) + # Usage: add_book( name of stack, name of or pointer to subroutine ) # Return 1 for success, 0 for failure. + no strict "refs"; our %hooks; my ($stack, $routine ) = @_; unless ( exists $hooks{$stack} ) { @@ -11694,7 +11615,7 @@ sub find_dirs { # is added to the list. # Non-existent directories and non-directories are removed from the list # Trailing "/"s and "\"s are removed - local @result = (); + my @result = (); my $find_action = sub { ## Subroutine for use in File::find @@ -11855,7 +11776,7 @@ sub split_search_path push @list, ""; } # Replace each blank argument (default) by current directory: - for ($i = 0; $i <= $#list ; $i++ ) { + for (my $i = 0; $i <= $#list ; $i++ ) { if ($list[$i] eq "") {$list[$i] = $default;} } return @list; @@ -12006,12 +11927,14 @@ sub Run { my @args = parse_quotes( $2 ); print "$My_name: calling $routine( $2 )\n" if (! $silent); + no strict "refs"; return ( 0, &$routine( @args ) ); } elsif ( $cmd_line =~ /^internal\s+([a-zA-Z_]\w*)\s*$/ ) { my $routine = $1; print "$My_name: calling $routine()\n" if (! $silent); + no strict "refs"; return ( 0, &$routine() ); } elsif ( $cmd_line =~ /^NONE/ ) { @@ -12207,7 +12130,7 @@ sub good_cwd { sub pushd { push @dir_stack, [cwd(), $cache{cwd}]; if ( $#_ > -1) { - local $ret = 0; + my $ret = 0; eval { if ( -d $_[0] ) { $ret = chdir dirname_no_tail( $_[0] ); @@ -12261,6 +12184,7 @@ sub end_wait { # Handler for break: Set global variable $have_break to 1. # Some systems (e.g., MSWin reset) appear to reset the handler. # So I'll re-enable it + our $have_break; &catch_break; $have_break = 1; } @@ -12289,3 +12213,128 @@ sub default_break { #************************************************************ #************************************************************ + +#************************************************************ +#************************************************************ +# Unicode manipuation and normalization +# Notes about Perl strings: +# 1. Strings have a flag utf8. +# a. If the utf8 flag is on, the string is to be interpreted as a sequence +# of code points. +# When "use utf8;" is used, a string containing non-ASCII characters +# has the utf8 flag set. +# If 'no bytes;' is in effect, the ordinal value for each item in the +# string is the Unicode code point value. +# b. If the utf8 flag is off for a string, the string is a sequence of +# bytes, to be interpreted according to whatever CS the user happens +# to choose to use. +# c. The utf8 flag is NOT to be interpreted as saying that the string is +# encoded as UTF-8, even though under the hood that may be the case. +# d. Indeed, setting 'use bytes;' appears to expose the internal +# byte-level representation of a string with the utf8 flag set, and +# that appears to be UTF-8. +# 2. The utf8 flag is quite confusing in its meaning. +# 3. When encode is applied to a string whose utf8 flag is on, the result +# is a string with the utf8 flag off, and the result consists of a sequence +# of bytes in the chosen encoding scheme, which may be chosen as UTF-8. +# 4. Strings received from the command line have the utf8 flag off and are +# encoded in whatever CS the OS/terminal is using. +# 5. When a string is supplied to print (or c), by default: +# a. If the utf8 flag is off or if 'use bytes;' is in effect, then the +# string is sent as a sequence of bytes. They are UTF-8 coded if +# the utf8 flag is on and 'use bytes;' is in effect. +# b. If the utf8 flag is on and if 'no bytes;' is in effect, then mostly +# garbage results for non-ASCII characters; the string must first be +# encoded as a byte string, in the CS suitable for the OS. +# c. Correct results are obtained when the utf8 flag is on and 'no bytes' +# is used when the binmode for the file handle is set suitably. +# 6. Generally OS calls and interactions with the OS need encoded byte strings. +# 7. Even more generally, interaction with the external world, including file +# contents is in terms of byte strings, with some CS chosen by default, by +# the user, or the OS. Unix-like OSs: Default is UTF-8, but as much by +# convention as by a requirement of the OS. + +#------------------------------------- + +sub utf8_to_mine { + # Given string encoded in UTF-8, return encoded string in my current CS. + # Don't use Encode::from_to, which does in-place conversion. + if ($no_CP_conversions) { return $_[0]; } + else { return encode( $CS_system, decode('UTF-8', $_[0])); } +} + +#------------------------------------- + +sub utf8_to_mine_errors { + # Given string encoded in UTF-8, return encoded string in my current CS. + # Don't use Encode::from_to, which does in-place conversion. + # Assume coding of input string is correctly UTF-8, but + # check for correct encoding in CS_system. + # Error message is returned in $@. No error => $@ is null string. + # (Same style as eval!) + $@ = ''; + if ($no_CP_conversions) { return $_[0]; } + else { + my $result = ''; + eval { + $result = encode( $CS_system, + decode('UTF-8', $_[0]), + Encode::FB_CROAK | Encode::LEAVE_SRC + ); + }; + return $result; + } +} + +#------------------------------------- + +sub config_to_mine { + # Ensure that configuration strings about files and directories are + # encoded in system CS. + # Configuration strings set in an rc file SHOULD either be: + # a. ASCII only, with Perl's utf8 flag off. + # b. Containing non-ASCII characters, with utf8 flag on. + # These need to be converted to encoded strings in system CS (and + # hence with utf8 flag off). + # Configuration variables set from the command line, e.g., from an + # -outdir=... option, are already in the system CS, because that is + # how strings are passed on the command line. + # So we just need to do a conversion for strings with utf8 flag on: + foreach ( $out_dir, $aux_dir, @default_files, @default_excluded_files ) { + if (utf8::is_utf8($_)) { $_ = encode( $CS_system, $_ ); } + } +} #END config_to_mine + +#************************************************************ + +sub mine_to_utf8 { + # Given string encoded in my current CS, return utf-8 encoded string. + # Don't use Encode::from_to, which does in-place conversion. + if ($no_CP_conversions) { return $_[0]; } + else { return encode( 'UTF-8', decode($CS_system, $_[0])); } +} + +#------------------------------------- + +sub is_valid_utf8 { + eval { decode( 'UTF-8', $_[0], (Encode::FB_CROAK | Encode::LEAVE_SRC ) ); }; + if ($@) { return 0; } + else { return 1; } +} + +#------------------------------------- + +sub fprint8 { + # Usage: fprint8( handle, data array) + # Write to file converting from my CS to UTF-8 + my $fh = shift; + print $fh mine_to_utf8( join( '', @_ ) ); +} + +#------------------------------------- + +################################################################ + + + + diff --git a/support/latexmk/latexmk.txt b/support/latexmk/latexmk.txt index cf97de03fe..462e9a80da 100644 --- a/support/latexmk/latexmk.txt +++ b/support/latexmk/latexmk.txt @@ -61,7 +61,7 @@ DESCRIPTION - 10 January 2024 1 + 31 January 2024 1 @@ -127,7 +127,7 @@ LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE - 10 January 2024 2 + 31 January 2024 2 @@ -188,12 +188,12 @@ LATEXMK(1) General Commands Manual LATEXMK(1) sionally result from filenames that have been incorrectly quoted on the command line. In addition, under Microsoft Windows, the forward slash character "\" is a directory separator, so latexmk - replaces it by a backward slash "/", which is also a legal di- - rectory separator in Windows, and is accepted by latex etc. + replaces it by a forward slash "/", which is also a legal direc- + tory separator in Windows, and is accepted by latex etc. - 10 January 2024 3 + 31 January 2024 3 @@ -203,21 +203,21 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -auxdir=FOO or -aux-directory=FOO - Sets the directory for auxiliary output files of *latex (.aux, - .log etc). These are all the generated files, with the excep- + Sets the directory for auxiliary output files of *latex (.aux, + .log etc). These are all the generated files, with the excep- tion of final output files (.dvi, .ps, .pdf, .synctex.gz, .sync- - tex). See the -outdir/-output-directory option for directories + tex). See the -outdir/-output-directory option for directories for the final output files. If the directory specified for the -aux/-aux-directory option is - blank, then the default is used, which is to be the same as the + blank, then the default is used, which is to be the same as the output directory. If you also use the -cd option, and the specified auxiliary out- - put directory is a relative path, then the path is interpreted + put directory is a relative path, then the path is interpreted relative to the document directory. - See the section AUXILIARY AND OUTPUT DIRECTORIES for more de- + See the section AUXILIARY AND OUTPUT DIRECTORIES for more de- tails. @@ -225,41 +225,41 @@ LATEXMK(1) General Commands Manual LATEXMK(1) When the source file uses bbl files for bibliography, run bibtex or biber as needed to regenerate the bbl files. - This property can also be configured by setting the $bibtex_use + This property can also be configured by setting the $bibtex_use variable to 2 in a configuration file. -bibtex- - Never run bibtex or biber. Also, always treat .bbl files as + Never run bibtex or biber. Also, always treat .bbl files as precious, i.e., do not delete them in a cleanup operation. - A common use for this option is when a document comes from an - external source, complete with its bbl file(s), and the user - does not have the corresponding bib files available. In this - situation use of the -bibtex- option will prevent latexmk from + A common use for this option is when a document comes from an + external source, complete with its bbl file(s), and the user + does not have the corresponding bib files available. In this + situation use of the -bibtex- option will prevent latexmk from trying to run bibtex or biber, which would result in overwriting of the bbl files. - This property can also be configured by setting the $bibtex_use + This property can also be configured by setting the $bibtex_use variable to 0 in a configuration file. -bibtex-cond - When the source file uses a bbl file for the bibliography and - bibtex is used to generate the bibliography, run bibtex as - needed to regenerate the bbl files only if the relevant bib - file(s) exist. Thus when the bib file(s) are not available, + When the source file uses a bbl file for the bibliography and + bibtex is used to generate the bibliography, run bibtex as + needed to regenerate the bbl files only if the relevant bib + file(s) exist. Thus when the bib file(s) are not available, bibtex is not run, thereby avoiding overwriting of the bbl file. - Also, always treat .bbl files as precious, i.e., do not delete + Also, always treat .bbl files as precious, i.e., do not delete them in a cleanup operation. - This is the default setting. It can also be configured by set- + This is the default setting. It can also be configured by set- ting the $bibtex_use variable to 1 in a configuration file. - 10 January 2024 4 + 31 January 2024 4 @@ -268,21 +268,21 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - The reason for using this setting is first to allow automatic + The reason for using this setting is first to allow automatic switching between the use and non-use of bibtex depending on the - existence or not of a bib file. In addition, when submitting - articles to a scientific journal, it is common to submit only - .tex and .bbl files (plus graphics files), but not a .bib file. - Hence it is often useful to treat .bbl files as true source + existence or not of a bib file. In addition, when submitting + articles to a scientific journal, it is common to submit only + .tex and .bbl files (plus graphics files), but not a .bib file. + Hence it is often useful to treat .bbl files as true source files, that should be preserved under a clean up operation. - This property can also be configured by setting the $bibtex_use + This property can also be configured by setting the $bibtex_use variable to 1 in a configuration file. Note that when biber is used, and a bib file doesn't exist, this - option does not prevent biber from being run, with the bbl file - then being incorrect. See the documentation on $bibtex_use for - more details. However, a bbl file is treated as precious in a + option does not prevent biber from being run, with the bbl file + then being incorrect. See the documentation on $bibtex_use for + more details. However, a bbl file is treated as precious in a clean up operation. @@ -290,42 +290,42 @@ LATEXMK(1) General Commands Manual LATEXMK(1) The same as -bibtex-cond except that .bbl files are only treated as precious if one or more bibfiles fails to exist. - Thus if all the bib files exist, bibtex is run to generate .bbl - files as needed, and then it is appropriate to delete the bbl + Thus if all the bib files exist, bibtex is run to generate .bbl + files as needed, and then it is appropriate to delete the bbl files in a cleanup operation since they can be re-generated. - This property can also be configured by setting the $bibtex_use + This property can also be configured by setting the $bibtex_use variable to 1.5 in a configuration file. Note that when biber is used, and a bib file doesn't exist, this - option does not prevent biber from being run, with the bbl file - then being incorrect. See the documentation on $bibtex_use for - more details. However, a bbl file is treated as precious in a + option does not prevent biber from being run, with the bbl file + then being incorrect. See the documentation on $bibtex_use for + more details. However, a bbl file is treated as precious in a clean up operation. -bibtexfudge or -bibfudge - Turn on the change-directory fudge for bibtex. See documenta- + Turn on the change-directory fudge for bibtex. See documenta- tion of $bibtex_fudge for details. -bibtexfudge- or -bibfudge- - Turn off the change-directory fudge for bibtex. See documenta- + Turn off the change-directory fudge for bibtex. See documenta- tion of $bibtex_fudge for details. -bm - A banner message to print diagonally across each page when con- - verting the dvi file to postscript. The message must be a sin- - gle argument on the command line so be careful with quoting + A banner message to print diagonally across each page when con- + verting the dvi file to postscript. The message must be a sin- + gle argument on the command line so be careful with quoting spaces and such. - Note that if the -bm option is specified, the -ps option is as- + Note that if the -bm option is specified, the -ps option is as- sumed. - 10 January 2024 5 + 31 January 2024 5 @@ -335,16 +335,16 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -bi - How dark to print the banner message. A decimal number between + How dark to print the banner message. A decimal number between 0 and 1. 0 is black and 1 is white. The default is 0.95, which is OK unless your toner cartridge is getting low. -bs - A decimal number that specifies how large the banner message - will be printed. Experimentation is necessary to get the right - scale for your message, as a rule of thumb the scale should be - about equal to 1100 divided by the number of characters in the + A decimal number that specifies how large the banner message + will be printed. Experimentation is necessary to get the right + scale for your message, as a rule of thumb the scale should be + about equal to 1100 divided by the number of characters in the message. The default is 220.0 which is just right for 5 charac- ter messages. @@ -356,42 +356,42 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -c Clean up (remove) all regeneratable files generated by latex and bibtex or biber except dvi, postscript and pdf. These files are - a combination of log files, aux files, latexmk's database file - of source file information, and those with extensions specified - in the @generated_exts configuration variable. In addition, + a combination of log files, aux files, latexmk's database file + of source file information, and those with extensions specified + in the @generated_exts configuration variable. In addition, files specified by the $clean_ext and @generated_exts configura- tion variables are removed. - This cleanup is instead of a regular make. See the -gg option + This cleanup is instead of a regular make. See the -gg option if you want to do a cleanup followed by a make. - Treatment of .bbl files: If $bibtex_use is set to 0 or 1, bbl - files are always treated as non-regeneratable. If $bibtex_use + Treatment of .bbl files: If $bibtex_use is set to 0 or 1, bbl + files are always treated as non-regeneratable. If $bibtex_use is set to 1.5, bbl files are counted as non-regeneratable condi- - tionally: If the bib file exists, then bbl files are regenerat- - able, and are deleted in a clean up. But if $bibtex_use is 1.5 - and a bib file doesn't exist, then the bbl files are treated as + tionally: If the bib file exists, then bbl files are regenerat- + able, and are deleted in a clean up. But if $bibtex_use is 1.5 + and a bib file doesn't exist, then the bbl files are treated as non-regeneratable and hence are not deleted. - In contrast, if $bibtex_use is set to 2, bbl files are always + In contrast, if $bibtex_use is set to 2, bbl files are always treated as regeneratable, and are deleted in a cleanup. - Treatment of files generated by custom dependencies: If - $cleanup_includes_cusdep_generated is nonzero, regeneratable - files are considered as including those generated by custom de- - pendencies and are also deleted. Otherwise these files are not + Treatment of files generated by custom dependencies: If + $cleanup_includes_cusdep_generated is nonzero, regeneratable + files are considered as including those generated by custom de- + pendencies and are also deleted. Otherwise these files are not deleted. -C Clean up (remove) all regeneratable files generated by latex and bibtex or biber. This is the same as the -c option with the ad- - dition of dvi, postscript and pdf files, and those specified in + dition of dvi, postscript and pdf files, and those specified in the $clean_full_ext configuration variable. - 10 January 2024 6 + 31 January 2024 6 @@ -400,64 +400,64 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - This cleanup is instead of a regular make. See the -gg option + This cleanup is instead of a regular make. See the -gg option if you want to do a cleanup followed by a make. - See the -c option for the specification of whether or not .bbl + See the -c option for the specification of whether or not .bbl files are treated as non-regeneratable or regeneratable. - If $cleanup_includes_cusdep_generated is nonzero, regeneratable - files are considered as including those generated by custom de- - pendencies and are also deleted. Otherwise these files are not + If $cleanup_includes_cusdep_generated is nonzero, regeneratable + files are considered as including those generated by custom de- + pendencies and are also deleted. Otherwise these files are not deleted. - -CA (Obsolete). Now equivalent to the -C option. See that option + -CA (Obsolete). Now equivalent to the -C option. See that option for details. - -cd Change to the directory containing the main source file before - processing it. Then all the generated files (.aux, .log, .dvi, + -cd Change to the directory containing the main source file before + processing it. Then all the generated files (.aux, .log, .dvi, .pdf, etc) will be relative to the source file. - This option is particularly useful when latexmk is invoked from - a GUI configured to invoke latexmk with a full pathname for the + This option is particularly useful when latexmk is invoked from + a GUI configured to invoke latexmk with a full pathname for the source file. - This option works by setting the $do_cd configuration variable - to one; you can set that variable if you want to configure la- + This option works by setting the $do_cd configuration variable + to one; you can set that variable if you want to configure la- texmk to have the effect of the -cd option without specifying it on the command line. See the documentation for that variable. - -cd- Do NOT change to the directory containing the main source file + -cd- Do NOT change to the directory containing the main source file before processing it. Then all the generated files (.aux, .log, - .dvi, .pdf, etc) will be relative to the current directory + .dvi, .pdf, etc) will be relative to the current directory rather than the source file. - This is the default behavior and corresponds to the behavior of + This is the default behavior and corresponds to the behavior of the *latex programs. However, it is not desirable behavior when - latexmk is invoked by a GUI configured to invoke latexmk with a + latexmk is invoked by a GUI configured to invoke latexmk with a full pathname for the source file. See the -cd option. - This option works by setting the $do_cd configuration variable - to zero. See the documentation for that variable for more in- + This option works by setting the $do_cd configuration variable + to zero. See the documentation for that variable for more in- formation. - -CF Remove the file containing the database of source file informa- + -CF Remove the file containing the database of source file informa- tion, before doing the other actions requested. - -d Set draft mode. This prints the banner message "DRAFT" across - your page when converting the dvi file to postscript. Size and + -d Set draft mode. This prints the banner message "DRAFT" across + your page when converting the dvi file to postscript. Size and intensity can be modified with the -bs and -bi options. The -bm - option will override this option as this is really just a short + option will override this option as this is really just a short way of specifying: - 10 January 2024 7 + 31 January 2024 7 @@ -468,27 +468,27 @@ LATEXMK(1) General Commands Manual LATEXMK(1) latexmk -bm DRAFT - Note that if the -d option is specified, the -ps option is as- + Note that if the -d option is specified, the -ps option is as- sumed. -deps Show a list of dependent files after processing. This is in the - form of a dependency list of the form used by the make program, + form of a dependency list of the form used by the make program, and it is therefore suitable for use in a Makefile. It gives an overall view of the files without listing intermediate files, as well as latexmk can determine them. - By default the list of dependent files is sent to stdout (i.e., - normally to the screen unless you've redirected latexmk's out- + By default the list of dependent files is sent to stdout (i.e., + normally to the screen unless you've redirected latexmk's out- put). But you can set the filename where the list is sent by the -deps-out= option. - See the section "USING latexmk WITH make" for an example of how + See the section "USING latexmk WITH make" for an example of how to use a dependency list with make. - Users familiar with GNU automake and gcc will find that the - -deps option is very similar in its purpose and results to the - -M option to gcc. (In fact, latexmk also has options -M, -MF, + Users familiar with GNU automake and gcc will find that the + -deps option is very similar in its purpose and results to the + -M option to gcc. (In fact, latexmk also has options -M, -MF, and -MP options that behave like those of gcc.) @@ -496,7 +496,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Equivalent to -deps. - -deps- Do not show a list of dependent files after processing. (This + -deps- Do not show a list of dependent files after processing. (This is the default.) @@ -506,24 +506,24 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -deps-escape= Set the kind of escaping used for spaces in the dependency list. - The possible values are "none", "unix", "nmake", corresponding - respectively to no escaping, escaping with a "\" suitable for - standard Unix make, and escaping with "^", suitable for Mi- + The possible values are "none", "unix", "nmake", corresponding + respectively to no escaping, escaping with a "\" suitable for + standard Unix make, and escaping with "^", suitable for Mi- crosoft's nmake. -deps-out=FILENAME - Set the filename to which the list of dependent files is writ- - ten. If the FILENAME argument is omitted or set to "-", then + Set the filename to which the list of dependent files is writ- + ten. If the FILENAME argument is omitted or set to "-", then the output is sent to stdout. - Use of this option also turns on the output of the list of de- + Use of this option also turns on the output of the list of de- pendent files after processing. - 10 January 2024 8 + 31 January 2024 8 @@ -532,10 +532,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - -dF Dvi file filtering. The argument to this option is a filter - which will generate a filtered dvi file with the extension - ".dviF". All extra processing (e.g. conversion to postscript, - preview, printing) will then be performed on this filtered dvi + -dF Dvi file filtering. The argument to this option is a filter + which will generate a filtered dvi file with the extension + ".dviF". All extra processing (e.g. conversion to postscript, + preview, printing) will then be performed on this filtered dvi file. Example usage: To use dviselect to select only the even pages of @@ -545,26 +545,26 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -diagnostics - Print detailed diagnostics during a run. This may help for de- - bugging problems or to understand latexmk's behavior in diffi- + Print detailed diagnostics during a run. This may help for de- + bugging problems or to understand latexmk's behavior in diffi- cult situations. -dir-report - For each .tex file processed, list the settings for aux and out - directories, after they have been normalized from the settings - specified during initialization. See the description of the + For each .tex file processed, list the settings for aux and out + directories, after they have been normalized from the settings + specified during initialization. See the description of the variable $aux_out_dir_report for more details. -dir-report- - Do not report the settings for aux and out directories. (De- + Do not report the settings for aux and out directories. (De- fault) -dir-report-only - After all initialization is complete, give the settings for the - aux and out directories, and then halt. This option is primar- + After all initialization is complete, give the settings for the + aux and out directories, and then halt. This option is primar- ily used for debugging configuration issues. @@ -572,24 +572,24 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -dvilua - Generate dvi version of document using lualatex instead of la- + Generate dvi version of document using lualatex instead of la- tex. - -dvi- Turn off generation of dvi version of document. (This may get - overridden, if some other file is made (e.g., a .ps file) that - is generated from the dvi file, or if no generated file at all + -dvi- Turn off generation of dvi version of document. (This may get + overridden, if some other file is made (e.g., a .ps file) that + is generated from the dvi file, or if no generated file at all is requested.) -dvilualatex="COMMAND" This sets the string specifying the command to run dvi lualatex. - It behaves like the -pdflatex option, but sets the variable + It behaves like the -pdflatex option, but sets the variable $dvilualatex. - 10 January 2024 9 + 31 January 2024 9 @@ -598,44 +598,44 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - Note: This option when provided with the COMMAND argument only - sets the command for invoking dvilualatex; it does not turn on - the use of dvilualatex. That is done by other options or in an + Note: This option when provided with the COMMAND argument only + sets the command for invoking dvilualatex; it does not turn on + the use of dvilualatex. That is done by other options or in an initialization file. -e - Execute the specified initialization code before processing. - The code is Perl code of the same form as is used in latexmk's - initialization files. For more details, see the information on - the -r option, and the section about "Configuration/initializa- - tion (RC) files". The code is typically a sequence of assign- + Execute the specified initialization code before processing. + The code is Perl code of the same form as is used in latexmk's + initialization files. For more details, see the information on + the -r option, and the section about "Configuration/initializa- + tion (RC) files". The code is typically a sequence of assign- ment statements separated by semicolons. - The code is executed when the -e option is encountered during - latexmk's parsing of its command line. See the -r option for a - way of executing initialization code from a file. An error re- - sults in latexmk stopping. Multiple instances of the -r and -e + The code is executed when the -e option is encountered during + latexmk's parsing of its command line. See the -r option for a + way of executing initialization code from a file. An error re- + sults in latexmk stopping. Multiple instances of the -r and -e options can be used, and they are executed in the order they ap- pear on the command line. Some care is needed to deal with proper quoting of special char- - acters in the code on the command line. For example, suppose - you want to set the latex command to use its -shell-escape op- + acters in the code on the command line. For example, suppose + you want to set the latex command to use its -shell-escape op- tion, then under UNIX/Linux you could use the line latexmk -e '$latex=q/latex %O -shell-escape %S/' file.tex - Note that the single quotes block normal UNIX/Linux command - shells from treating the characters inside the quotes as spe- - cial. (In this example, the q/.../ construct is a Perl idiom - equivalent to using single quotes. This avoids the complica- - tions of getting a quote character inside an already quoted - string in a way that is independent of both the shell and the + Note that the single quotes block normal UNIX/Linux command + shells from treating the characters inside the quotes as spe- + cial. (In this example, the q/.../ construct is a Perl idiom + equivalent to using single quotes. This avoids the complica- + tions of getting a quote character inside an already quoted + string in a way that is independent of both the shell and the operating-system.) - The above command line will NOT work under MS-Windows with - cmd.exe or command.com or 4nt.exe. For MS-Windows with these + The above command line will NOT work under MS-Windows with + cmd.exe or command.com or 4nt.exe. For MS-Windows with these command shells you could use latexmk -e "$latex=q/latex %O -shell-escape %S/" file.tex @@ -644,18 +644,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) latexmk -e "$latex='latex %O -shell-escape %S'" file.tex - The last two examples will NOT work with UNIX/Linux command + The last two examples will NOT work with UNIX/Linux command shells. - (Note: the above examples show are to show how to use the -e to - specify initialization code to be executed. But the particular + (Note: the above examples show are to show how to use the -e to + specify initialization code to be executed. But the particular effect can be achieved also by the use of the -latex option with less problems in dealing with quoting.) - 10 January 2024 10 + 31 January 2024 10 @@ -666,45 +666,45 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -emulate-aux-dir Emulate the use of an aux directory instead of leaving it to the - *latex programs to do it. (MiKTeX supports -aux-directory, but + *latex programs to do it. (MiKTeX supports -aux-directory, but TeXLive doesn't.) - See the section AUXILIARY AND OUTPUT DIRECTORIES for more de- + See the section AUXILIARY AND OUTPUT DIRECTORIES for more de- tails. -emulate-aux-dir- Turn off emulation to implement an aux directory and leave it to - the *latex program to handle the case that the aux directory is - different from the output directory. Note that if you use - TeXLive, which doesn't support -aux-directory, latexmk will au- - tomatically switch aux_dir emulation on after the first run of + the *latex program to handle the case that the aux directory is + different from the output directory. Note that if you use + TeXLive, which doesn't support -aux-directory, latexmk will au- + tomatically switch aux_dir emulation on after the first run of *latex, because it will find the .log file in the wrong place. - -f Force latexmk to continue document processing despite errors. + -f Force latexmk to continue document processing despite errors. Normally, when latexmk detects that LaTeX or another program has found an error which will not be resolved by further processing, no further processing is carried out. - Note: "Further processing" means the running of other programs - or the rerunning of latex (etc) that would be done if no errors - had occurred. If instead, or additionally, you want the latex - (etc) program not to pause for user input after an error, you - should arrange this by an option that is passed to the program, - e.g., by latexmk's option -interaction=nonstopmode (which la- + Note: "Further processing" means the running of other programs + or the rerunning of latex (etc) that would be done if no errors + had occurred. If instead, or additionally, you want the latex + (etc) program not to pause for user input after an error, you + should arrange this by an option that is passed to the program, + e.g., by latexmk's option -interaction=nonstopmode (which la- texmk passes to *latex). -f- Turn off the forced processing-past-errors such as is set by the - -f option. This could be used to override a setting in a con- + -f option. This could be used to override a setting in a con- figuration file. - -g Force latexmk to process document fully, even under situations - where latexmk would normally decide that no changes in the - source files have occurred since the previous run. This option - is useful, for example, if you change some options and wish to + -g Force latexmk to process document fully, even under situations + where latexmk would normally decide that no changes in the + source files have occurred since the previous run. This option + is useful, for example, if you change some options and wish to reprocess the files. @@ -721,7 +721,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 11 + 31 January 2024 11 @@ -730,24 +730,24 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - -hnt Generate hnt (HINT) version of document using hilatex. (And + -hnt Generate hnt (HINT) version of document using hilatex. (And turn off dvi, postscript, and pdf modes.) -jobname=STRING - Set the basename of output files(s) to STRING, instead of the - default, which is the basename of the specified TeX file. (At + Set the basename of output files(s) to STRING, instead of the + default, which is the basename of the specified TeX file. (At present, STRING should not contain spaces.) - This is like the same option for current implementations of the + This is like the same option for current implementations of the *latex, and the passing of this option to these programs is part of latexmk's implementation of -jobname. There is one enhancement, that the STRING may contain the place- holder '%A'. This will be substituted by the basename of the TeX - file. The primary purpose is when multiple files are specified - on the command line to latexmk, and you wish to use a jobname - with a different file-dependent value for each file. For exam- + file. The primary purpose is when multiple files are specified + on the command line to latexmk, and you wish to use a jobname + with a different file-dependent value for each file. For exam- ple, suppose you had .tex files test1.tex and test2.tex, and you wished to compare the results of compilation by *latex and those with xelatex. Then under a unix-type operating system you could @@ -756,13 +756,13 @@ LATEXMK(1) General Commands Manual LATEXMK(1) latexmk -pdf -jobname=%A-pdflatex *.tex latexmk -pdfxe -jobname=%A-xelatex *.tex - Then the .aux, .log, and .pdf files from the use of pdflatex - would have basenames test1-pdflatex and test2-pdflatex, while + Then the .aux, .log, and .pdf files from the use of pdflatex + would have basenames test1-pdflatex and test2-pdflatex, while from xelatex, the basenames would be test1-xelatex and test2-xe- latex. Under MS-Windows with cmd.exe, you would need to double the per- - cent sign, so that the percent character is passed to latexmk + cent sign, so that the percent character is passed to latexmk rather than being used to substitute an environment variable: latexmk -pdf -jobname=%%A-pdflatex *.tex @@ -770,24 +770,24 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -l Run in landscape mode, using the landscape mode for the preview- - ers and the dvi to postscript converters. This option is not - normally needed nowadays, since current previewers normally de- + ers and the dvi to postscript converters. This option is not + normally needed nowadays, since current previewers normally de- termine this information automatically. -l- Turn off -l. - -latex This sets the generation of dvi files by latex, and turns off + -latex This sets the generation of dvi files by latex, and turns off the generation of pdf and ps files. - Note: to set the command used when latex is specified, see the + Note: to set the command used when latex is specified, see the -latex="COMMAND" option. - 10 January 2024 12 + 31 January 2024 12 @@ -798,20 +798,20 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -latex="COMMAND" This sets the string specifying the command to run latex, and is - typically used to add desired options. Since the string nor- + typically used to add desired options. Since the string nor- mally contains spaces, it should be quoted, e.g., latexmk -latex="latex --shell-escape %O %S" foo.tex - The specification of the contents of the string are the same as - for the $latex configuration variable. Depending on your oper- - ating system and the command-line shell you are using, you may - need to change the single quotes to double quotes (or something + The specification of the contents of the string are the same as + for the $latex configuration variable. Depending on your oper- + ating system and the command-line shell you are using, you may + need to change the single quotes to double quotes (or something else). - Note: This option when provided with the COMMAND argument only + Note: This option when provided with the COMMAND argument only sets the command for invoking latex; it does not turn on the use - of latex. That is done by other options or in an initialization + of latex. That is done by other options or in an initialization file. To set the command for running pdflatex (rather than the command @@ -819,31 +819,31 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -logfilewarninglist - -logfilewarnings After a run of *latex, give a list of warnings - about undefined citations and references (unless silent mode is + -logfilewarnings After a run of *latex, give a list of warnings + about undefined citations and references (unless silent mode is on). See also the $silence_logfile_warnings configuration variable. -logfilewarninglist- - -logfilewarnings- After a run of *latex, do not give a list of + -logfilewarnings- After a run of *latex, do not give a list of warnings about undefined citations and references. (Default) See also the $silence_logfile_warnings configuration variable. -lualatex - Use lualatex. That is, use lualatex to process the source - file(s) to pdf. The generation of dvi and postscript files is + Use lualatex. That is, use lualatex to process the source + file(s) to pdf. The generation of dvi and postscript files is turned off. This option is equivalent to using the following set of options -pdflua -dvi- -ps- - (Note: Note that the method of implementation of this option, - but not its intended effect, differ from some earlier versions + (Note: Note that the method of implementation of this option, + but not its intended effect, differ from some earlier versions of latexmk.) @@ -853,7 +853,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 13 + 31 January 2024 13 @@ -864,29 +864,29 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $lualatex. - Note: This option when provided with the COMMAND argument only - sets the command for invoking lualatex; it does not turn on the + Note: This option when provided with the COMMAND argument only + sets the command for invoking lualatex; it does not turn on the use of lualatex. That is done by other options or in an initial- ization file. - -M Show list of dependent files after processing. This is equiva- + -M Show list of dependent files after processing. This is equiva- lent to the -deps option. -MF file - If a list of dependents is made, the -MF specifies the file to + If a list of dependents is made, the -MF specifies the file to write it to. -MP If a list of dependents is made, include a phony target for each - source file. If you use the dependents list in a Makefile, the + source file. If you use the dependents list in a Makefile, the dummy rules work around errors the program make gives if you re- move header files without updating the Makefile to match. -makeindexfudge - Turn on the change-directory fudge for makeindex. See documen- + Turn on the change-directory fudge for makeindex. See documen- tation of $makeindex_fudge for details. @@ -902,24 +902,24 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -MSWinBackSlash This option only has an effect when latexmk is running under MS- Windows. This is that when latexmk runs a command under MS-Win- - dows, the Windows standard directory separator "\" is used to - separate directory components in a file name. Internally, la- - texmk uses "/" for the directory separator character, which is + dows, the Windows standard directory separator "\" is used to + separate directory components in a file name. Internally, la- + texmk uses "/" for the directory separator character, which is the character used by Unix-like systems. This is the default behavior. However the default may have been - overridden by a configuration file (latexmkrc file) which sets + overridden by a configuration file (latexmkrc file) which sets $MSWin_back_slash=0. -MSWinBackSlash- This option only has an effect when latexmk is running under MS- Windows. This is that when latexmk runs a command under MS-Win- - dows, the substitution of "\" for the separator character + dows, the substitution of "\" for the separator character - 10 January 2024 14 + 31 January 2024 14 @@ -938,18 +938,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -new-viewer - When in continuous-preview mode, always start a new viewer to - view the generated file. By default, latexmk will, in continu- - ous-preview mode, test for a previously running previewer for + When in continuous-preview mode, always start a new viewer to + view the generated file. By default, latexmk will, in continu- + ous-preview mode, test for a previously running previewer for the same file and not start a new one if a previous previewer is running. However, its test sometimes fails (notably if there is - an already-running previewer that is viewing a file of the same - name as the current file, but in a different directory). This + an already-running previewer that is viewing a file of the same + name as the current file, but in a different directory). This option turns off the default behavior. -new-viewer- - The inverse of the -new-viewer option. It puts latexmk in its + The inverse of the -new-viewer option. It puts latexmk in its normal behavior that in preview-continuous mode it checks for an already-running previewer. @@ -959,7 +959,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -nobibtexfudge or -nobibfudge - Turn off the change-directory fudge for bibtex. See documenta- + Turn off the change-directory fudge for bibtex. See documenta- tion of $bibtex_fudge for details. @@ -974,9 +974,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -norc Turn off the automatic reading of initialization (rc) files. - N.B. Normally the initialization files are read and obeyed, and - then command line options are obeyed in the order they are en- - countered. But -norc is an exception to this rule: it is acted + N.B. Normally the initialization files are read and obeyed, and + then command line options are obeyed in the order they are en- + countered. But -norc is an exception to this rule: it is acted on first, no matter where it occurs on the command line. @@ -985,7 +985,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 15 + 31 January 2024 15 @@ -997,48 +997,48 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Sets the directory for the output files of *latex. If the aux directory is not set or is the same as the output di- - rectory, then all output files of *latex are sent to the output + rectory, then all output files of *latex are sent to the output directory. If the aux directory is set, e.g., by the option -auxdir, and is - not equal to the output directory, then only final output files - (.dvi, .ps, .pdf, .synctex, .synctex.gz) are sent to the output + not equal to the output directory, then only final output files + (.dvi, .ps, .pdf, .synctex, .synctex.gz) are sent to the output directory. Other generated files are sent to the aux directory. - See the section AUXILIARY AND OUTPUT DIRECTORIES for more de- + See the section AUXILIARY AND OUTPUT DIRECTORIES for more de- tails. -output-format=FORMAT - This option is one that is allowed for latex, lualatex, and - pdflatex. But it is not passed to these programs. Instead la- - texmk emulates it in a way suitable for the context of latexmk + This option is one that is allowed for latex, lualatex, and + pdflatex. But it is not passed to these programs. Instead la- + texmk emulates it in a way suitable for the context of latexmk and its workflows. - If FORMAT is dvi, then dvi output is turned on, and postscript - and pdf output are turned off. This is equivalent to using the + If FORMAT is dvi, then dvi output is turned on, and postscript + and pdf output are turned off. This is equivalent to using the options -dvi -ps- -pdf-. - If FORMAT is pdf, then pdf output is turned on, and dvi and - postscript output are turned off. This is equivalent to using + If FORMAT is pdf, then pdf output is turned on, and dvi and + postscript output are turned off. This is equivalent to using the options -pdf -ps- -dvi-. If FORMAT is anything else, latexmk gives an error. - -p Print out the document. By default the file to be printed is - the first in the list postscript, pdf, dvi that is being made. + -p Print out the document. By default the file to be printed is + the first in the list postscript, pdf, dvi that is being made. But you can use the -print=... option to change the type of file to be printed, and you can configure this in a start up file (by setting the $print_type variable). - However, printing is enabled by default only under UNIX/Linux + However, printing is enabled by default only under UNIX/Linux systems, where the default is to use the lpr command and only on postscript files. In general, the correct behavior for printing very much depends on your system's software. In particular, un- - der MS-Windows you must have suitable program(s) available, and - you must have configured the print commands used by latexmk. - This can be non-trivial. See the documentation on the $lpr, + der MS-Windows you must have suitable program(s) available, and + you must have configured the print commands used by latexmk. + This can be non-trivial. See the documentation on the $lpr, $lpr_dvi, and $lpr_pdf configuration variables to see how to set the commands for printing. @@ -1046,12 +1046,12 @@ LATEXMK(1) General Commands Manual LATEXMK(1) turns them off. - -pdf Generate pdf version of document using pdflatex. (If you wish + -pdf Generate pdf version of document using pdflatex. (If you wish to use lualatex or xelatex, you can use whichever of the options - 10 January 2024 16 + 31 January 2024 16 @@ -1060,17 +1060,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - -pdflua, -pdfxe, -lualatex or -xelatex applies.) To configure - latexmk to have such behavior by default, see the section on + -pdflua, -pdfxe, -lualatex or -xelatex applies.) To configure + latexmk to have such behavior by default, see the section on "Configuration/initialization (rc) files". -pdfdvi - Generate dvi file and then pdf version of document from the dvi + Generate dvi file and then pdf version of document from the dvi file, by default using dvipdf. - The program used to compile the document to dvi is latex by de- - fault, but this can be changed to dvilulatex by the use of the + The program used to compile the document to dvi is latex by de- + fault, but this can be changed to dvilulatex by the use of the -dvilua option or by setting $dvi_mode to 2. @@ -1081,43 +1081,43 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -pdfps Generate dvi file, ps file from the dvi file, and then pdf file from the ps file. - The program used to compile the document to dvi is latex by de- - fault, but this can be changed to dvilulatex by the use of the + The program used to compile the document to dvi is latex by de- + fault, but this can be changed to dvilulatex by the use of the -dvilua option or by setting $dvi_mode to 2. - -pdfxe Generate pdf version of document using xelatex. Note that to - optimize processing time, latexmk uses xelatex to generate an - .xdv file rather than a pdf file directly. Only after possibly - multiple runs to generate a fully up-to-date .xdv file does la- + -pdfxe Generate pdf version of document using xelatex. Note that to + optimize processing time, latexmk uses xelatex to generate an + .xdv file rather than a pdf file directly. Only after possibly + multiple runs to generate a fully up-to-date .xdv file does la- texmk then call xdvipdfmx to generate the final .pdf file. - (Note: The reason why latexmk arranges for xelatex to make an - .xdv file instead of the xelatex's default of a .pdf file is as - follows: When the document includes large graphics files, espe- - cially .png files, the production of a .pdf file can be quite + (Note: The reason why latexmk arranges for xelatex to make an + .xdv file instead of the xelatex's default of a .pdf file is as + follows: When the document includes large graphics files, espe- + cially .png files, the production of a .pdf file can be quite time consuming, even when the creation of the .xdv file by xela- - tex is fast. So the use of the intermediate .xdv file can re- + tex is fast. So the use of the intermediate .xdv file can re- sult in substantial gains in procesing time, since the .pdf file is produced once rather than on every run of xelatex.) - -pdf- Turn off generation of pdf version of document. (This can be - used to override a setting in a configuration file. It may get + -pdf- Turn off generation of pdf version of document. (This can be + used to override a setting in a configuration file. It may get overridden if some other option requires the generation of a pdf file.) - If after all options have been processed, pdf generation is - still turned off, then generation of a dvi file will be turned + If after all options have been processed, pdf generation is + still turned off, then generation of a dvi file will be turned on, and then the program used to compiled a document will be la- - tex (or, more precisely, whatever program is configured to be + tex (or, more precisely, whatever program is configured to be used in the $latex configuration variable). - 10 January 2024 17 + 31 January 2024 17 @@ -1130,7 +1130,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) This sets the generation of pdf files by pdflatex, and turns off the generation of dvi and ps files. - Note: to set the command used when pdflatex is specified, see + Note: to set the command used when pdflatex is specified, see the -pdflatex="COMMAND" option. @@ -1142,19 +1142,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1) latexmk -pdf -pdflatex="pdflatex --shell-escape %O %S" foo.tex - The specification of the contents of the string are the same as + The specification of the contents of the string are the same as for the $pdflatex configuration variable. (The option -pdflatex in fact sets the variable $pdflatex.) Depending on your operat- - ing system and the command-line shell you are using, you may - need to change the single quotes to double quotes (or something + ing system and the command-line shell you are using, you may + need to change the single quotes to double quotes (or something else). - Note: This option when provided with the COMMAND argument only - sets the command for invoking pdflatex; it does not turn on the + Note: This option when provided with the COMMAND argument only + sets the command for invoking pdflatex; it does not turn on the use of pdflatex. That is done by other options or in an initial- ization file. - To set the command for running latex (rather than the command + To set the command for running latex (rather than the command for pdflatex) see the -latex option. @@ -1169,10 +1169,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -pretex=CODE Given that CODE is some TeX code, this options sets that code to - be executed before inputting source file. This only works if + be executed before inputting source file. This only works if the command for invoking the relevant *latex is suitably config- - ured. See the documentation of the variable $pre_tex_code, and - the substitution strings %P and %U for more details. This op- + ured. See the documentation of the variable $pre_tex_code, and + the substitution strings %P and %U for more details. This op- tion works by setting the variable $pre_tex_code. See also the -usepretex option. @@ -1183,7 +1183,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 18 + 31 January 2024 18 @@ -1204,12 +1204,12 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -print=dvi, -print=ps, -print=pdf, -print=auto, - Define which kind of file is printed. This option also ensures + Define which kind of file is printed. This option also ensures that the requisite file is made, and turns on printing. The (default) case -print=auto determines the kind of print file - automatically from the set of files that is being made. The - first in the list postscript, pdf, dvi that is among the files + automatically from the set of files that is being made. The + first in the list postscript, pdf, dvi that is among the files to be made is the one used for print out. @@ -1217,13 +1217,13 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -ps- Turn off generation of postscript version of document. This can - be used to override a setting in a configuration file. (It may - get overridden by some other option that requires a postscript + be used to override a setting in a configuration file. (It may + get overridden by some other option that requires a postscript file, for example a request for printing.) - -pF Postscript file filtering. The argument to this option is a - filter which will generate a filtered postscript file with the + -pF Postscript file filtering. The argument to this option is a + filter which will generate a filtered postscript file with the extension ".psF". All extra processing (e.g. preview, printing) will then be performed on this filtered postscript file. @@ -1236,20 +1236,20 @@ LATEXMK(1) General Commands Manual LATEXMK(1) latexmk -ps -pF "psnup -2" foo.tex Whether to use single or double quotes round the "psnup -2" will - depend on your command interpreter, as used by the particular + depend on your command interpreter, as used by the particular version of perl and the operating system on your computer. - -pv Run file previewer. If the -view option is used, that will se- + -pv Run file previewer. If the -view option is used, that will se- lect the kind of file to be previewed (.pdf, .ps or .dvi). Oth- - erwise the viewer views the "highest" kind of output file that - is made, with the ordering being .pdf, .ps, .dvi (high to low). - This option is incompatible with the -p and -pvc options, so it + erwise the viewer views the "highest" kind of output file that + is made, with the ordering being .pdf, .ps, .dvi (high to low). + This option is incompatible with the -p and -pvc options, so it turns them off. - 10 January 2024 19 + 31 January 2024 19 @@ -1261,43 +1261,43 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -pv- Turn off -pv. - -pvc Run a file previewer and continually update the .dvi, .ps, + -pvc Run a file previewer and continually update the .dvi, .ps, and/or .pdf files whenever changes are made to source files (see - the Description above). Which of these files is generated and - which is viewed is governed by the other options, and is the - same as for the -pv option. The preview-continuous option -pvc - can only work with one file. So in this case you will normally - only specify one filename on the command line. It is also in- - compatible with the -p and -pv options, so it turns these op- + the Description above). Which of these files is generated and + which is viewed is governed by the other options, and is the + same as for the -pv option. The preview-continuous option -pvc + can only work with one file. So in this case you will normally + only specify one filename on the command line. It is also in- + compatible with the -p and -pv options, so it turns these op- tions off. - The -pvc option also turns off force mode (-f), as is normally - best for continuous preview mode. If you really want force + The -pvc option also turns off force mode (-f), as is normally + best for continuous preview mode. If you really want force mode, use the options in the order -pvc -f. With a good previewer the display will be automatically updated. - (Under some but not all versions of UNIX/Linux "gv -watch" does - this for postscript files; this can be set by a configuration - variable. This would also work for pdf files except for an ap- + (Under some but not all versions of UNIX/Linux "gv -watch" does + this for postscript files; this can be set by a configuration + variable. This would also work for pdf files except for an ap- parent bug in gv that causes an error when the newly updated pdf file is read.) Many other previewers will need a manual update. Important note: the acroread program on MS-Windows locks the pdf - file, and prevents new versions being written, so it is a bad - idea to use acroread to view pdf files in preview-continuous - mode. It is better to use a different viewer: SumatraPDF and + file, and prevents new versions being written, so it is a bad + idea to use acroread to view pdf files in preview-continuous + mode. It is better to use a different viewer: SumatraPDF and gsview are good possibilities. - There are some other methods for arranging an update, notably - useful for many versions of xdvi and xpdf. These are best set + There are some other methods for arranging an update, notably + useful for many versions of xdvi and xpdf. These are best set in latexmk's configuration; see below. - Note that if latexmk dies or is stopped by the user, the + Note that if latexmk dies or is stopped by the user, the "forked" previewer will continue to run. Successive invocations - with the -pvc option will not fork new previewers, but latexmk - will normally use the existing previewer. (At least this will - happen when latexmk is running under an operating system where - it knows how to determine whether an existing previewer is run- + with the -pvc option will not fork new previewers, but latexmk + will normally use the existing previewer. (At least this will + happen when latexmk is running under an operating system where + it knows how to determine whether an existing previewer is run- ning.) @@ -1305,9 +1305,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -pvctimeout - Do timeout in pvc mode after period of inactivity, which is 30 + Do timeout in pvc mode after period of inactivity, which is 30 min. by default. Inactivity means a period when latexmk has de- - tected no file changes and hence has not taken any actions like + tected no file changes and hence has not taken any actions like compiling the document. @@ -1315,7 +1315,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 20 + 31 January 2024 20 @@ -1336,31 +1336,31 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -r - Read the specified initialization file ("RC file") before pro- + Read the specified initialization file ("RC file") before pro- cessing. Be careful about the ordering: (1) Standard initialization files - -- see the section below on "Configuration/initialization (RC) - files" -- are read first. (2) Then the options on the command - line are acted on in the order they are given. Therefore if an - initialization file is specified by the -r option, it is read - during this second step. Thus an initialization file specified + -- see the section below on "Configuration/initialization (RC) + files" -- are read first. (2) Then the options on the command + line are acted on in the order they are given. Therefore if an + initialization file is specified by the -r option, it is read + during this second step. Thus an initialization file specified with the -r option can override both the standard initialization files and previously specified options. But all of these can be overridden by later options. The contents of the RC file just comprise a piece of code in the - Perl programming language (typically a sequence of assignment + Perl programming language (typically a sequence of assignment statements); they are executed when the -r option is encountered during latexmk's parsing of its command line. See the -e option - for a way of giving initialization code directly on latexmk's - command line. An error results in latexmk stopping. Multiple + for a way of giving initialization code directly on latexmk's + command line. An error results in latexmk stopping. Multiple instances of the -r and -e options can be used, and they are ex- ecuted in the order they appear on the command line. -rc-report - After initialization, give a list of the RC files read. (De- + After initialization, give a list of the RC files read. (De- fault) @@ -1369,10 +1369,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -recorder - Give the -recorder option with *latex. In (most) modern ver- - sions of these programs, this results in a file of extension - .fls containing a list of the files that these programs have - read and written. Latexmk will then use this file to improve + Give the -recorder option with *latex. In (most) modern ver- + sions of these programs, this results in a file of extension + .fls containing a list of the files that these programs have + read and written. Latexmk will then use this file to improve its detection of source files and generated files after a run of *latex. This is the default setting of latexmk, unless overrid- den in an initialization file. @@ -1381,7 +1381,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 21 + 31 January 2024 21 @@ -1401,53 +1401,53 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -rules- - Do not show a list of latexmk's rules and dependencies after + Do not show a list of latexmk's rules and dependencies after processing. (This is the default.) -showextraoptions - Show the list of extra *latex options that latexmk recognizes, - but that it simply passes through to the programs *latex when - they are run. These options are (currently) a combination of - those allowed by the TeXLive and MiKTeX implementations. (If a - particular option is given to latexmk but is not handled by the - particular implementation of *latex that is being used, that - program will probably give a warning or an error.) These op- - tions are very numerous, but are not listed in this documenta- + Show the list of extra *latex options that latexmk recognizes, + but that it simply passes through to the programs *latex when + they are run. These options are (currently) a combination of + those allowed by the TeXLive and MiKTeX implementations. (If a + particular option is given to latexmk but is not handled by the + particular implementation of *latex that is being used, that + program will probably give a warning or an error.) These op- + tions are very numerous, but are not listed in this documenta- tion because they have no effect on latexmk's actions. - There are a few options (e.g., -includedirectory=dir, -initial- - ize, -ini) that are not recognized, either because they don't - fit with latexmk's intended operations, or because they need - special processing by latexmk that isn't implemented (at least, + There are a few options (e.g., -includedirectory=dir, -initial- + ize, -ini) that are not recognized, either because they don't + fit with latexmk's intended operations, or because they need + special processing by latexmk that isn't implemented (at least, not yet). - There are certain options for *latex (e.g., -recorder) that + There are certain options for *latex (e.g., -recorder) that trigger special actions or behavior by latexmk itself. Depending - on the action, they may also be passed in some form to the + on the action, they may also be passed in some form to the called *latex program, and/or may affect other programs as well. - These options do have entries in this documentation. Among + These options do have entries in this documentation. Among these options are: -jobname=STRING, -aux-directory=dir, -output- directory=DIR, -quiet, and -recorder. - There are also options that are accepted by *latex, but instead + There are also options that are accepted by *latex, but instead trigger actions purely by latexmk: -help, -version. -silent Run commands silently, i.e., with options that reduce the amount - of diagnostics generated. For example, with the default set- - tings, the command "latex -interaction=batchmode" is used for + of diagnostics generated. For example, with the default set- + tings, the command "latex -interaction=batchmode" is used for latex, and similarly for its friends. - See also the -logfilewarninglist and -logfilewarninglist- op- + See also the -logfilewarninglist and -logfilewarninglist- op- tions. - Also reduce the number of informational messages that latexmk + Also reduce the number of informational messages that latexmk - 10 January 2024 22 + 31 January 2024 22 @@ -1458,62 +1458,62 @@ LATEXMK(1) General Commands Manual LATEXMK(1) itself generates. - To change the options used to make the commands run silently, + To change the options used to make the commands run silently, you need to configure latexmk with changed values of its config- - uration variables, the relevant ones being $bib- - tex_silent_switch, $biber_silent_switch, $dvipdf_silent_switch, + uration variables, the relevant ones being $bib- + tex_silent_switch, $biber_silent_switch, $dvipdf_silent_switch, $dvips_silent_switch, $dvilualatex_silent_switch, $la- - tex_silent_switch, $lualatex_silent_switch $makein- - dex_silent_switch, $pdflatex_silent_switch, and $xela- + tex_silent_switch, $lualatex_silent_switch $makein- + dex_silent_switch, $pdflatex_silent_switch, and $xela- tex_silent_switch -stdtexcmds - Sets the commands for latex, etc, so that they are the standard + Sets the commands for latex, etc, so that they are the standard ones. This is useful to override special configurations. - The result is that $latex = 'latex %O %S', and similarly for - $pdflatex, $lualatex, and $xelatex. (The option -no-pdf needed + The result is that $latex = 'latex %O %S', and similarly for + $pdflatex, $lualatex, and $xelatex. (The option -no-pdf needed for $xelatex is provided automatically, given that %O appears in the definition.) -time Show time used. (On MS Windows, what is shown is clock time; on - other systems CPU time.) See also the configuration variable + other systems CPU time.) See also the configuration variable $show_time. - -time- Do not show time used. See also the configuration variable + -time- Do not show time used. See also the configuration variable $show_time. -use-make - When after a run of *latex, there are warnings about missing - files (e.g., as requested by the LaTeX \input, \include, and - \includgraphics commands), latexmk tries to make them by a cus- - tom dependency. If no relevant custom dependency with an appro- + When after a run of *latex, there are warnings about missing + files (e.g., as requested by the LaTeX \input, \include, and + \includgraphics commands), latexmk tries to make them by a cus- + tom dependency. If no relevant custom dependency with an appro- priate source file is found, and if the -use-make option is set, - then as a last resort latexmk will try to use the make program + then as a last resort latexmk will try to use the make program to try to make the missing files. - Note that the filename may be specified without an extension, - e.g., by \includegraphics{drawing} in a LaTeX file. In that - case, latexmk will try making drawing.ext with ext set in turn - to the possible extensions that are relevant for latex (or as + Note that the filename may be specified without an extension, + e.g., by \includegraphics{drawing} in a LaTeX file. In that + case, latexmk will try making drawing.ext with ext set in turn + to the possible extensions that are relevant for latex (or as appropriate pdflatex, lualatex, xelatex). - See also the documentation for the $use_make_for_missing_files + See also the documentation for the $use_make_for_missing_files configuration variable. -use-make- - Do not use the make program to try to make missing files. (De- + Do not use the make program to try to make missing files. (De- fault.) - 10 January 2024 23 + 31 January 2024 23 @@ -1524,13 +1524,13 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -usepretex Sets the command lines for latex, etc, so that they use the code - that is defined by the variable $pre_tex_code or that is set by + that is defined by the variable $pre_tex_code or that is set by the option -pretex=CODE to execute the specified TeX code before the source file is read. This option overrides any previous de- finition of the command lines. - The result is that $latex = 'latex %O %P', and similarly for - $pdflatex, $lualatex, and $xelatex. (The option -no-pdf needed + The result is that $latex = 'latex %O %P', and similarly for + $pdflatex, $lualatex, and $xelatex. (The option -no-pdf needed for $xelatex is provided automatically, given that %O appears in the definition.) @@ -1552,25 +1552,25 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -view=default, -view=dvi, -view=ps, -view=pdf, -view=none Set the kind of file used when previewing is requested (e.g., by the -pv or -pvc switches). The default is to view the "highest" - kind of requested file (in the low-to-high order .dvi, .ps, + kind of requested file (in the low-to-high order .dvi, .ps, .pdf). - Note the possibility -view=none where no viewer is opened at - all. One example of is use is in conjunction with the -pvc op- - tion, when you want latexmk to do a compilation automatically - whenever source file(s) change, but do not want a previewer to + Note the possibility -view=none where no viewer is opened at + all. One example of is use is in conjunction with the -pvc op- + tion, when you want latexmk to do a compilation automatically + whenever source file(s) change, but do not want a previewer to be opened. -Werror - This causes latexmk to return a non-zero status code if any of - the files processed gives a warning about problems with cita- - tions or references (i.e., undefined citations or references or - about multiply defined references). This is after latexmk has - completed all the runs it needs to try and resolve references - and citations. Thus -Werror causes latexmk to treat such warn- + This causes latexmk to return a non-zero status code if any of + the files processed gives a warning about problems with cita- + tions or references (i.e., undefined citations or references or + about multiply defined references). This is after latexmk has + completed all the runs it needs to try and resolve references + and citations. Thus -Werror causes latexmk to treat such warn- ings as errors, but only when they occur on the last run of *la- - tex and only after processing is complete. Also can be set by + tex and only after processing is complete. Also can be set by the configuration variable $warnings_as_errors. @@ -1579,7 +1579,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 24 + 31 January 2024 24 @@ -1590,51 +1590,51 @@ LATEXMK(1) General Commands Manual LATEXMK(1) -xelatex Use xelatex. That is, use xelatex to process the source file(s) - to pdf. The generation of dvi and postscript files is turned + to pdf. The generation of dvi and postscript files is turned off. This option is equivalent to using the following set of options -pdfxe -dvi- -ps- - [Note: Note that the method of implementation of this option, - but not its intended primary effect, differ from some earlier - versions of latexmk. Latexmk first uses xelatex to make an .xdv - file, and does all the extra runs needed (including those of - bibtex, etc). Only after that does it make the pdf file from - the .xdv file, using xdvipdfmx. See the documentation for the + [Note: Note that the method of implementation of this option, + but not its intended primary effect, differ from some earlier + versions of latexmk. Latexmk first uses xelatex to make an .xdv + file, and does all the extra runs needed (including those of + bibtex, etc). Only after that does it make the pdf file from + the .xdv file, using xdvipdfmx. See the documentation for the -pdfxe for why this is done.] -xelatex="COMMAND" - This sets the string specifying the command to run xelatex. It + This sets the string specifying the command to run xelatex. It sets the variable $xelatex. Warning: It is important to ensure that the -no-pdf is used when - xelatex is invoked, since latexmk expects xelatex to produce an - .xdv file, not a .pdf file. If you provide %O in the command - specification, this will be done automatically. See the docu- - mentation for the -pdfxe option for why latexmk makes a .xdv + xelatex is invoked, since latexmk expects xelatex to produce an + .xdv file, not a .pdf file. If you provide %O in the command + specification, this will be done automatically. See the docu- + mentation for the -pdfxe option for why latexmk makes a .xdv file rather than a .pdf file when xelatex is used. An example of the use of the -pdfxelatex option: - latexmk -pdfxe -pdfxelatex="xelatex --shell-escape %O %S" + latexmk -pdfxe -pdfxelatex="xelatex --shell-escape %O %S" foo.tex - Note: This option when provided with the COMMAND argument only - sets the command for invoking lualatex; it does not turn on the + Note: This option when provided with the COMMAND argument only + sets the command for invoking lualatex; it does not turn on the use of lualatex. That is done by other options or in an initial- ization file. Compatibility between options - The preview-continuous option -pvc can only work with one file. So in - this case you will normally only specify one filename on the command + The preview-continuous option -pvc can only work with one file. So in + this case you will normally only specify one filename on the command line. - Options -p, -pv and -pvc are mutually exclusive. So each of these op- + Options -p, -pv and -pvc are mutually exclusive. So each of these op- tions turns the others off. @@ -1645,7 +1645,7 @@ EXAMPLES - 10 January 2024 25 + 31 January 2024 25 @@ -1674,44 +1674,44 @@ LATEXMK(1) General Commands Manual LATEXMK(1) DEALING WITH ERRORS, PROBLEMS, ETC Some possibilities: - a. If you get a strange error, do look carefully at the output that is - on the screen and in log files. While there is much that is notori- + a. If you get a strange error, do look carefully at the output that is + on the screen and in log files. While there is much that is notori- ously verbose in the output of latex (and that is added to by latexmk), - the verbosity is there for a reason: to enable the user to diagnose - problems. Latexmk does repeat some messages at the end of a run that - it thinks would otherwise be easy to miss in the middle of other out- + the verbosity is there for a reason: to enable the user to diagnose + problems. Latexmk does repeat some messages at the end of a run that + it thinks would otherwise be easy to miss in the middle of other out- put. b. Generally, remember that latexmk does its work by running other pro- grams. Your first priority in dealing with errors should be to examine what went wrong with the individual programs. Then you need to correct - the causes of errors in the runs of these programs. (Often these come - from errors in the source document, but they could also be about miss- + the causes of errors in the runs of these programs. (Often these come + from errors in the source document, but they could also be about miss- ing LaTeX packages, etc.) c. If latexmk doesn't run the programs the way you would like, then you - need to look in this documentation at the list of command line options - and then at the sections on configuration/initialization files. A lot - of latexmk's behavior is configurable to deal with particular situa- + need to look in this documentation at the list of command line options + and then at the sections on configuration/initialization files. A lot + of latexmk's behavior is configurable to deal with particular situa- tions. (But there is a lot of reading!) - The remainder of these notes consists of ideas for dealing with more + The remainder of these notes consists of ideas for dealing with more difficult situations. - d. Further tricks can involve replacing the standard commands that la- + d. Further tricks can involve replacing the standard commands that la- texmk runs by other commands or scripts. - e. For possible examples of code for use in an RC file, see the direc- - tory example_rcfiles in the distribution of latexmk (e.g., at + e. For possible examples of code for use in an RC file, see the direc- + tory example_rcfiles in the distribution of latexmk (e.g., at http://mirror.ctan.org/support/latexmk/example_rcfiles). Even if these examples don't do what you want, they may provide suitable inspiration. - f. There's a useful trick that can be used when you use lualatex in- - stead of pdflatex (and in some related situations). The problem is + f. There's a useful trick that can be used when you use lualatex in- + stead of pdflatex (and in some related situations). The problem is - 10 January 2024 26 + 31 January 2024 26 @@ -1720,64 +1720,64 @@ DEALING WITH ERRORS, PROBLEMS, ETC LATEXMK(1) General Commands Manual LATEXMK(1) - that latexmk won't notice a dependency on a file, bar.baz say, that is - input by the lua code in your document instead of by the LaTeX part. - (Thus if you change bar.baz and rerun latexmk, then latexmk will think - no files have changed and not rerun lualatex, whereas if you had '\in- - put{bar.baz}' in the LaTeX part of the document, latexmk would notice - the change.) One solution is just to put the following somewhere in + that latexmk won't notice a dependency on a file, bar.baz say, that is + input by the lua code in your document instead of by the LaTeX part. + (Thus if you change bar.baz and rerun latexmk, then latexmk will think + no files have changed and not rerun lualatex, whereas if you had '\in- + put{bar.baz}' in the LaTeX part of the document, latexmk would notice + the change.) One solution is just to put the following somewhere in the LaTeX part of the document: \typeout{(bar.baz)} - This puts a line in the log file that latexmk will treat as implying - that the file bar.baz was read. (At present I don't know a way of do- - ing this automatically.) Of course, if the file has a different name, + This puts a line in the log file that latexmk will treat as implying + that the file bar.baz was read. (At present I don't know a way of do- + ing this automatically.) Of course, if the file has a different name, change bar.baz to the name of your file. g. See also the section "Advanced Configuration: Some extra resources". - h. Look on tex.stackexchange, i.e., at http://tex.stackex- - change.com/questions/tagged/latexmk Someone may have already solved + h. Look on tex.stackexchange, i.e., at http://tex.stackex- + change.com/questions/tagged/latexmk Someone may have already solved your problem. i. Ask a question at tex.stackexchange.com. - j. Or ask me (the author of latexmk). My e-mail is at the end of this + j. Or ask me (the author of latexmk). My e-mail is at the end of this documentation. AUXILIARY AND OUTPUT DIRECTORIES - Running *latex and the associated programs generate a number of files, - it is often convenient to arrange for the generated files to be in a - different directory than the source file(s) of a document. For our + Running *latex and the associated programs generate a number of files, + it is often convenient to arrange for the generated files to be in a + different directory than the source file(s) of a document. For our purposes here, we identify two classes of generated file. One class is what one may term the final output files, for example, the - .pdf file generated by running pdflatex, or the .dvi file from latex. + .pdf file generated by running pdflatex, or the .dvi file from latex. Also in this class is the ps file generated by applying dvips to a .dvi - file. There are also .synctec or .synctex.gz files that can be used by - programs that display .pdf files and the like to relate positions in + file. There are also .synctec or .synctex.gz files that can be used by + programs that display .pdf files and the like to relate positions in them to positions in source files. - The second class of file is composed of all other generated files: - These include notably .aux files that are used for implementing cross + The second class of file is composed of all other generated files: + These include notably .aux files that are used for implementing cross referencing, and are both generated on one run and read on a later run. - Many packages generate yet more such intermediate files, as well as - programs like bibtex, makeindex, etc. There are also .log files from + Many packages generate yet more such intermediate files, as well as + programs like bibtex, makeindex, etc. There are also .log files from *latex and corresponding files from other programs. - Let us use the term "output directory" for the directory that receives - the final output files, and "aux directory" for the directory for the - other generated files. If no special options are provided to the *la- - tex programs, these directories default to the current directory, and + Let us use the term "output directory" for the directory that receives + the final output files, and "aux directory" for the directory for the + other generated files. If no special options are provided to the *la- + tex programs, these directories default to the current directory, and then the generated files aren't segregated. If the two directories are - the same, as is the simplest situation, then all generated files are + the same, as is the simplest situation, then all generated files are - 10 January 2024 27 + 31 January 2024 27 @@ -1786,64 +1786,64 @@ AUXILIARY AND OUTPUT DIRECTORIES LATEXMK(1) General Commands Manual LATEXMK(1) - written to the same directory, and one often simply refers to the out- + written to the same directory, and one often simply refers to the out- put directory, without mentioning a separate aux directory. - Support for them is provided for them in the *latex programs: by the + Support for them is provided for them in the *latex programs: by the single option -output-directory for the TeXLive implementations, and by - the options -aux-directory and -output-directory for the MiKTeX imple- + the options -aux-directory and -output-directory for the MiKTeX imple- mentations. Special support like this is needed for two reasons: First - is that there are many packages that write files and it needs to be + is that there are many packages that write files and it needs to be arranged that these are automatically written to the appropriate direc- - tory without any rewriting of the packages' code. Second is that the - files are often read in again on subsequent runs of *latex, and it is + tory without any rewriting of the packages' code. Second is that the + files are often read in again on subsequent runs of *latex, and it is necessary that the program knows where to find the files. - A complication is that the TeXLive implementation does not allow for - separate aux and output directories. Latexmk deals with this by being - able to emulating a separate aux directory: In this method it invokes - *latex with just an -output-directory option, with the directory set - not to the desired output directory, but to the aux directory. After - running *latex, it moves the relevant final output file(s) to the in- - tended output directory. Emulation can be turned on by setting the - configuration variable $emulate_aux to one in a configuration file or + A complication is that the TeXLive implementation does not allow for + separate aux and output directories. Latexmk deals with this by being + able to emulating a separate aux directory: In this method it invokes + *latex with just an -output-directory option, with the directory set + not to the desired output directory, but to the aux directory. After + running *latex, it moves the relevant final output file(s) to the in- + tended output directory. Emulation can be turned on by setting the + configuration variable $emulate_aux to one in a configuration file or by using latexmk's -emulate-aux-dir option. The emulation method works equally well if MiKTeX is used. - Latexmk also turns emulation on if it is found to be needed, as fol- - lows. Suppose emulation is initially off, but the aux and output di- - rectories are different. Then latexmk invokes *latex with an -aux-di- - rectory option and after the run finds that it hasn't been obeyed, no- - tably because the .log file is in the output directory rather than the - aux directory. Latexmk then sets emulation on, and retries. Conceiv- + Latexmk also turns emulation on if it is found to be needed, as fol- + lows. Suppose emulation is initially off, but the aux and output di- + rectories are different. Then latexmk invokes *latex with an -aux-di- + rectory option and after the run finds that it hasn't been obeyed, no- + tably because the .log file is in the output directory rather than the + aux directory. Latexmk then sets emulation on, and retries. Conceiv- ably, it could move all the appropriate generated files from the output - directory to the aux directory; but there is such a large variety of + directory to the aux directory; but there is such a large variety of possibilities for these files that this is hard to identify all of them reliably except for simple cases. - Note that the emulation issue only arises when the user has arranged - for the the aux and output directories to be different. When instead - they are equal, e.g., because the user only set the $out_dir variable, - then latexmk invokes *latex with only an -output-directory option, + Note that the emulation issue only arises when the user has arranged + for the the aux and output directories to be different. When instead + they are equal, e.g., because the user only set the $out_dir variable, + then latexmk invokes *latex with only an -output-directory option, which works as intended with both TeXLive and MiKTeX. In addition, latexmk arranges the invocations of any auxiliary programs like bibtex and makeindex so that they will read and write the relevant - files from and to the aux directory. Programs like dvips, dvipdf, - ps2pdf, and xdvipdfmx are invoked so that they read from the appropri- + files from and to the aux directory. Programs like dvips, dvipdf, + ps2pdf, and xdvipdfmx are invoked so that they read from the appropri- ate places and write their output to the output directory. - Files considered as final output files, i.e., those that belong in the - output directory rather than the aux directory: These have the exten- + Files considered as final output files, i.e., those that belong in the + output directory rather than the aux directory: These have the exten- sions .dvi, .ps., .pdf, .synctex, and .synctex.gz. A special case, be- cause of compatibility issues, is of .fls files: See below. - Note that xelatex when invoked with its -no-pdf option, as latexmk - does, generates an .xdv file, which would appear to have the same + Note that xelatex when invoked with its -no-pdf option, as latexmk + does, generates an .xdv file, which would appear to have the same - 10 January 2024 28 + 31 January 2024 28 @@ -1853,36 +1853,36 @@ LATEXMK(1) General Commands Manual LATEXMK(1) status as a .dvi file generated by latex. Nevertheless, latexmk treats - .xdv as an intermediate file that is found in the aux directory. This - is to match MiKTeX's treatment of the -aux-directory option. As fur- - ther justification, one can say that under modern conditions an .xdv + .xdv as an intermediate file that is found in the aux directory. This + is to match MiKTeX's treatment of the -aux-directory option. As fur- + ther justification, one can say that under modern conditions an .xdv file is (almost) always an intermediate file. Historically, the situa- - tion with .dvi files from latex was different, and currently dvi pre- + tion with .dvi files from latex was different, and currently dvi pre- viewers do exist. - Variables and options for directories: The variables for setting the - aux and output directories are $aux_dir and $out_dir, with correspond- - ing command line options -auxdir (or -aux-directory) and -outdir (or - -output-directory). When a value for these is blank (which is the de- - fault value), it implies the use of a default: For the aux directory, + Variables and options for directories: The variables for setting the + aux and output directories are $aux_dir and $out_dir, with correspond- + ing command line options -auxdir (or -aux-directory) and -outdir (or + -output-directory). When a value for these is blank (which is the de- + fault value), it implies the use of a default: For the aux directory, the default is to set it equal to the output directory. For the output directory, the default is to be the current directory. For the turning on and off of the emulation mode, there is the configu- - ration variable $emulate_aux and the options -emulate-aux-dir, -emu- + ration variable $emulate_aux and the options -emulate-aux-dir, -emu- late-aux-dir-, -noemulate-aux-dir. Interaction with -cd option: When the -cd option is used (or the equiv- alent setting of $do_cd variable), then latexmk changes the working di- - rectory to the document directory before invoking *latex. If the aux - and/or output directories are given by relative paths, e.g., by -out- - dir=output for a directory named "output", then the directories are + rectory to the document directory before invoking *latex. If the aux + and/or output directories are given by relative paths, e.g., by -out- + dir=output for a directory named "output", then the directories are relative to the document directory, rather than relative to the working directory that was in effect when latexmk was invoked. This matches the - behavior of *latex as invoked with the provided command line directory - argument(s) after the change of working directory to the document di- + behavior of *latex as invoked with the provided command line directory + argument(s) after the change of working directory to the document di- rectory. Automatic creation of aux and output directories: Unlike *latex, if la- @@ -1891,25 +1891,25 @@ LATEXMK(1) General Commands Manual LATEXMK(1) If the document uses the \include macro to read a .tex file from a sub- directory, *latex will attempt to write an extra aux file to the corre- - sponding subdirectory of the aux directory. If the subdirectory - doesn't exist, then *latex will complain that it can't write the aux + sponding subdirectory of the aux directory. If the subdirectory + doesn't exist, then *latex will complain that it can't write the aux file. After the run of *latex, latexmk detects this situation, creates - the necessary directory, and reruns *latex with the error situation + the necessary directory, and reruns *latex with the error situation corrected. Choice of aux and output directories: Often the aux and output directo- - ries are given as subdirectories of the document directory, e.g., by + ries are given as subdirectories of the document directory, e.g., by -outdir=output. But it is possible to provide, for example, an absolute - path or a path relative to a parent directory, e.g., "/tmp/foo" or + path or a path relative to a parent directory, e.g., "/tmp/foo" or "../output". Be aware that in general this can cause problems, notably - with makeindex or bibtex. This is because modern versions of these - programs, by default, will refuse to work when they find that they are + with makeindex or bibtex. This is because modern versions of these + programs, by default, will refuse to work when they find that they are asked to write to a file in a directory that appears not to be the cur- - rent working directory or one of its subdirectories. This is part of + rent working directory or one of its subdirectories. This is part of - 10 January 2024 29 + 31 January 2024 29 @@ -1921,61 +1921,61 @@ LATEXMK(1) General Commands Manual LATEXMK(1) security measures by the whole TeX system that try to prevent malicious or errant TeX documents from incorrectly messing with a user's files. - By default, latexmk evades this issue: Before running bibtex and + By default, latexmk evades this issue: Before running bibtex and makeindex, latexmk changes working directory to the aux directory, with appropriate settings of search paths. The use or non-use of this trick - is governed by the variables $bibtex_fudge and $makeindex_fudge. Un- - fortunately, the trick sometimes makes bibtex and makeindex unable to + is governed by the variables $bibtex_fudge and $makeindex_fudge. Un- + fortunately, the trick sometimes makes bibtex and makeindex unable to find files. If necessary the trick can be turned off. But this is incompatible with - an aux directory like, "/tmp/foo" of "../output"). If you really have + an aux directory like, "/tmp/foo" of "../output"). If you really have to deal with this situation, and only if you have to deal with it, then - you need to disable the security measures (and assume any risks). One + you need to disable the security measures (and assume any risks). One way of doing this is to temporarily set an operating system environment - variable openout_any to "a" (as in "all"), to override the default + variable openout_any to "a" (as in "all"), to override the default "paranoid" setting. - Certain names of aux and output directories not allowed on Microsoft + Certain names of aux and output directories not allowed on Microsoft Windows: It is natural to want to use the name "aux" for the aux direc- - tory, e.g., by using the option -auxdir=aux. But on Microsoft operat- + tory, e.g., by using the option -auxdir=aux. But on Microsoft operat- ing systems "aux" is one of the names that is not allowed for a file or - directory. I find it useful to standardize on a name like "auxdir" - (e.g., by -auxdir=auxdir); this works independently of operating sys- + directory. I find it useful to standardize on a name like "auxdir" + (e.g., by -auxdir=auxdir); this works independently of operating sys- tem. - Location of .fls file: Much of the dependency information that latexmk + Location of .fls file: Much of the dependency information that latexmk uses comes from the .fls file generated when *latex is invoked with the - -recorder option, which latexmk does by default. It may seem rational - that this is written to the aux directory. But in fact versions of + -recorder option, which latexmk does by default. It may seem rational + that this is written to the aux directory. But in fact versions of MiKTeX prior to Oct. 2020 wrote it to the output directory. Later ver- - sions do write it to the aux directory. To deal with this, latexmk - does two things: First, if latexmk finds that the .fls file has only - been generated in the "wrong" directory, then latexmk copies it to the + sions do write it to the aux directory. To deal with this, latexmk + does two things: First, if latexmk finds that the .fls file has only + been generated in the "wrong" directory, then latexmk copies it to the expected directory, after which latexmk's operation continues correctly - independently of the behavior of *latex. Second it allows its idea of - the "correct" (or expected) directory to be configured by the variable - $fls_uses_aux_dir. This defaults to zero, to correspond to MiKTeX's + independently of the behavior of *latex. Second it allows its idea of + the "correct" (or expected) directory to be configured by the variable + $fls_uses_aux_dir. This defaults to zero, to correspond to MiKTeX's current behavior. ALLOWING FOR CHANGE OF OUTPUT FILE TYPE When one of the latex engines is run, the usual situation is that latex - produces a .dvi file, while pdflatex and lualatex produce a .pdf file. + produces a .dvi file, while pdflatex and lualatex produce a .pdf file. For xelatex the default is to produce a .pdf file, but to optimize pro- - cessing time latexmk runs xelatex its -no-pdf option so that it pro- - duces an .xdv file. Further processing by latexmk takes this as a + cessing time latexmk runs xelatex its -no-pdf option so that it pro- + duces an .xdv file. Further processing by latexmk takes this as a starting point. However, the actual output file may differ from the normal expectation; - and then latexmk can adjust its processing to accommodate this situa- - tion. The difference in output file type can happen for two reasons: - One is that for latex, pdflatex and lualatex the document itself can + and then latexmk can adjust its processing to accommodate this situa- + tion. The difference in output file type can happen for two reasons: + One is that for latex, pdflatex and lualatex the document itself can - 10 January 2024 30 + 31 January 2024 30 @@ -1984,64 +1984,64 @@ ALLOWING FOR CHANGE OF OUTPUT FILE TYPE LATEXMK(1) General Commands Manual LATEXMK(1) - override the defaults. The other is that there may be a configuration, + override the defaults. The other is that there may be a configuration, or misconfiguration, such that the program that latexmk invokes to com- - pile the document is not the expected one, or is given options incom- + pile the document is not the expected one, or is given options incom- patible with what latexmk initially expects. - Under latex and pdflatex, control of the output format by the document - is done by setting the \pdfoutput macro. Under lualatex, the \output- + Under latex and pdflatex, control of the output format by the document + is done by setting the \pdfoutput macro. Under lualatex, the \output- mode macro is used instead. One example of an important use-case for document control of the output - format is a document that uses the psfrag package to insert graphical + format is a document that uses the psfrag package to insert graphical elements in the output file. The psfrag package achieves its effects by inserting postscript code in the output of the compilation of the docu- - ment. This entails the use of compilation to a .dvi file, followed by - the use of conversion to a postscript file (either directly, as by - dvips or implicitly, as an intermediate step by dvipdf). Then it is - useful to force output to be of the .dvi format by inserting \pdfout- + ment. This entails the use of compilation to a .dvi file, followed by + the use of conversion to a postscript file (either directly, as by + dvips or implicitly, as an intermediate step by dvipdf). Then it is + useful to force output to be of the .dvi format by inserting \pdfout- put=0 in the preamble of the document. - Another example is where the document uses graphics file of the .pdf, - .jpg, and png types. With the default setting for the graphicx pack- - age, these can be processed in compilation to .pdf but not with compi- - lation to .dvi. In this case, it is useful to insert \pdfoutput=1 in - the preamble of the document to force compilation to .pdf output for- + Another example is where the document uses graphics file of the .pdf, + .jpg, and png types. With the default setting for the graphicx pack- + age, these can be processed in compilation to .pdf but not with compi- + lation to .dvi. In this case, it is useful to insert \pdfoutput=1 in + the preamble of the document to force compilation to .pdf output for- mat. In all of these cases, it is needed that latexmk has to adjust its pro- - cessing to deal with a mismatch between the actual output format (out - of .pdf, .dvi, .xdv) and the initially expected output, if possible. + cessing to deal with a mismatch between the actual output format (out + of .pdf, .dvi, .xdv) and the initially expected output, if possible. Latexmk does this provided the following conditions are met. The first is that latexmk's $allow_switch configuration variable is set - to a non-zero value as it is by default. If this variable is zero, a + to a non-zero value as it is by default. If this variable is zero, a mismatch of filetypes in the compilation results in an error. - The second condition for latexmk to be able to handle a change of out- - put type is that no explicit requests for .dvi or .ps output files are - made. Explicit requests are by the -dvi and -ps, -print=dvi, - -print=ps, -view=dvi, and -view=ps options, and by corresponding set- - tings of the $dvi_mode, $postscript_mode, $print_type, and $view con- - figuration variables. The print-type and view-type restrictions only + The second condition for latexmk to be able to handle a change of out- + put type is that no explicit requests for .dvi or .ps output files are + made. Explicit requests are by the -dvi and -ps, -print=dvi, + -print=ps, -view=dvi, and -view=ps options, and by corresponding set- + tings of the $dvi_mode, $postscript_mode, $print_type, and $view con- + figuration variables. The print-type and view-type restrictions only apply when printing and viewing are explicitly requested, respectively. - For this purpose, the use of the -pdfdvi and -pdfps options (and the - corresponding setting of the $pdf_mode variable) does not count as an - explicit request for the .dvi and .ps files; they are merely regarded - as a request for making a .pdf file together with an initial proposal + For this purpose, the use of the -pdfdvi and -pdfps options (and the + corresponding setting of the $pdf_mode variable) does not count as an + explicit request for the .dvi and .ps files; they are merely regarded + as a request for making a .pdf file together with an initial proposal for the processing route to make it. Note that when accommodating a change in output file type, there is in- - volved a substantial change in the network of rules that latexmk uses - in its actions. The second condition applied to accommodate a change + volved a substantial change in the network of rules that latexmk uses + in its actions. The second condition applied to accommodate a change is to avoid situations where the change in the rule network is too rad- ical to be readily handled automatically. - 10 January 2024 31 + 31 January 2024 31 @@ -2051,11 +2051,11 @@ LATEXMK(1) General Commands Manual LATEXMK(1) CONFIGURATION/INITIALIZATION (RC) FILES - In this section is explained which configuration files are read by la- - texmk. Subsequent sections "How to Set Variables in Initialization - Files", "Format of Command Specifications", "List of Configuration - Variables Usable in Initialization Files", "Custom Dependencies", and - "Advanced Configuration" give details on what can be configured and + In this section is explained which configuration files are read by la- + texmk. Subsequent sections "How to Set Variables in Initialization + Files", "Format of Command Specifications", "List of Configuration + Variables Usable in Initialization Files", "Custom Dependencies", and + "Advanced Configuration" give details on what can be configured and how. Latexmk can be customized using initialization files, which are read at @@ -2063,7 +2063,7 @@ CONFIGURATION/INITIALIZATION (RC) FILES 1) The system RC file, if it exists. On a UNIX system, latexmk searches the following directories for a - system RC file, which may be named either "LatexMk" or "latexmkrc". + system RC file, which may be named either "LatexMk" or "latexmkrc". The directories are searched in the following order, and latexmk uses the first such file it finds (if any): @@ -2072,7 +2072,7 @@ CONFIGURATION/INITIALIZATION (RC) FILES "/usr/local/share/latexmk", "/usr/local/lib/latexmk". On a MS-Windows system it looks just in "C:\latexmk". - On a cygwin system (i.e., a MS-Windows system in which Perl is that + On a cygwin system (i.e., a MS-Windows system in which Perl is that of cygwin), latexmk looks in the directories "/cygdrive/c/latexmk", "/etc", @@ -2080,34 +2080,34 @@ CONFIGURATION/INITIALIZATION (RC) FILES "/usr/local/share/latexmk", "/usr/local/lib/latexmk". - If the environment variable LATEXMKRCSYS is set, its value is used as + If the environment variable LATEXMKRCSYS is set, its value is used as the name of the system RC file, instead of any of the above. 2) The user's RC file, if it exists. This can be in one of two places. - The traditional one is ".latexmkrc" in the user's home directory. The - other possibility is "latexmk/latexmkrc" in the user's XDG configura- - tion home directory. The actual file read is the first of "$XDG_CON- - FIG_HOME/latexmk/latexmkrc" or "$HOME/.latexmkrc" which exists. (See + The traditional one is ".latexmkrc" in the user's home directory. The + other possibility is "latexmk/latexmkrc" in the user's XDG configura- + tion home directory. The actual file read is the first of "$XDG_CON- + FIG_HOME/latexmk/latexmkrc" or "$HOME/.latexmkrc" which exists. (See https://specifications.freedesktop.org/basedir-spec/basedir-spec-lat- est.html for details on the XDG Base Directory Specification.) - Here $HOME is the user's home directory. [Latexmk determines the - user's home directory as follows: It is the value of the environment - variable HOME, if this variable exists, which normally is the case on - UNIX-like systems (including Linux and OS-X). Otherwise the environ- - ment variable USERPROFILE is used, if it exists, which normally is the + Here $HOME is the user's home directory. [Latexmk determines the + user's home directory as follows: It is the value of the environment + variable HOME, if this variable exists, which normally is the case on + UNIX-like systems (including Linux and OS-X). Otherwise the environ- + ment variable USERPROFILE is used, if it exists, which normally is the case on MS-Windows systems. Otherwise a blank string is used instead of $HOME, in which case latexmk does not look for an RC file in it.] - $XDG_CONFIG_HOME is the value of the environment variable XDG_CON- - FIG_HOME if it exists. If this environment variable does not exist, - but $HOME is non-blank, then $XDG_CONFIG_HOME is set to the default - value of $HOME/.config. Otherwise $XDG_CONFIG_HOME is blank, and la- + $XDG_CONFIG_HOME is the value of the environment variable XDG_CON- + FIG_HOME if it exists. If this environment variable does not exist, + but $HOME is non-blank, then $XDG_CONFIG_HOME is set to the default + value of $HOME/.config. Otherwise $XDG_CONFIG_HOME is blank, and la- texmk does not look for an RC file under it. - 10 January 2024 32 + 31 January 2024 32 @@ -2116,35 +2116,35 @@ CONFIGURATION/INITIALIZATION (RC) FILES LATEXMK(1) General Commands Manual LATEXMK(1) - 3) The RC file in the current working directory. This file can be - named either "latexmkrc" or ".latexmkrc", and the first of these to be + 3) The RC file in the current working directory. This file can be + named either "latexmkrc" or ".latexmkrc", and the first of these to be found is used, if any. 4) Any RC file(s) specified on the command line with the -r option. Each RC file is a sequence of Perl commands. Naturally, a user can use - this in creative ways. But for most purposes, one simply uses a se- + this in creative ways. But for most purposes, one simply uses a se- quence of assignment statements that override some of the built-in set- - tings of Latexmk. Straightforward cases can be handled without knowl- - edge of the Perl language by using the examples in this document as + tings of Latexmk. Straightforward cases can be handled without knowl- + edge of the Perl language by using the examples in this document as templates. Comment lines are introduced by the "#" character. - Note that command line options are obeyed in the order in which they + Note that command line options are obeyed in the order in which they are written; thus any RC file specified on the command line with the -r - option can override previous options but can be itself overridden by - later options on the command line. There is also the -e option, which + option can override previous options but can be itself overridden by + later options on the command line. There is also the -e option, which allows initialization code to be specified in latexmk's command line. For possible examples of code for in an RC file, see the directory ex- - ample_rcfiles in the distribution of latexmk (e.g., at http://mir- + ample_rcfiles in the distribution of latexmk (e.g., at http://mir- ror.ctan.org/support/latexmk/example_rcfiles). HOW TO SET VARIABLES IN INITIALIZATION FILES - The important variables that can be configured are described in the - section "List of configuration variables usable in initialization - files". (See the earlier section "Configuration/Initialization (rc) - Files" for the files where the configurations are done.) Syntax for + The important variables that can be configured are described in the + section "List of configuration variables usable in initialization + files". (See the earlier section "Configuration/Initialization (rc) + Files" for the files where the configurations are done.) Syntax for setting these variables is of the following forms: $bibtex = 'bibtex %O %S'; @@ -2157,23 +2157,23 @@ HOW TO SET VARIABLES IN INITIALIZATION FILES @default_files = ('paper', 'paper1'); - for the setting of an array of strings. It is possible to append an + for the setting of an array of strings. It is possible to append an item to an array variable as follows: push @default_files, 'paper2'; - Note that simple "scalar" variables have names that begin with a $ + Note that simple "scalar" variables have names that begin with a $ character and array variables have names that begin with a @ character. Each statement ends with a semicolon. - Strings should be enclosed in single quotes. (You could use double - quotes, as in many programming languages. But then the Perl program- - ming language brings into play some special rules for interpolating - variables into strings. People not fluent in Perl will want to avoid + Strings should be enclosed in single quotes. (You could use double + quotes, as in many programming languages. But then the Perl program- + ming language brings into play some special rules for interpolating + variables into strings. People not fluent in Perl will want to avoid - 10 January 2024 33 + 31 January 2024 33 @@ -2184,33 +2184,33 @@ LATEXMK(1) General Commands Manual LATEXMK(1) these complications.) - You can do much more complicated things, but for this you will need to + You can do much more complicated things, but for this you will need to consult a manual for the Perl programming language. FORMAT OF COMMAND SPECIFICATIONS - Some of the variables set the commands that latexmk uses for carrying - out its work, for example to generate a .dvi file from a .tex file or - to view a postscript file. This section describes some important fea- + Some of the variables set the commands that latexmk uses for carrying + out its work, for example to generate a .dvi file from a .tex file or + to view a postscript file. This section describes some important fea- tures of how the commands are specified. (Note that some of the possi- - bilities listed here do not apply to the $kpsewhich variable; see its + bilities listed here do not apply to the $kpsewhich variable; see its documentation.) Placeholders: Supposed you wanted latexmk to use the command elatex in - place of the regular latex command, and suppose moreover that you - wanted to give it the option "--shell-escape". You could do this by + place of the regular latex command, and suppose moreover that you + wanted to give it the option "--shell-escape". You could do this by the following setting: $latex = 'elatex --shell-escape %O %S'; - The two items starting with the % character are placeholders. These - are substituted by appropriate values before the command is run. Thus - %S will be replaced by the source file that elatex will be applied to, - and %O will be replaced by any options that latexmk has decided to use + The two items starting with the % character are placeholders. These + are substituted by appropriate values before the command is run. Thus + %S will be replaced by the source file that elatex will be applied to, + and %O will be replaced by any options that latexmk has decided to use for this command. (E.g., if you used the -silent option in the invoca- - tion of latexmk, it results in the replacement of %O by "-interac- + tion of latexmk, it results in the replacement of %O by "-interac- tion=batchmode".) The available placeholders are: @@ -2219,27 +2219,27 @@ FORMAT OF COMMAND SPECIFICATIONS the setting of a jobname by the -jobname option or the $jobname configuration value. - %B base of filename for current command. E.g., if a postscript - file document.ps is being made from the dvi file document.dvi, + %B base of filename for current command. E.g., if a postscript + file document.ps is being made from the dvi file document.dvi, then the basename is document. - %D destination file (e.g., the name of the postscript file when + %D destination file (e.g., the name of the postscript file when converting a dvi file to postscript). %O options - %P If the variable $pre_tex_code is non-empty, then %P is substi- - tuted by the contents of $pre_tex_code followed by \in- - put{SOURCE}, where SOURCE stands for the name of the source + %P If the variable $pre_tex_code is non-empty, then %P is substi- + tuted by the contents of $pre_tex_code followed by \in- + put{SOURCE}, where SOURCE stands for the name of the source file. Appropriate quoting is done. This enables TeX code to be - passed to one of the *latex engines to be executed before the + passed to one of the *latex engines to be executed before the source file is read. - If the variable $pre_tex_code is the empty string, then %P is + If the variable $pre_tex_code is the empty string, then %P is - 10 January 2024 34 + 31 January 2024 34 @@ -2252,60 +2252,60 @@ LATEXMK(1) General Commands Manual LATEXMK(1) %R root filename. This is the base name for the main tex file. - By default this is the basename of the main tex file. However - the value can be changed by the use of the -jobname option or + By default this is the basename of the main tex file. However + the value can be changed by the use of the -jobname option or the $jobname configuration variable. - %S source file (e.g., the name of the dvi file when converting a + %S source file (e.g., the name of the dvi file when converting a .dvi file to ps). %T The name of the primary tex file. - %U If the variable $pre_tex_code is non-empty, then its value is - substituted for %U (appropriately quoted). Otherwise it is re- + %U If the variable $pre_tex_code is non-empty, then its value is + substituted for %U (appropriately quoted). Otherwise it is re- placed by a null string. %Y Name of directory for auxiliary output files (see the configura- tion variable $aux_dir). A directory separation character ('/') is appended if $aux_dir is non-empty and does not end in a suit- able character, with suitable characters being those appropriate - to UNIX and MS-Windows, i.e., ':', '/' and '\'. Note that if - after initialization, $out_dir is set, but $aux_dir is not set - (i.e., it is blank), then latexmk sets $aux_dir to the same + to UNIX and MS-Windows, i.e., ':', '/' and '\'. Note that if + after initialization, $out_dir is set, but $aux_dir is not set + (i.e., it is blank), then latexmk sets $aux_dir to the same value $out_dir. - %Z Name of directory for output files (see the configuration vari- - able $out_dir). A directory separation character ('/') is ap- - pended if $out_dir is non-empty and does not end in a suitable - character, with suitable characters being those appropriate to + %Z Name of directory for output files (see the configuration vari- + able $out_dir). A directory separation character ('/') is ap- + pended if $out_dir is non-empty and does not end in a suitable + character, with suitable characters being those appropriate to UNIX and MS-Windows, i.e., ':', '/' and '\'. - If for some reason you need a literal % character in your string not + If for some reason you need a literal % character in your string not subject to the above rules, use "%%". - Appropriate quoting will be applied to the filename substitutions, so - you mustn't supply them yourself even if the names of your files have + Appropriate quoting will be applied to the filename substitutions, so + you mustn't supply them yourself even if the names of your files have spaces in them. (But if your TeX filenames have spaces in them, beware - that some older versions of the TeX program cannot correctly handle - filenames containing spaces.) In case latexmk's quoting does not work - correctly on your system, you can turn it off -- see the documentation + that some older versions of the TeX program cannot correctly handle + filenames containing spaces.) In case latexmk's quoting does not work + correctly on your system, you can turn it off -- see the documentation for the variable $quote_filenames. - See the default values in the section "List of configuration variables + See the default values in the section "List of configuration variables usable in initialization files" for what is normally the most appropri- ate usage. If you omit to supply any placeholders whatever in the specification of - a command, latexmk will supply what its author thinks are appropriate + a command, latexmk will supply what its author thinks are appropriate defaults. This gives compatibility with configuration files for previ- ous versions of latexmk, which didn't use placeholders. - "Detaching" a command: Normally when latexmk runs a command, it waits + "Detaching" a command: Normally when latexmk runs a command, it waits for the command to run to completion. This is appropriate for commands - 10 January 2024 35 + 31 January 2024 35 @@ -2315,24 +2315,24 @@ LATEXMK(1) General Commands Manual LATEXMK(1) like latex, of course. But for previewers, the command should normally - run detached, so that latexmk gets the previewer running and then re- - turns to its next task (or exits if there is nothing else to do). To - achieve this effect of detaching a command, you need to precede the + run detached, so that latexmk gets the previewer running and then re- + turns to its next task (or exits if there is nothing else to do). To + achieve this effect of detaching a command, you need to precede the command name with "start ", as in $dvi_previewer = 'start xdvi %O %S'; - This will be translated to whatever is appropriate for your operating + This will be translated to whatever is appropriate for your operating system. Notes: (1) In some circumstances, latexmk will always run a command de- - tached. This is the case for a previewer in preview continuous mode, - since otherwise previewing continuously makes no sense. (2) This pre- - cludes the possibility of running a command named start. (3) If the - word start occurs more than once at the beginning of the command - string, that is equivalent to having just one. (4) Under cygwin, some - complications happen, since cygwin amounts to a complicated merging of - UNIX and MS-Windows. See the source code for how I've handled the + tached. This is the case for a previewer in preview continuous mode, + since otherwise previewing continuously makes no sense. (2) This pre- + cludes the possibility of running a command named start. (3) If the + word start occurs more than once at the beginning of the command + string, that is equivalent to having just one. (4) Under cygwin, some + complications happen, since cygwin amounts to a complicated merging of + UNIX and MS-Windows. See the source code for how I've handled the problem. Command names containing spaces: Under MS-Windows it is common that the @@ -2344,26 +2344,26 @@ LATEXMK(1) General Commands Manual LATEXMK(1) %S'; $pdf_previewer = 'start "c:/Program Files/SumatraPDF/Suma- traPDF.exe" %O %S'; - $pdf_previewer = 'start "c:/Program Files/SumatraPDF (x86)/Suma- + $pdf_previewer = 'start "c:/Program Files/SumatraPDF (x86)/Suma- traPDF.exe" %O %S'; - (Note about the above example: Under MS-Windows forward slashes are + (Note about the above example: Under MS-Windows forward slashes are equivalent to backslashes in a filename under almost all circumstances, - provided that the filename is inside double quotes. It is easier to + provided that the filename is inside double quotes. It is easier to use forward slashes in examples like the one above, since then one does - not have to worry about the rules for dealing with forward slashes in + not have to worry about the rules for dealing with forward slashes in strings in the Perl language.) - Command names under Cygwin: If latexmk is executed by Cygwin's Perl, + Command names under Cygwin: If latexmk is executed by Cygwin's Perl, be particularly certain that pathnames in commands have forward slashes - not the usual backslashes for the separator of pathname components. - See the above examples. Backslashes often get misinterpreted by the + not the usual backslashes for the separator of pathname components. + See the above examples. Backslashes often get misinterpreted by the Unix shell used by Cygwin's Perl to execute external commands. Forward slashes don't suffer from this problem, and (when quoted, as above) are equally acceptable to MS-Windows. - Using MS-Windows file associations: A useful trick under modern ver- + Using MS-Windows file associations: A useful trick under modern ver- sions of MS-Windows (e.g., WinXP) is to use just the command 'start' by itself: @@ -2371,7 +2371,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 36 + 31 January 2024 36 @@ -2381,9 +2381,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Under MS-Windows, this will cause to be run whatever program the system - has associated with dvi files. (The same applies for a postscript + has associated with dvi files. (The same applies for a postscript viewer and a pdf viewer.) But note that this trick is not always suit- - able for the pdf previwer, if your system has acroread for the default + able for the pdf previwer, if your system has acroread for the default pdf viewer. As explained elsewhere, acroread under MS-Windows does not work well with latex and latexmk, because acroread locks the pdf file. @@ -2392,18 +2392,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $lpr = 'NONE lpr'; - This typically is used when an appropriate command does not exist on + This typically is used when an appropriate command does not exist on your system. The string after the "NONE" is effectively a comment. Options to commands: Setting the name of a command can be used not only for changing the name of the command called, but also to add options to - command. Suppose you want latexmk to use latex with source specials - enabled. Then you might use the following line in an initialization + command. Suppose you want latexmk to use latex with source specials + enabled. Then you might use the following line in an initialization file: $latex = 'latex --src-specials %O %S'; - Running a subroutine instead of an external command: Use a specifica- + Running a subroutine instead of an external command: Use a specifica- tion starting with "internal", as in $latex = 'internal mylatex %O %S'; @@ -2413,31 +2413,31 @@ LATEXMK(1) General Commands Manual LATEXMK(1) return system 'latex', @args; } - For some of the more exotic possibilities that then become available, - see the section "Advanced configuration: Some extra resources and ad- - vanced tricks". Also see some of the examples in the directory exam- + For some of the more exotic possibilities that then become available, + see the section "Advanced configuration: Some extra resources and ad- + vanced tricks". Also see some of the examples in the directory exam- ple_rcfiles in the latexmk distribution. - Advanced tricks: Normally one specifies a single command for the com- - mands invoked by latexmk. Naturally, if there is some complicated ad- - ditional processing you need to do in your special situation, you can + Advanced tricks: Normally one specifies a single command for the com- + mands invoked by latexmk. Naturally, if there is some complicated ad- + ditional processing you need to do in your special situation, you can write a script (or batch file) to do the processing, and then configure latexmk to use your script in place of the standard program. - You can also use a Perl subroutine instead of a script -- see above. + You can also use a Perl subroutine instead of a script -- see above. This is generally the most flexible and portable solution. It is also possible to configure latexmk to run multiple commands. For - example, if when running pdflatex to generate a pdf file from a tex + example, if when running pdflatex to generate a pdf file from a tex file you need to run another program after pdflatex to perform some ex- tra processing, you could do something like: - $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk + $pdflatex = 'pdflatex --shell-escape %O %S; pst2pdf_for_latexmk %B'; - 10 January 2024 37 + 31 January 2024 37 @@ -2446,8 +2446,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - This definition assumes you are using a UNIX-like system (which in- - cludes Linux and OS-X), so that the two commands to be run are sepa- + This definition assumes you are using a UNIX-like system (which in- + cludes Linux and OS-X), so that the two commands to be run are sepa- rated by the semicolon in the middle of the string. If you are using MS-Windows, you would replace the above line by @@ -2455,36 +2455,36 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $pdflatex = 'cmd /c pdflatex --shell-escape %O %S' . '&& pst2pdf_for_latexmk %B'; - Here, the UNIX command separator ; is replaced by &&. In addition, + Here, the UNIX command separator ; is replaced by &&. In addition, there is a problem that some versions of Perl on MS-Windows do not obey - the command separator; this problem is overcome by explicitly invoking + the command separator; this problem is overcome by explicitly invoking the MS-Windows command-line processor cmd.exe. LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES - In this section are specified the variables whose values can be ad- - justed to configure latexmk. (See the earlier section "Configura- - tion/Initialization (rc) Files" for the files where the configurations + In this section are specified the variables whose values can be ad- + justed to configure latexmk. (See the earlier section "Configura- + tion/Initialization (rc) Files" for the files where the configurations are done.) Default values are indicated in brackets. Note that for variables that - are boolean in character, concerning whether latexmk does or does not - behave in a certain way, a non-zero value, normally 1, indicates true, - i.e., the behavior occurs, while a zero value indicates a false value, + are boolean in character, concerning whether latexmk does or does not + behave in a certain way, a non-zero value, normally 1, indicates true, + i.e., the behavior occurs, while a zero value indicates a false value, i.e., the behavior does not occur. $allow_switch [1] - This controls what happens when the output extension of latex, - pdflatex, lualatex or xelatex differs from what is expected. + This controls what happens when the output extension of latex, + pdflatex, lualatex or xelatex differs from what is expected. (The possible extensions are .dvi, .pdf, .xdv.) This can happen - with the use of the \pdfoutput macro in a document compiled un- - der latex or pdflatex, or with the use of the \outputmode macro + with the use of the \pdfoutput macro in a document compiled un- + der latex or pdflatex, or with the use of the \outputmode macro under lualatex. It can also happen with certain kinds of incor- rect configuration. - In such a case, latexmk can appropriately adjust its network of + In such a case, latexmk can appropriately adjust its network of rules. The adjustment is made if $allow_switch is on, and if no request for a dvi or ps file has been made. @@ -2492,18 +2492,18 @@ LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES $always_view_file_via_temporary [0] - Whether .ps and .pdf files are initially to be made in a tempo- - rary directory and then moved to the final location. (This ap- + Whether .ps and .pdf files are initially to be made in a tempo- + rary directory and then moved to the final location. (This ap- plies to dvips, dvipdf, and ps2pdf operations, and the filtering operators on .dvi and .ps files. It does not apply to pdflatex, - unfortunately, since pdflatex provides no way of specifying a + unfortunately, since pdflatex provides no way of specifying a chosen name for the output file.) This use of a temporary file solves a problem that the making of - 10 January 2024 38 + 31 January 2024 38 @@ -2518,58 +2518,58 @@ LATEXMK(1) General Commands Manual LATEXMK(1) which can cause havoc. See the $pvc_view_file_via_temporary variable for a setting that - applies only if preview-continuous mode (-pvc option) is used. + applies only if preview-continuous mode (-pvc option) is used. See $tmpdir for the setting of the directory where the temporary file is created. $analyze_input_log_always [1] - After a run of latex (etc), always analyze .log for input files - in the <...> and (...) constructions. Otherwise, only do the + After a run of latex (etc), always analyze .log for input files + in the <...> and (...) constructions. Otherwise, only do the analysis when fls file doesn't exist or is out of date. - Under normal circumstances, the data in the fls file is reli- + Under normal circumstances, the data in the fls file is reli- able, and the test of the log file gets lots of false positives; - usually $analyze_input_log_always is best set to zero. But the - test of the log file is needed at least in the following situa- - tion: When a user needs to persuade latexmk that a certain file - is a source file, and latexmk doesn't otherwise find it. Then - the user can write code that causes a line with (...) to be - written to log file. One important case is for lualatex, which - doesn't always generate lines in the .fls file for input lua - files. (The situation with lualatex is HIGHLY version depen- - dent, e.g., there was a big change between TeXLive 2016 and + usually $analyze_input_log_always is best set to zero. But the + test of the log file is needed at least in the following situa- + tion: When a user needs to persuade latexmk that a certain file + is a source file, and latexmk doesn't otherwise find it. Then + the user can write code that causes a line with (...) to be + written to log file. One important case is for lualatex, which + doesn't always generate lines in the .fls file for input lua + files. (The situation with lualatex is HIGHLY version depen- + dent, e.g., there was a big change between TeXLive 2016 and TeXLive 2017.) - To keep backward compatibility with older versions of latexmk, + To keep backward compatibility with older versions of latexmk, the default is to set $analyze_input_log_always to 1. $auto_rc_use [1] - Whether to automatically read the standard initialization (rc) + Whether to automatically read the standard initialization (rc) files, which are the system RC file, the user's RC file, and the RC file in the current directory. The command line option -norc - can be used to turn this setting off. Each RC file co2uld also - turn this setting off, i.e., it could set $auto_rc_use to zero + can be used to turn this setting off. Each RC file co2uld also + turn this setting off, i.e., it could set $auto_rc_use to zero to prevent automatic reading of the later RC files. - This variable does not affect the reading of RC files specified + This variable does not affect the reading of RC files specified on the command line by the -r option. $aux_dir [""] - The aux directory, i.e., the directory in which auxiliary files + The aux directory, i.e., the directory in which auxiliary files (aux, log, etc) are to be written by a run of *latex. - If this variable is not set, but $out_dir is set, then latexmk - takes the aux directory to equal the output directory which is + If this variable is not set, but $out_dir is set, then latexmk + takes the aux directory to equal the output directory which is the directory to which final output files are to be written. - If neither variable is set, then the current directory when + If neither variable is set, then the current directory when - 10 January 2024 39 + 31 January 2024 39 @@ -2578,64 +2578,64 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - *latex is invoked is used both for the aux and output directo- + *latex is invoked is used both for the aux and output directo- ries. If the aux and output directories are distinct, then the aux di- - rectory contains all generated files with the exception of "fi- - nal output files", which are defined to be .dvi, .ps, .pdf, + rectory contains all generated files with the exception of "fi- + nal output files", which are defined to be .dvi, .ps, .pdf, .synctex, and .synctex.gz files. - See the section AUXILIARY AND OUTPUT DIRECTORIES for more de- + See the section AUXILIARY AND OUTPUT DIRECTORIES for more de- tails. $aux_out_dir_report [0] - If this variable is set to 1, then prior to the processing of + If this variable is set to 1, then prior to the processing of each primary .tex file, list the settings for aux and output di- - rectories, after they have been normalized from the settings + rectories, after they have been normalized from the settings specified during initialization. - This report gives a reminder of where to look for generated + This report gives a reminder of where to look for generated files. - The report is done per primary .tex file, because of possible - directory changes for each file (when the -cd option is used). + The report is done per primary .tex file, because of possible + directory changes for each file (when the -cd option is used). In the simplest cases, the directory names are the same as orig- inally specified. But in general some clean up/normalization is - performed; this helps performance and cleans up output to the + performed; this helps performance and cleans up output to the screen. If this variable is set to 2, then halt after reporting the set- - tings for the aux and out directories, rather than continuing - with processing of tex files. This setting is primarily used - for debugging configuration issues. See the -dir-report-only + tings for the aux and out directories, rather than continuing + with processing of tex files. This setting is primarily used + for debugging configuration issues. See the -dir-report-only option. $bad_warning_is_error [0] - Whether to treat bad warnings reported by *latex in log file as - errors. The specifications of the warning messages are in + Whether to treat bad warnings reported by *latex in log file as + errors. The specifications of the warning messages are in @bad_warnings. @bad_warnings - Array of regular expressions specifying messages in log file - that are officially treated as warnings rather than errors by - *latex, but which a user may treat as errors: See $bad_warn- + Array of regular expressions specifying messages in log file + that are officially treated as warnings rather than errors by + *latex, but which a user may treat as errors: See $bad_warn- ing_is_error. - Currently the default set of these warnings is those about \end - occuring inside constructs. + Currently the default set of these warnings is those about \end + occurring inside constructs. $banner [0] - If nonzero, the banner message is printed across each page when + If nonzero, the banner message is printed across each page when - 10 January 2024 40 + 31 January 2024 40 @@ -2644,8 +2644,8 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - converting the dvi file to postscript. Without modifying the - variable $banner_message, this is equivalent to specifying the + converting the dvi file to postscript. Without modifying the + variable $banner_message, this is equivalent to specifying the -d option. Note that if $banner is nonzero, the $postscript_mode is assumed @@ -2654,7 +2654,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $banner_intensity [0.95] Equivalent to the -bi option, this is a decimal number between 0 - and 1 that specifies how dark to print the banner message. 0 is + and 1 that specifies how dark to print the banner message. 0 is black, 1 is white. The default is just right if your toner car- tridge isn't running too low. @@ -2663,19 +2663,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1) dvi file to postscript. This is equivalent to the -bm option. $banner_scale [220.0] - A decimal number that specifies how large the banner message - will be printed. Experimentation is necessary to get the right - scale for your message, as a rule of thumb the scale should be - about equal to 1100 divided by the number of characters in the - message. The Default is just right for 5 character messages. + A decimal number that specifies how large the banner message + will be printed. Experimentation is necessary to get the right + scale for your message, as a rule of thumb the scale should be + about equal to 1100 divided by the number of characters in the + message. The Default is just right for 5 character messages. This is equivalent to the -bs option. @BIBINPUTS - This is an array variable, now mostly obsolete, that specifies - directories where latexmk should look for .bib files. By de- - fault it is set from the BIBINPUTS environment variable of the - operating system. If that environment variable is not set, a - single element list consisting of the current directory is set. + This is an array variable, now mostly obsolete, that specifies + directories where latexmk should look for .bib files. By de- + fault it is set from the BIBINPUTS environment variable of the + operating system. If that environment variable is not set, a + single element list consisting of the current directory is set. The format of the directory names depends on your operating sys- tem, of course. Examples for setting this variable are: @@ -2685,23 +2685,23 @@ LATEXMK(1) General Commands Manual LATEXMK(1) @BIBINPUTS = ( ".", "//server/bibfiles" ); @BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" ); - Note that under MS Windows, either a forward slash "/" or a - backward slash "\" can be used to separate pathname components, - so the first two and the second two examples are equivalent. - Each backward slash should be doubled to avoid running afoul of - Perl's rules for writing strings. Generally, it is simplest al- + Note that under MS Windows, either a forward slash "/" or a + backward slash "\" can be used to separate pathname components, + so the first two and the second two examples are equivalent. + Each backward slash should be doubled to avoid running afoul of + Perl's rules for writing strings. Generally, it is simplest al- ways to use forward slashes instead of backward slashes. Important note: This variable is now mostly obsolete in the cur- - rent version of latexmk, since it now uses a better method of - searching for files using the kpsewhich command. However, if + rent version of latexmk, since it now uses a better method of + searching for files using the kpsewhich command. However, if your system is an unusual one without the kpsewhich command, you may need to set the variable @BIBINPUTS. - 10 January 2024 41 + 31 January 2024 41 @@ -2715,29 +2715,29 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $biber_silent_switch ["--onlylog"] - Switch(es) for the biber processing program when silent mode is + Switch(es) for the biber processing program when silent mode is on. $bibtex ["bibtex %O %S"] The BibTeX processing program. $bibtex_fudge [1] - When using bibtex, whether to change directory to $aux_dir be- + When using bibtex, whether to change directory to $aux_dir be- fore running bibtex. The need arises as follows: - a. With bibtex before about 2019, if the filename given to it + a. With bibtex before about 2019, if the filename given to it contains a path component, there was a bug that bibtex would not - find extra aux files, as produced by the \include command in + find extra aux files, as produced by the \include command in TeX. - b. With all moderately recent versions of bibtex, bibtex may + b. With all moderately recent versions of bibtex, bibtex may refuse to write its bbl and blg files, for security reasons, for certain cases of the path component of the filename given to it. - However, there are also rare cases where the change-directory - method prevents bibtex from finding certain bib or bst files. + However, there are also rare cases where the change-directory + method prevents bibtex from finding certain bib or bst files. Then $bibtex_fudge needs to be set to 0. @@ -2748,26 +2748,26 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $bibtex_use [1] Under what conditions to run bibtex or biber. When latexmk dis- - covers from the log file that one (or more) bibtex/biber-gener- - ated bibliographies are used, it can run bibtex or biber when- - ever it appears necessary to regenerate the bbl file(s) from - their source bib database file(s). But sometimes, the bib + covers from the log file that one (or more) bibtex/biber-gener- + ated bibliographies are used, it can run bibtex or biber when- + ever it appears necessary to regenerate the bbl file(s) from + their source bib database file(s). But sometimes, the bib file(s) are not available (e.g., for a document obtained from an external archive), but the bbl files are provided. In that case - use of bibtex or biber will result in incorrect overwriting of - the precious bbl files. The variable $bibtex_use controls - whether this happens, and also controls whether or not .bbl + use of bibtex or biber will result in incorrect overwriting of + the precious bbl files. The variable $bibtex_use controls + whether this happens, and also controls whether or not .bbl files are deleted in a cleanup operation. The possible values of $bibtex_use are: - 0: never use bibtex or biber; never delete .bbl files in a + 0: never use bibtex or biber; never delete .bbl files in a cleanup. 1: only use bibtex or biber if the bib file(s) exist; never delete .bbl files in a cleanup. - 10 January 2024 42 + 31 January 2024 42 @@ -2777,63 +2777,63 @@ LATEXMK(1) General Commands Manual LATEXMK(1) 1.5: only use bibtex or biber if the bib files exist; - conditionally delete .bbl files in a cleanup (i.e., delete + conditionally delete .bbl files in a cleanup (i.e., delete them only when the bib files all exist). 2: run bibtex or biber whenever it appears necessary to update - the bbl file(s), without testing for the existence of the bib + the bbl file(s), without testing for the existence of the bib files; always delete .bbl files in a cleanup. - Note: When biber is being used, conditional use of biber can be - problematic. From latexmk's point of view the problem is that + Note: When biber is being used, conditional use of biber can be + problematic. From latexmk's point of view the problem is that because of how biber works, a full knowledge of its source files can only be obtained after running biber. In contrast, for bib- - tex, full information on which bib files are used is obtained + tex, full information on which bib files are used is obtained from the .aux file(s) after a run of *latex. But for biber, the - corresponding information is somewhat incomplete; this the in- - formation obtained in the .bcf file that is generated by the + corresponding information is somewhat incomplete; this the in- + formation obtained in the .bcf file that is generated by the biblatex package during a run of *latex. $cleanup_includes_cusdep_generated [0] - If nonzero, specifies that cleanup also deletes files that are + If nonzero, specifies that cleanup also deletes files that are generated by custom dependencies. (When doing a clean up, e.g., by use of the -C option, custom dependencies are those listed in the .fdb_latexmk file from a previous run.) $cleanup_includes_generated [0] - If nonzero, specifies that cleanup also deletes files that are + If nonzero, specifies that cleanup also deletes files that are detected in the fls file (or failing that, in log file) as being - generated. It will also include files made from these first + generated. It will also include files made from these first generation generated files. - This operation is somewhat dangerous, and can have unintended - consequences, since the files to be deleted are determined from - a file created by *latex, which can contain erroneous informa- + This operation is somewhat dangerous, and can have unintended + consequences, since the files to be deleted are determined from + a file created by *latex, which can contain erroneous informa- tion. Therefore this variable is turned off by default, and then files to be deleted are restricted to those explicitly specified - by patterns configured in the variables clean_ext, + by patterns configured in the variables clean_ext, clean_full_ext, and @generated_exts. Standard cases (e.g., .log - files) appear in latexmk's initial value for the array @gener- + files) appear in latexmk's initial value for the array @gener- ated_exts. $cleanup_mode [0] - If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for - cleanup except for .dvi, .ps and .pdf files, 3 for cleanup ex- - cept for dep and aux files. (There is also extra cleaning as + If nonzero, specifies cleanup mode: 1 for full cleanup, 2 for + cleanup except for .dvi, .ps and .pdf files, 3 for cleanup ex- + cept for dep and aux files. (There is also extra cleaning as specified by the $clean_ext, $clean_full_ext and @generated_exts variables.) - This variable is equivalent to specifying one of the -c or -C - options. But there should be no need to set this variable from + This variable is equivalent to specifying one of the -c or -C + options. But there should be no need to set this variable from an RC file. - 10 January 2024 43 + 31 January 2024 43 @@ -2843,9 +2843,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $clean_ext [""] - Extra extensions of files for latexmk to remove when any of the - clean-up options (-c or -C) is selected. The value of this - variable is a string containing the extensions separated by + Extra extensions of files for latexmk to remove when any of the + clean-up options (-c or -C) is selected. The value of this + variable is a string containing the extensions separated by spaces. It is also possible to specify a more general pattern of file to @@ -2856,50 +2856,50 @@ LATEXMK(1) General Commands Manual LATEXMK(1) files-%R/*"; in an initialization file will imply that when a clean-up opera- - tion is specified, not only is the standard set of files - deleted, but also files of the form FOO.out, FOO-blx.bib, FOO- - figures*.log, and pythontex-files-FOO/*, where FOO stands for + tion is specified, not only is the standard set of files + deleted, but also files of the form FOO.out, FOO-blx.bib, FOO- + figures*.log, and pythontex-files-FOO/*, where FOO stands for the basename of the file being processed (as in FOO.tex). - Most of the files to be deleted are relative to the directory - specified by $aux_dir. Note that if $out_dir but not $aux_dir - is set, then in its initialization, latexmk sets $aux_dir equal - to $out_dir. A normal situation is therefore that $aux_dir - equals $out_dir, which is the only case directly supported by - TeXLive, unlike MiKTeX. Note that even with TeXLive latexmk + Most of the files to be deleted are relative to the directory + specified by $aux_dir. Note that if $out_dir but not $aux_dir + is set, then in its initialization, latexmk sets $aux_dir equal + to $out_dir. A normal situation is therefore that $aux_dir + equals $out_dir, which is the only case directly supported by + TeXLive, unlike MiKTeX. Note that even with TeXLive latexmk does now support different values for the directories -- see the explanation of the $emulate_aux variable. If $out_dir and $aux_dir different, latexmk actually deletes any files of the specified names in both $aux_dir and $out_dir; this - is because under certain error conditions, the files may be put - in $out_dir instead of $aux_dir. This also handles the case of + is because under certain error conditions, the files may be put + in $out_dir instead of $aux_dir. This also handles the case of deleting any fls file, since that file is in $out_dir. - The filenames specified for a clean-up operation can refer not - only to regular files but also to directories. Directories are + The filenames specified for a clean-up operation can refer not + only to regular files but also to directories. Directories are only deleted if they are empty. An example of an application is - to pythontex, which creates files in a particular directory. - You can arrange to remove both the files and the directory by + to pythontex, which creates files in a particular directory. + You can arrange to remove both the files and the directory by setting $clean_ext = "pythontex-files-%R/* pythontex-files-%R"; - See also the (array) variable @generated_exts. In the past, - this variable had certain uses beyond that of $clean_ext. But - now, they accomplish the same things. In fact, after initial- - ization including the processing of command line options, la- + See also the (array) variable @generated_exts. In the past, + this variable had certain uses beyond that of $clean_ext. But + now, they accomplish the same things. In fact, after initial- + ization including the processing of command line options, la- texmk simply appends the list of extensions in $clean_ext to the array @generated_exts. $clean_full_ext [""] - Extra extensions of files for latexmk to remove when the -C op- - tion is selected, i.e., extensions of files to remove when the + Extra extensions of files for latexmk to remove when the -C op- + tion is selected, i.e., extensions of files to remove when the .dvi, etc files are to be cleaned-up. - 10 January 2024 44 + 31 January 2024 44 @@ -2910,62 +2910,62 @@ LATEXMK(1) General Commands Manual LATEXMK(1) More general patterns are allowed, as for $clean_ext. - The files specified by $clean_full_ext to be deleted are rela- + The files specified by $clean_full_ext to be deleted are rela- tive to the directory specified by $out_dir. $compiling_cmd [""], $failure_cmd [""], $warning_cmd [""], $success_cmd [""] - These variables specify commands that are executed at certain - points of compilations. One motivation for their existence is - to allow very useful convenient visual indications of compila- - tion status even when the window receiving the screen output of - the compilation is hidden. This is particularly useful in pre- + These variables specify commands that are executed at certain + points of compilations. One motivation for their existence is + to allow very useful convenient visual indications of compila- + tion status even when the window receiving the screen output of + the compilation is hidden. This is particularly useful in pre- view-continuous mode. - The commands are executed at the following points: $compil- - ing_cmd at the start of compilation, $success_cmd at the end of - a completely successful compilation, $failure_cmd at the end of + The commands are executed at the following points: $compil- + ing_cmd at the start of compilation, $success_cmd at the end of + a completely successful compilation, $failure_cmd at the end of an unsuccessful compilation, $warning_cmd at the of an otherwise successful compilation that gives warnings about undefined cita- tions or references or about multiply defined references. If any - of above variables is undefined or blank (the default situa- + of above variables is undefined or blank (the default situa- tion), then the corresponding command is not executed. - However, when $warning_cmd is not set, then in the case of a - compilation with warnings about references or citations, but - with no other error, one or other of $success_cmd or $fail- - ure_cmd is used (if it is set) according to the setting of + However, when $warning_cmd is not set, then in the case of a + compilation with warnings about references or citations, but + with no other error, one or other of $success_cmd or $fail- + ure_cmd is used (if it is set) according to the setting of $warnings_as_errors. An example of a simple setting of these variables is as follows - $compiling_cmd = "xdotool search --name \"%D\" set_window + $compiling_cmd = "xdotool search --name \"%D\" set_window --name \"%D compiling\""; - $success_cmd = "xdotool search --name \"%D\" set_window + $success_cmd = "xdotool search --name \"%D\" set_window --name \"%D OK\""; $warning_cmd = "xdotool search --name \"%D\" ". "set_window --name \"%D CITE/REF ISSUE\""; - $failure_cmd = "xdotool search --name \"%D\" set_window + $failure_cmd = "xdotool search --name \"%D\" set_window --name \"%D FAILURE\""; - These assume that the program xdotool is installed, that the - previewer is using an X-Window system for display, and that the - title of the window contains the name of the displayed file, as - it normally does. When the commands are executed, the place- - holder string %D is replaced by the name of the destination + These assume that the program xdotool is installed, that the + previewer is using an X-Window system for display, and that the + title of the window contains the name of the displayed file, as + it normally does. When the commands are executed, the place- + holder string %D is replaced by the name of the destination file, which is the previewed file. The above commands result in an appropriate string being appended to the filename in the win- dow title: " compiling", " OK", or " FAILURE". - Other placeholders that can be used are %S, %T, and %R, with %S - and %T normally being identical. These can be useful for a com- - mand changing the title of the edit window. The visual + Other placeholders that can be used are %S, %T, and %R, with %S + and %T normally being identical. These can be useful for a com- + mand changing the title of the edit window. The visual - 10 January 2024 45 + 31 January 2024 45 @@ -2975,17 +2975,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) indication in a window title can useful, since the user does not - have to keep shifting attention to the (possibly hidden) compi- + have to keep shifting attention to the (possibly hidden) compi- lation window to know the status of the compilation. - More complicated situations can best be handled by defining a - Perl subroutine to invoke the necessary commands, and using the - "internal" keyword in the definitions to get the subroutine to + More complicated situations can best be handled by defining a + Perl subroutine to invoke the necessary commands, and using the + "internal" keyword in the definitions to get the subroutine to be invoked. (See the section "Format of Command Specifications" for how to do this.) - Naturally, the above settings that invoke the xdotool program - are only applicable when the X-Window system is used for the + Naturally, the above settings that invoke the xdotool program + are only applicable when the X-Window system is used for the relevant window(s). For other cases, you will have to find what software solutions are available. @@ -2994,15 +2994,15 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Custom dependency list -- see section on "Custom Dependencies". @default_excluded_files [()] - When latexmk is invoked with no files specified on the command + When latexmk is invoked with no files specified on the command line, then, by default, it will process all files in the current directory with the extension .tex. (In general, it will process the files specified in the @default_files variable.) But sometimes you want to exclude particular files from this de- - fault list. In that case you can specify the excluded files in + fault list. In that case you can specify the excluded files in the array @default_excluded_files. For example if you wanted to - process all .tex files with the exception of common.tex, which + process all .tex files with the exception of common.tex, which is a not a standard alone LaTeX file but a file input by some or all of the others, you could do @@ -3012,26 +3012,26 @@ LATEXMK(1) General Commands Manual LATEXMK(1) If you have a variable or large number of files to be processed, this method saves you from having to list them in detail in @de- - fault_files and having to update the list every time you change + fault_files and having to update the list every time you change the set of files to be processed. - Notes: 1. This variable has no effect except when no files are + Notes: 1. This variable has no effect except when no files are specified on the latexmk command line. 2. Wildcards are allowed in @default_excluded_files. @default_files [("*.tex")] Default list of files to be processed. - If no filenames are specified on the command line, latexmk - processes all tex files specified in the @default_files vari- - able, which by default is set to all tex files ("*.tex") in the - current directory. This is a convenience: just run latexmk and - it will process an appropriate set of files. But sometimes you + If no filenames are specified on the command line, latexmk + processes all tex files specified in the @default_files vari- + able, which by default is set to all tex files ("*.tex") in the + current directory. This is a convenience: just run latexmk and + it will process an appropriate set of files. But sometimes you want only some of these files to be processed. In this case you - 10 January 2024 46 + 31 January 2024 46 @@ -3040,10 +3040,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - can list the files to be processed by setting @default_files in - an initialization file (e.g., the file "latexmkrc" in the cur- - rent directory). Then if no files are specified on the command - line then the files you specify by setting @default_files are + can list the files to be processed by setting @default_files in + an initialization file (e.g., the file "latexmkrc" in the cur- + rent directory). Then if no files are specified on the command + line then the files you specify by setting @default_files are processed. Three examples: @@ -3054,50 +3054,50 @@ LATEXMK(1) General Commands Manual LATEXMK(1) @default_files = ("*.tex", "*.dtx"); - Note that more than file may be given, and that the default ex- + Note that more than file may be given, and that the default ex- tension is ".tex". Wild cards are allowed. The parentheses are because @default_files is an array variable, i.e., a sequence of filename specifications is possible. - If you want latexmk to process all .tex files with a few excep- + If you want latexmk to process all .tex files with a few excep- tions, see the @default_excluded_files array variable. $dependents_phony [0] - If a list of dependencies is output, this variable determines - whether to include a phony target for each source file. If you - use the dependents list in a Makefile, the dummy rules work - around errors make gives if you remove header files without up- + If a list of dependencies is output, this variable determines + whether to include a phony target for each source file. If you + use the dependents list in a Makefile, the dummy rules work + around errors make gives if you remove header files without up- dating the Makefile to match. $dependents_list [0] - Whether to display a list(s) of dependencies at the end of a + Whether to display a list(s) of dependencies at the end of a run. $deps_escape ["none"] This variable determines which kind of escaping of space charac- ters to use in dependency lists. The possible values are "none", - "unix", "nmake", corresponding respectively to no escaping, es- - caping with a "\" suitable for standard Unix make, and escaping + "unix", "nmake", corresponding respectively to no escaping, es- + caping with a "\" suitable for standard Unix make, and escaping with "^", suitable for Microsoft's nmake. - Currently the only character escaped is a space, since that is - particularly common in file names and directory names. There - are other characters that would need escaping if a dependency + Currently the only character escaped is a space, since that is + particularly common in file names and directory names. There + are other characters that would need escaping if a dependency list is to be used as-is by a make program; but those characters (e.g., "$") commonly cause difficulties when used for .tex docu- - ments. Moreover, the detailed rules for which characters need + ments. Moreover, the detailed rules for which characters need to be escaped depends on the version of make. $deps_file ["-"] - Name of file to receive list(s) of dependencies at the end of a - run, to be used if $dependents_list is set. If the filename is - "-", then the dependency list is set to stdout (i.e., normally + Name of file to receive list(s) of dependencies at the end of a + run, to be used if $dependents_list is set. If the filename is + "-", then the dependency list is set to stdout (i.e., normally - 10 January 2024 47 + 31 January 2024 47 @@ -3110,10 +3110,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $do_cd [0] - Whether to change working directory to the directory specified - for the main source file before processing it. The default be- - havior is not to do this, which is the same as the behavior of - *latex programs. This variable is set by the -cd and -cd- op- + Whether to change working directory to the directory specified + for the main source file before processing it. The default be- + havior is not to do this, which is the same as the behavior of + *latex programs. This variable is set by the -cd and -cd- op- tions on latexmk's command line. $dvi_filter [empty] @@ -3122,48 +3122,48 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $dvilualatex ["dvilualatex %O %S"] - Specifies the command line to invoke the dvilualatex program. - Note that as with other programs, you can use this variable not - just to change the name of the program used, but also specify + Specifies the command line to invoke the dvilualatex program. + Note that as with other programs, you can use this variable not + just to change the name of the program used, but also specify options to the program. E.g., - $dvilualatex = "dvilualatex --src-specials + $dvilualatex = "dvilualatex --src-specials %O %S"; - To do a coordinated setting of all of $dvilualatex, $hilatex, + To do a coordinated setting of all of $dvilualatex, $hilatex, $latex, $pdflatex, $lualatex, and $xelatex, see the section "Ad- vanced Configuration". $dvi_mode [See below for default] - If one, generate a dvi version of the document by use of latex. + If one, generate a dvi version of the document by use of latex. Equivalent to the -dvi option. If 2, generate a dvi version of the document by use of dviluala- tex. Equivalent to the -dvilua option. - The variable $dvi_mode defaults to 0, but if no explicit re- - quests are made for other types of file (postscript, pdf), then - $dvi_mode will be set to 1. In addition, if a request for a - file for which a .dvi file is a prerequisite and $dvi_mode is + The variable $dvi_mode defaults to 0, but if no explicit re- + quests are made for other types of file (postscript, pdf), then + $dvi_mode will be set to 1. In addition, if a request for a + file for which a .dvi file is a prerequisite and $dvi_mode is zero, then $dvi_mode is set to 1. $dvilualatex_silent_switch ["-interaction=batchmode"] - Switch(es) for the dvilualatex program (specified in the vari- + Switch(es) for the dvilualatex program (specified in the vari- able $dvilualatex) when silent mode is on. - See details of the $latex_silent_switch for other information + See details of the $latex_silent_switch for other information that equally applies to $dvilualatex_silent_switch. $dvi_previewer ["start xdvi %O %S" under UNIX] - The command to invoke a dvi-previewer. [Under MS-Windows the + The command to invoke a dvi-previewer. [Under MS-Windows the - 10 January 2024 48 + 31 January 2024 48 @@ -3172,64 +3172,64 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - default is "start"; then latexmk arranges to use the MS-Windows - start program, which will cause to be run whatever command the + default is "start"; then latexmk arranges to use the MS-Windows + start program, which will cause to be run whatever command the system has associated with .dvi files.] - Important note: Normally you will want to have a previewer run + Important note: Normally you will want to have a previewer run detached, so that latexmk doesn't wait for the previewer to ter- - minate before continuing its work. So normally you should pre- - fix the command by "start ", which flags to latexmk that it - should do the detaching of the previewer itself (by whatever - method is appropriate to the operating system). But sometimes + minate before continuing its work. So normally you should pre- + fix the command by "start ", which flags to latexmk that it + should do the detaching of the previewer itself (by whatever + method is appropriate to the operating system). But sometimes letting latexmk do the detaching is not appropriate (for a vari- - ety of non-trivial reasons), so you should put the "start " bit + ety of non-trivial reasons), so you should put the "start " bit in yourself, whenever it is needed. $dvi_previewer_landscape ["start xdvi %O %S"] The command to invoke a dvi-previewer in landscape mode. [Under - MS-Windows the default is "start"; then latexmk arranges to use - the MS-Windows start program, which will cause to be run what- + MS-Windows the default is "start"; then latexmk arranges to use + the MS-Windows start program, which will cause to be run what- ever command the system has associated with .dvi files.] $dvipdf ["dvipdf -dALLOWPSTRANSPARENCY %O %S %D"] - Command to convert .dvi to .pdf file. A common reconfiguration - is to use the dvipdfm command, which needs its arguments in a + Command to convert .dvi to .pdf file. A common reconfiguration + is to use the dvipdfm command, which needs its arguments in a different order: $dvipdf = "dvipdfm %O -o %D %S"; - WARNING: The default dvipdf script generates pdf files with + WARNING: The default dvipdf script generates pdf files with bitmapped fonts, which do not look good when viewed by acroread. - That script should be modified to give dvips the options "-P + That script should be modified to give dvips the options "-P pdf" to ensure that type 1 fonts are used in the pdf file. $dvipdf_silent_switch ["-q"] Switch(es) for dvipdf program when silent mode is on. - N.B. The standard dvipdf program runs silently, so adding the - silent switch has no effect, but is actually innocuous. But if - an alternative program is used, e.g., dvipdfmx, then the silent - switch has an effect. The default setting is correct for + N.B. The standard dvipdf program runs silently, so adding the + silent switch has no effect, but is actually innocuous. But if + an alternative program is used, e.g., dvipdfmx, then the silent + switch has an effect. The default setting is correct for dvipdfm and dvipdfmx. $dvips ["dvips %O -o %D %S"] - The program to used as a filter to convert a .dvi file to a .ps - file. If pdf is going to be generated from pdf, then the value - of the $dvips_pdf_switch variable -- see below -- will be in- + The program to used as a filter to convert a .dvi file to a .ps + file. If pdf is going to be generated from pdf, then the value + of the $dvips_pdf_switch variable -- see below -- will be in- cluded in the options substituted for "%O". $dvips_landscape ["dvips -tlandscape %O -o %D %S"] - The program to used as a filter to convert a .dvi file to a .ps + The program to used as a filter to convert a .dvi file to a .ps file in landscape mode. $dvips_pdf_switch ["-P pdf"] - Switch(es) for dvips program when pdf file is to be generated + Switch(es) for dvips program when pdf file is to be generated from .ps file. - 10 January 2024 49 + 31 January 2024 49 @@ -3242,60 +3242,60 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Switch(es) for dvips program when silent mode is on. $dvi_update_command [""] - When the dvi previewer is set to be updated by running a com- - mand, this is the command that is run. See the information for + When the dvi previewer is set to be updated by running a com- + mand, this is the command that is run. See the information for the variable $dvi_update_method for further information, and see - information on the variable $pdf_update_method for an example + information on the variable $pdf_update_method for an example for the analogous case of a pdf previewer. $dvi_update_method [2 under UNIX, 1 under MS-Windows] - How the dvi viewer updates its display when the dvi file has - changed. The values here apply equally to the $pdf_up- + How the dvi viewer updates its display when the dvi file has + changed. The values here apply equally to the $pdf_up- date_method and to the $ps_update_method variables. 0 => update is automatic, 1=> manual update by user, which may only mean a mouse click on the viewer's window or may mean a more serious action. - 2 => Send the signal, whose number is in the variable - $dvi_update_signal. The default value under UNIX is suitable + 2 => Send the signal, whose number is in the variable + $dvi_update_signal. The default value under UNIX is suitable for xdvi. - 3 => Viewer cannot do an update, because it locks the file. + 3 => Viewer cannot do an update, because it locks the file. (As with acroread under MS-Windows.) - 4 => run a command to do the update. The command is speci- + 4 => run a command to do the update. The command is speci- fied by the variable $dvi_update_command. - See information on the variable $pdf_update_method for an exam- + See information on the variable $pdf_update_method for an exam- ple of updating by command. $dvi_update_signal [Under UNIX: SIGUSR1, which is a system-dependent value] - The number of the signal that is sent to the dvi viewer when it - is updated by sending a signal -- see the information on the - variable $dvi_update_method. The default value is the one ap- + The number of the signal that is sent to the dvi viewer when it + is updated by sending a signal -- see the information on the + variable $dvi_update_method. The default value is the one ap- propriate for xdvi on a UNIX system. $emulate_aux [0] - Whether to emulate the use of aux directory when $aux_dir and + Whether to emulate the use of aux directory when $aux_dir and $out_dir are different, rather than using the -aux-directory op- - tion for the *latex programs. (MiKTeX supports -aux-directory, + tion for the *latex programs. (MiKTeX supports -aux-directory, but TeXLive doesn't.) - If you use a version of *latex that doesn't support -aux-direc- - tory, e.g., TeXLive, latexmk will automatically switch aux_dir + If you use a version of *latex that doesn't support -aux-direc- + tory, e.g., TeXLive, latexmk will automatically switch aux_dir emulation on after the first run of *latex, because it will find the .log file in the wrong place. But it is better to set $emu- - late_aux to 1 in an rc file, or equivalently to use the -emu- + late_aux to 1 in an rc file, or equivalently to use the -emu- late-aux-dir option. This emulation mode works equally well with MiKTeX. - Aux directory emulation means that when *latex is invoked, the + Aux directory emulation means that when *latex is invoked, the output directory provided to *latex is set to be the desired aux - directory. After that, any files that need to be in the output - directory will be moved there by latexmk. (These are the files - with extensions .dvi, .ps, .pdf, .synctex, .synctex.gz, and, + directory. After that, any files that need to be in the output + directory will be moved there by latexmk. (These are the files + with extensions .dvi, .ps, .pdf, .synctex, .synctex.gz, and, - 10 January 2024 50 + 31 January 2024 50 @@ -3313,26 +3313,26 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $fdb_ext ["fdb_latexmk"] - The extension of the file which latexmk generates to contain a - database of information on source files. You will not normally + The extension of the file which latexmk generates to contain a + database of information on source files. You will not normally need to change this. @file_not_found - This an array of Perl regular expressions that are patterns to - find messages in the .log file from a run of *latex that indi- - cate that a file was looked for and not found. To see the cur- - rent default set, you should look at the definition of + This an array of Perl regular expressions that are patterns to + find messages in the .log file from a run of *latex that indi- + cate that a file was looked for and not found. To see the cur- + rent default set, you should look at the definition of @file_not_found in the latexmk.pl file. - In the regular expression, the string for the name of the miss- - ing file should be enclosed in parentheses. That carries the - implication that after latexmk gets a succesful match to the - pattern, the variable $1 is set to the filename, which is then + In the regular expression, the string for the name of the miss- + ing file should be enclosed in parentheses. That carries the + implication that after latexmk gets a successful match to the + pattern, the variable $1 is set to the filename, which is then picked up by latexmk. - If you happen to encounter a package that gives a missing file - message of a different form than one that matches one of the + If you happen to encounter a package that gives a missing file + message of a different form than one that matches one of the built-in patterns, you can add another pattern to the array. An example would be @@ -3345,23 +3345,23 @@ LATEXMK(1) General Commands Manual LATEXMK(1) But the corresponding string specification in the push statement has to have the backslashes doubled. - This regular expression matches a line that starts with 'No - file', then has one or more white space characters, then any - number of characters forming the filename, then possible white - space, and finally the end of the line. (See documentation on + This regular expression matches a line that starts with 'No + file', then has one or more white space characters, then any + number of characters forming the filename, then possible white + space, and finally the end of the line. (See documentation on Perl regular expressions for details.) $filetime_causality_threshold [5] - The use of this variable is as follows: At a number of places, - latexmk needs to determine whether a particular file has been - produced during a just-concluded run of some rule/program or is + The use of this variable is as follows: At a number of places, + latexmk needs to determine whether a particular file has been + produced during a just-concluded run of some rule/program or is leftover from a previous run. (An example is the production of a - .bcf file by the biblatex package during a run of *latex to + .bcf file by the biblatex package during a run of *latex to - 10 January 2024 51 + 31 January 2024 51 @@ -3370,52 +3370,52 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - provide bibliographic information to the biber program. If a + provide bibliographic information to the biber program. If a .bcf file is not produced during a current run of *latex, but is - leftover from a previous run, then latexmk has to conclude that - the .tex document has changed so that biber is no longer to be + leftover from a previous run, then latexmk has to conclude that + the .tex document has changed so that biber is no longer to be used.) - Latexmk's criterion that a file has been produced during a run - is that the modification time of the file is more recent than - the system time at the beginning of the run. Bascially, if the - modification time is earlier than this, then it is a leftover + Latexmk's criterion that a file has been produced during a run + is that the modification time of the file is more recent than + the system time at the beginning of the run. Bascially, if the + modification time is earlier than this, then it is a leftover from a previous run. However, a naive use of the criterion can, - among other things, run afoul of the granularity of how file - times are stored in some file systems, which means it is possi- - ble that the filesystem's reported time for a file might be a - second or more earlier than the actual modification time, the + among other things, run afoul of the granularity of how file + times are stored in some file systems, which means it is possi- + ble that the filesystem's reported time for a file might be a + second or more earlier than the actual modification time, the exact difference being quite random. - The variable $filetime_causality_threshold allows an appopriate - sloppiness in latexmk's use of file modification time. It can - be quite generous; it should merely be less than the time scale - on which a human user makes changes to source files for a docu- + The variable $filetime_causality_threshold allows an appopriate + sloppiness in latexmk's use of file modification time. It can + be quite generous; it should merely be less than the time scale + on which a human user makes changes to source files for a docu- ment (or to configuration files, etc). $fls_uses_out_dir [0] - This variable determines whether or not the .fls file should be - in the output directory instead of the natural directory, which + This variable determines whether or not the .fls file should be + in the output directory instead of the natural directory, which is the aux directory. If the variable is nonzero, the .fls file is to be in the output directory. See the section AUXILIARY AND - OUTPUT DIRECTORIES for more details about these directories. - The rationale for the existence of the variable + OUTPUT DIRECTORIES for more details about these directories. + The rationale for the existence of the variable $fls_uses_aux_dir is explained there. In all cases, if latexmk finds that an .fls file has been gener- - ated in the opposite directory to the one specified by - $fls_uses_out_dir, it copies the file to the other directory - (aux or output directory as appropriate). The file is copied - rather than simply moved, to avoid potential clashes with other - software that assumes the .fls file is generated in the direc- - tory it was written to by *latex. Thus the effect an incorrect + ated in the opposite directory to the one specified by + $fls_uses_out_dir, it copies the file to the other directory + (aux or output directory as appropriate). The file is copied + rather than simply moved, to avoid potential clashes with other + software that assumes the .fls file is generated in the direc- + tory it was written to by *latex. Thus the effect an incorrect setting of $fls_uses_out_dir is only to cause a superfluous copy of the .fls file to be generated. $force_mode [0] - If nonzero, continue processing past minor latex errors includ- + If nonzero, continue processing past minor latex errors includ- ing unrecognized cross references. Equivalent to specifying the -f option. @@ -3423,11 +3423,11 @@ LATEXMK(1) General Commands Manual LATEXMK(1) @generated_exts [( 'aux', 'bcf', 'fls', 'idx', 'ind', 'lof', 'lot', 'out', 'toc', 'blg', 'ilg', 'log', 'xdv' )] - This contains a list of extensions for files that are generated + This contains a list of extensions for files that are generated - 10 January 2024 52 + 31 January 2024 52 @@ -3436,64 +3436,64 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - during processing, and that should be deleted during a main - clean up operation, as invoked by the command line option -c. + during processing, and that should be deleted during a main + clean up operation, as invoked by the command line option -c. (The use of -C or -gg gives this clean up and more.) - The default values are extensions for standard files generated - by *latex, bibtex, and the like. (Note that the clean up also - deletes the fdb_latexmk file, but that's separately coded into + The default values are extensions for standard files generated + by *latex, bibtex, and the like. (Note that the clean up also + deletes the fdb_latexmk file, but that's separately coded into latexmk, currently.) - After initialization of latexmk and the processing of its com- - mand line, the items in clean_ext are appended to @gener- - ated_exts. So these two variables have the same meaning (con- + After initialization of latexmk and the processing of its com- + mand line, the items in clean_ext are appended to @gener- + ated_exts. So these two variables have the same meaning (con- trary to older versions of latexmk). - The items in @generated_exts are normally extensions of files, - whose base name is the same as the main tex file. But it is - also possible to specify patterns including that basename --- + The items in @generated_exts are normally extensions of files, + whose base name is the same as the main tex file. But it is + also possible to specify patterns including that basename --- see the explanation of the variable $clean_ext. In addition to specifying files to be deleted in a clean up, la- - texmk uses the same specification to assist its examination of - changes in source files: Under some situations it needs to find - those changes in files (since a previous run) that are expected - to be due to the user editing a file. This contrasts with the + texmk uses the same specification to assist its examination of + changes in source files: Under some situations it needs to find + those changes in files (since a previous run) that are expected + to be due to the user editing a file. This contrasts with the cases of files that are generated by some program run by latexmk - and that differ from the results of the previous run. This use - of @generated_exts is normally unimportant, given the usual ac- - curacy of latexmk's other ways of determining these generated + and that differ from the results of the previous run. This use + of @generated_exts is normally unimportant, given the usual ac- + curacy of latexmk's other ways of determining these generated files. - A convenient way to add an extra extension to the list, without - losing the already defined ones is to use a push command in the + A convenient way to add an extra extension to the list, without + losing the already defined ones is to use a push command in the line in an RC file. E.g., push @generated_exts, "end"; adds the extension "end" to the list of predefined generated ex- - tensions. (This extension is used by the RevTeX package, for + tensions. (This extension is used by the RevTeX package, for example.) $go_mode [0] - If nonzero, process files regardless of timestamps, and is then + If nonzero, process files regardless of timestamps, and is then equivalent to the -g option. %hash_calc_ignore_pattern !!!This variable is for experts only!!! - The general rule latexmk uses for determining when an extra run - of some program is needed is that one of the source files has - changed. But consider for example a latex package that causes - an encapsulated postscript file (an "eps" file) to be made that - is to be read in on the next run. The file contains a comment + The general rule latexmk uses for determining when an extra run + of some program is needed is that one of the source files has + changed. But consider for example a latex package that causes + an encapsulated postscript file (an "eps" file) to be made that + is to be read in on the next run. The file contains a comment - 10 January 2024 53 + 31 January 2024 53 @@ -3502,10 +3502,10 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - line giving its creation date and time. On the next run the - time changes, latex sees that the eps file has changed, and - therefore reruns latex. This causes an infinite loop, that is - only terminated because latexmk has a limit on the number of + line giving its creation date and time. On the next run the + time changes, latex sees that the eps file has changed, and + therefore reruns latex. This causes an infinite loop, that is + only terminated because latexmk has a limit on the number of runs to guard against pathological situations. But the changing line has no real effect, since it is a comment. @@ -3514,31 +3514,31 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: '; This creates a rule for files with extension .eps about lines to - ignore. The left-hand side is a Perl idiom for setting an item - in a hash. Note that the file extension is specified without a + ignore. The left-hand side is a Perl idiom for setting an item + in a hash. Note that the file extension is specified without a period. The value, on the right-hand side, is a string contain- - ing a regular expression. (See documentation on Perl for how - they are to be specified in general.) This particular regular - expression specifies that lines beginning with "%%CreationDate: - " are to be ignored in deciding whether a file of the given ex- + ing a regular expression. (See documentation on Perl for how + they are to be specified in general.) This particular regular + expression specifies that lines beginning with "%%CreationDate: + " are to be ignored in deciding whether a file of the given ex- tension .eps has changed. - There is only one regular expression available for each exten- - sion. If you need more one pattern to specify lines to ignore, - then you need to combine the patterns into a single regular ex- - pression. The simplest method is separate the different simple - patterns by a vertical bar character (indicating "alternation" + There is only one regular expression available for each exten- + sion. If you need more one pattern to specify lines to ignore, + then you need to combine the patterns into a single regular ex- + pression. The simplest method is separate the different simple + patterns by a vertical bar character (indicating "alternation" in the jargon of regular expressions). For example, - $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: |^%%Ti- + $hash_calc_ignore_pattern{'eps'} = '^%%CreationDate: |^%%Ti- tle: '; causes lines starting with either "^%%CreationDate: " or "^%%Ti- tle: " to be ignored. - It may happen that a pattern to be ignored is specified in, for - example, in a system or user initialization file, and you wish - to remove this in a file that is read later. To do this, you + It may happen that a pattern to be ignored is specified in, for + example, in a system or user initialization file, and you wish + to remove this in a file that is read later. To do this, you use Perl's delete function, e.g., delete $hash_calc_ignore_pattern{'eps'}; @@ -3549,17 +3549,17 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $hnt_mode [0] - Whether to generate a hnt version of the document by use of hi- + Whether to generate a hnt version of the document by use of hi- latex. Can be turned on by the use of the -hnt option. $jobname [""] - This specifies the jobname, i.e., the basename that is used for + This specifies the jobname, i.e., the basename that is used for - 10 January 2024 54 + 31 January 2024 54 @@ -3568,56 +3568,56 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - generated files (.aux, .log, .dvi, .ps, .pdf, etc). If this - variable is a null string, then the basename is the basename of - the main tex file. (At present, the string in $jobname should + generated files (.aux, .log, .dvi, .ps, .pdf, etc). If this + variable is a null string, then the basename is the basename of + the main tex file. (At present, the string in $jobname should not contain spaces.) - The placeholder '%A' is permitted. This will be substituted by + The placeholder '%A' is permitted. This will be substituted by the basename of the TeX file. The primary purpose is when a va- - riety of tex files are to be processed, and you want to use a - different jobname for each but one that is distinct for each. - Thus if you wanted to compare compilations of a set of files on + riety of tex files are to be processed, and you want to use a + different jobname for each but one that is distinct for each. + Thus if you wanted to compare compilations of a set of files on different operating systems, with distinct filenames for all the cases, you could set $jobname = "%A-$^O"; - in an initialization file. (Here $^O is a variable provided by + in an initialization file. (Here $^O is a variable provided by perl that contains perl's name for the operating system.) - Suppose you had .tex files test1.tex and test2.tex. Then when + Suppose you had .tex files test1.tex and test2.tex. Then when you run latexmk -pdf *.tex - both files will be compiled. The .aux, .log, and .pdf files - will have basenames test1-MSWin32 ante test2-MSWin32 on a MS- + both files will be compiled. The .aux, .log, and .pdf files + will have basenames test1-MSWin32 ante test2-MSWin32 on a MS- Windows system, test1-darwin and test2-darwin on an OS-X system, and a variety of similar cases on linux systems. $kpsewhich ["kpsewhich %S"] - The program called to locate a source file when the name alone - is not sufficient. Most filenames used by latexmk have suffi- + The program called to locate a source file when the name alone + is not sufficient. Most filenames used by latexmk have suffi- cient path information to be found directly. But sometimes, no- tably when a .bib or a .bst file is found from the log file of a - bibtex or biber run, only the base name of the file is known, + bibtex or biber run, only the base name of the file is known, but not its path. The program specified by $kpsewhich is used to find it. - (For advanced users: Because of the different way in which la- + (For advanced users: Because of the different way in which la- texmk uses the command specified in $kpsewhich, some of the pos- sibilities listed in the FORMAT OF COMMAND SPECIFICATIONS do not - apply. The internal and start keywords are not available. A + apply. The internal and start keywords are not available. A simple command specification with possible options and then "%S" - is all that is guaranteed to work. Note that for other com- + is all that is guaranteed to work. Note that for other com- mands, "%S" is substituted by a single source file. In contrast, for $kpsewhich, "%S" may be substituted by a long list of space- - separated filenames, each of which is quoted. The result on + separated filenames, each of which is quoted. The result on STDOUT of running the command is then piped to latexmk.) - See also the @BIBINPUTS variable for another way that latexmk + See also the @BIBINPUTS variable for another way that latexmk also uses to try to locate files; it applies only in the case of .bib files. @@ -3625,7 +3625,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 55 + 31 January 2024 55 @@ -3635,52 +3635,52 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $kpsewhich_show [0] - Whether to show diagnostics about invocations of kpsewhich: the - command line use to invoke it and the results. These diagnos- - tics are shown if $kpsewhich_show is non-zero or if diagnostics - mode is on. (But in the second case, lots of other diagnostics - are also shown.) Without these diagnostics there is nothing - visible in latexmk's screen output about invocations of kpse- + Whether to show diagnostics about invocations of kpsewhich: the + command line use to invoke it and the results. These diagnos- + tics are shown if $kpsewhich_show is non-zero or if diagnostics + mode is on. (But in the second case, lots of other diagnostics + are also shown.) Without these diagnostics there is nothing + visible in latexmk's screen output about invocations of kpse- which. $landscape_mode [0] If nonzero, run in landscape mode, using the landscape mode pre- - viewers and dvi to postscript converters. Equivalent to the -l + viewers and dvi to postscript converters. Equivalent to the -l option. Normally not needed with current previewers. $latex ["latex %O %S"] - Specifies the command line for the LaTeX processing program. - Note that as with other programs, you can use this variable not - just to change the name of the program used, but also specify + Specifies the command line for the LaTeX processing program. + Note that as with other programs, you can use this variable not + just to change the name of the program used, but also specify options to the program. E.g., $latex = "latex --src-specials %O %S"; - To do a coordinated setting of all of $dvilualatex, $hilatex, + To do a coordinated setting of all of $dvilualatex, $hilatex, $latex, $pdflatex, $lualatex, and $xelatex, see the section "Ad- vanced Configuration". %latex_input_extensions - This variable specifies the extensions tried by latexmk when it - finds that a LaTeX run resulted in an error that a file has not - been found, and the file is given without an extension. This - typically happens when LaTeX commands of the form \input{file} - or \includegraphics{figure}, when the relevant source file does + This variable specifies the extensions tried by latexmk when it + finds that a LaTeX run resulted in an error that a file has not + been found, and the file is given without an extension. This + typically happens when LaTeX commands of the form \input{file} + or \includegraphics{figure}, when the relevant source file does not exist. - In this situation, latexmk searches for custom dependencies to - make the missing file(s), but restricts it to the extensions - specified by the variable %latex_input_extensions. The default + In this situation, latexmk searches for custom dependencies to + make the missing file(s), but restricts it to the extensions + specified by the variable %latex_input_extensions. The default extensions are 'tex' and 'eps'. - (For Perl experts: %latex_input_extensions is a hash whose keys - are the extensions. The values are irrelevant.) Two subrou- - tines are provided for manipulating this and the related vari- - able %pdflatex_input_extensions, add_input_ext and remove_in- - put_ext. They are used as in the following examples are possi- + (For Perl experts: %latex_input_extensions is a hash whose keys + are the extensions. The values are irrelevant.) Two subrou- + tines are provided for manipulating this and the related vari- + able %pdflatex_input_extensions, add_input_ext and remove_in- + put_ext. They are used as in the following examples are possi- ble lines in an initialization file: remove_input_ext( 'latex', 'tex' ); @@ -3691,7 +3691,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 56 + 31 January 2024 56 @@ -3700,19 +3700,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - add the extension 'asdf to latex_input_extensions. (Naturally + add the extension 'asdf to latex_input_extensions. (Naturally with such an extension, you should have made an appropriate cus- tom dependency for latexmk, and should also have done the appro- - priate programming in the LaTeX source file to enable the file - to be read. The standard extensions are handled by LaTeX and + priate programming in the LaTeX source file to enable the file + to be read. The standard extensions are handled by LaTeX and its graphics/graphicx packages.) $latex_silent_switch ["-interaction=batchmode"] - Switch(es) for the LaTeX processing program when silent mode is + Switch(es) for the LaTeX processing program when silent mode is on. - If you use MikTeX, you may prefer the results if you configure - the options to include -c-style-errors, e.g., by the following + If you use MikTeX, you may prefer the results if you configure + the options to include -c-style-errors, e.g., by the following line in an initialization file $latex_silent_switch = "-interaction=batchmode -c-style-er- @@ -3722,19 +3722,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $lpr ["lpr %O %S" under UNIX/Linux, "NONE lpr" under MS-Windows] The command to print postscript files. - Under MS-Windows (unlike UNIX/Linux), there is no standard pro- + Under MS-Windows (unlike UNIX/Linux), there is no standard pro- gram for printing files. But there are ways you can do it. For example, if you have gsview installed, you could use it with the option "/p": $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; - If gsview is installed in a different directory, you will need - to make the appropriate change. Note the combination of single - and double quotes around the name. The single quotes specify - that this is a string to be assigned to the configuration vari- - able $lpr. The double quotes are part of the string passed to - the operating system to get the command obeyed; this is neces- + If gsview is installed in a different directory, you will need + to make the appropriate change. Note the combination of single + and double quotes around the name. The single quotes specify + that this is a string to be assigned to the configuration vari- + able $lpr. The double quotes are part of the string passed to + the operating system to get the command obeyed; this is neces- sary because one part of the command name ("Program Files") con- tains a space which would otherwise be misinterpreted. @@ -3744,20 +3744,20 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $lpr_pdf ["NONE lpr_pdf"] The printing program to print pdf files. - Under MS-Windows you could set this to use gsview, if it is in- + Under MS-Windows you could set this to use gsview, if it is in- stalled, e.g., $lpr = '"c:/Program Files/Ghostgum/gsview/gsview32.exe" /p'; - If gsview is installed in a different directory, you will need - to make the appropriate change. Note the double quotes around + If gsview is installed in a different directory, you will need + to make the appropriate change. Note the double quotes around the name: this is necessary because one part of the command name ("Program Files") contains a space which would otherwise be mis- interpreted. - 10 January 2024 57 + 31 January 2024 57 @@ -3768,35 +3768,35 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $lualatex ["lualatex %O %S"] Specifies the command line for the LaTeX processing program that - is to be used when the lualatex program is called for (e.g., by + is to be used when the lualatex program is called for (e.g., by the option -lualatex. - To do a coordinated setting of all of $dvilualatex, $hilatex, + To do a coordinated setting of all of $dvilualatex, $hilatex, $latex, $pdflatex, $lualatex, and $xelatex, see the section "Ad- vanced Configuration". %lualatex_input_extensions - This variable specifies the extensions tried by latexmk when it - finds that a lualatex run resulted in an error that a file has - not been found, and the file is given without an extension. - This typically happens when LaTeX commands of the form \in- - put{file} or \includegraphics{figure}, when the relevant source + This variable specifies the extensions tried by latexmk when it + finds that a lualatex run resulted in an error that a file has + not been found, and the file is given without an extension. + This typically happens when LaTeX commands of the form \in- + put{file} or \includegraphics{figure}, when the relevant source file does not exist. - In this situation, latexmk searches for custom dependencies to - make the missing file(s), but restricts it to the extensions - specified by the variable %pdflatex_input_extensions. The de- + In this situation, latexmk searches for custom dependencies to + make the missing file(s), but restricts it to the extensions + specified by the variable %pdflatex_input_extensions. The de- fault extensions are 'tex', 'pdf', 'jpg, and 'png'. See details of the %latex_input_extensions for other information that equally applies to %lualatex_input_extensions. $lualatex_silent_switch ["-interaction=batchmode"] - Switch(es) for the lualatex program (specified in the variable + Switch(es) for the lualatex program (specified in the variable $lualatex) when silent mode is on. - See details of the $latex_silent_switch for other information + See details of the $latex_silent_switch for other information that equally applies to $lualatex_silent_switch. $make ["make"] @@ -3806,24 +3806,24 @@ LATEXMK(1) General Commands Manual LATEXMK(1) The index processing program. $makeindex_fudge [0] - When using makeindex, whether to change directory to $aux_dir - before running makeindex. Set to 1 if $aux_dir is not an ex- - plicit subdirectory of current directory, otherwise makeindex + When using makeindex, whether to change directory to $aux_dir + before running makeindex. Set to 1 if $aux_dir is not an ex- + plicit subdirectory of current directory, otherwise makeindex will refuse to write its output and log files, for security rea- sons. $makeindex_silent_switch ["-q"] - Switch(es) for the index processing program when silent mode is + Switch(es) for the index processing program when silent mode is on. $max_repeat [5] - The maximum number of times latexmk will run *latex before de- - ciding that there may be an infinite loop and that it needs to - bail out, rather than rerunning *latex again to resolve cross- + The maximum number of times latexmk will run *latex before de- + ciding that there may be an infinite loop and that it needs to + bail out, rather than rerunning *latex again to resolve cross- - 10 January 2024 58 + 31 January 2024 58 @@ -3838,58 +3838,58 @@ LATEXMK(1) General Commands Manual LATEXMK(1) tex generates files to be read in on a later run.) $MSWin_back_slash [1] - This configuration variable only has an effect when latexmk is - running under MS-Windows. With the default value of 1 for this - variable, when a command is executed under MS-Windows, latexmk - substitutes "\" for the separator character between components - of a directory name. Internally, latexmk uses "/" for the di- - rectory separator character, which is the character used by + This configuration variable only has an effect when latexmk is + running under MS-Windows. With the default value of 1 for this + variable, when a command is executed under MS-Windows, latexmk + substitutes "\" for the separator character between components + of a directory name. Internally, latexmk uses "/" for the di- + rectory separator character, which is the character used by Unix-like systems. - For almost all programs and for almost all filenames under MS- - Windows, both "\" and "/" are acceptable as the directory sepa- - rator character, provided at least that filenames are properly + For almost all programs and for almost all filenames under MS- + Windows, both "\" and "/" are acceptable as the directory sepa- + rator character, provided at least that filenames are properly quoted. But it is possible that programs exist that only accept - "\" on the command line, since that is the standard directory - separator for MS-Windows. So for safety latexmk makes the sub- + "\" on the command line, since that is the standard directory + separator for MS-Windows. So for safety latexmk makes the sub- stitution from "/" to "\", by default. - However there are also programs on MS-Windows for which a back + However there are also programs on MS-Windows for which a back slash "\" is interpreted differently than as a directory separa- - tor; for these the directory separator should be "/". Programs - with this behavior include all the *latex programs in the - TeXLive implementation (but not the MiKTeX implementation). - Hence if you use TeXLive on MS-Windows, then $MSWin_back_slash + tor; for these the directory separator should be "/". Programs + with this behavior include all the *latex programs in the + TeXLive implementation (but not the MiKTeX implementation). + Hence if you use TeXLive on MS-Windows, then $MSWin_back_slash should be set to zero. $new_viewer_always [0] - This variable applies to latexmk only in continuous-preview + This variable applies to latexmk only in continuous-preview mode. If $new_viewer_always is 0, latexmk will check for a pre- - viously running previewer on the same file, and if one is run- - ning will not start a new one. If $new_viewer_always is non- - zero, this check will be skipped, and latexmk will behave as if + viously running previewer on the same file, and if one is run- + ning will not start a new one. If $new_viewer_always is non- + zero, this check will be skipped, and latexmk will behave as if no viewer is running. $out_dir [""] If non-blank, this variable specifies the output directory. - This is the directory in which final output files are written - (dvi, ps, pdf, synctex, synctex.gz). In addition, if the aux - directory equals the output directory, as is the case by de- - fault, then other generated files are in effect written to the + This is the directory in which final output files are written + (dvi, ps, pdf, synctex, synctex.gz). In addition, if the aux + directory equals the output directory, as is the case by de- + fault, then other generated files are in effect written to the output directory. If $out_dir is blank, the output directory is the current direc- - tory at the invocation of *latex; this is equivalent to setting + tory at the invocation of *latex; this is equivalent to setting $out_dir to '.'. - See the section AUXILIARY AND OUTPUT DIRECTORIES for more de- + See the section AUXILIARY AND OUTPUT DIRECTORIES for more de- tails. - 10 January 2024 59 + 31 January 2024 59 @@ -3899,21 +3899,21 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $pdf_mode [0] - If zero, do NOT generate a pdf version of the document. If - equal to 1, generate a pdf version of the document using pdfla- - tex, using the command specified by the $pdflatex variable. If - equal to 2, generate a pdf version of the document from the ps - file, by using the command specified by the $ps2pdf variable. - If equal to 3, generate a pdf version of the document from the - dvi file, by using the command specified by the $dvipdf vari- + If zero, do NOT generate a pdf version of the document. If + equal to 1, generate a pdf version of the document using pdfla- + tex, using the command specified by the $pdflatex variable. If + equal to 2, generate a pdf version of the document from the ps + file, by using the command specified by the $ps2pdf variable. + If equal to 3, generate a pdf version of the document from the + dvi file, by using the command specified by the $dvipdf vari- able. If equal to 4, generate a pdf version of the document us- ing lualatex, using the command specified by the $lualatex vari- - able. If equal to 5, generate a pdf version (and an xdv ver- - sion) of the document using xelatex, using the commands speci- + able. If equal to 5, generate a pdf version (and an xdv ver- + sion) of the document using xelatex, using the commands speci- fied by the $xelatex and xdvipdfmx variables. - In $pdf_mode=2, it is ensured that .dvi and .ps files are also - made. In $pdf_mode=3, it is ensured that a .dvi file is also + In $pdf_mode=2, it is ensured that .dvi and .ps files are also + made. In $pdf_mode=3, it is ensured that a .dvi file is also made. But this may be overridden by the document. $pdflatex ["pdflatex %O %S"] @@ -3925,28 +3925,28 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $pdflatex = "pdflatex --shell-escape %O %S"; - (In some earlier versions of latexmk, you needed to use an as- - signment to $pdflatex to allow the use of lualatex or xelatex + (In some earlier versions of latexmk, you needed to use an as- + signment to $pdflatex to allow the use of lualatex or xelatex instead of pdflatex. There are now separate configuration vari- - ables for the use of lualatex or xelatex. See $lualatex and + ables for the use of lualatex or xelatex. See $lualatex and $xelatex.) - To do a coordinated setting of all of $dvilualatex, $hilatex, + To do a coordinated setting of all of $dvilualatex, $hilatex, $latex, $pdflatex, $lualatex, and $xelatex, see the section "Ad- vanced Configuration". %pdflatex_input_extensions - This variable specifies the extensions tried by latexmk when it - finds that a pdflatex run resulted in an error that a file has - not been found, and the file is given without an extension. - This typically happens when LaTeX commands of the form \in- - put{file} or \includegraphics{figure}, when the relevant source + This variable specifies the extensions tried by latexmk when it + finds that a pdflatex run resulted in an error that a file has + not been found, and the file is given without an extension. + This typically happens when LaTeX commands of the form \in- + put{file} or \includegraphics{figure}, when the relevant source file does not exist. - In this situation, latexmk searches for custom dependencies to - make the missing file(s), but restricts it to the extensions - specified by the variable %pdflatex_input_extensions. The de- + In this situation, latexmk searches for custom dependencies to + make the missing file(s), but restricts it to the extensions + specified by the variable %pdflatex_input_extensions. The de- fault extensions are 'tex', 'pdf', 'jpg, and 'png'. See details of the %latex_input_extensions for other information @@ -3955,7 +3955,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 60 + 31 January 2024 60 @@ -3965,55 +3965,55 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $pdflatex_silent_switch ["-interaction=batchmode"] - Switch(es) for the pdflatex program (specified in the variable + Switch(es) for the pdflatex program (specified in the variable $pdflatex) when silent mode is on. - See details of the $latex_silent_switch for other information + See details of the $latex_silent_switch for other information that equally applies to $pdflatex_silent_switch. $pdf_previewer ["start acroread %O %S"] The command to invoke a pdf-previewer. - On MS-Windows, the default is changed to "cmd /c start """; un- - der more recent versions of Windows, this will cause to be run + On MS-Windows, the default is changed to "cmd /c start """; un- + der more recent versions of Windows, this will cause to be run whatever command the system has associated with .pdf files. But - this may be undesirable if this association is to acroread -- + this may be undesirable if this association is to acroread -- see the notes in the explanation of the -pvc option.] - On OS-X the default is changed to "open %S", which results in - OS-X starting up (and detaching) the viewer associated with the - file. By default, for pdf files this association is to OS-X's + On OS-X the default is changed to "open %S", which results in + OS-X starting up (and detaching) the viewer associated with the + file. By default, for pdf files this association is to OS-X's preview, which is quite satisfactory. - WARNING: Problem under MS-Windows: if acroread is used as the - pdf previewer, and it is actually viewing a pdf file, the pdf - file cannot be updated. Thus makes acroread a bad choice of - previewer if you use latexmk's previous-continuous mode (option + WARNING: Problem under MS-Windows: if acroread is used as the + pdf previewer, and it is actually viewing a pdf file, the pdf + file cannot be updated. Thus makes acroread a bad choice of + previewer if you use latexmk's previous-continuous mode (option -pvc) under MS-windows. This problem does not occur if, for ex- ample, SumatraPDF or gsview is used to view pdf files. - Important note: Normally you will want to have a previewer run + Important note: Normally you will want to have a previewer run detached, so that latexmk doesn't wait for the previewer to ter- - minate before continuing its work. So normally you should pre- - fix the command by "start ", which flags to latexmk that it - should do the detaching of the previewer itself (by whatever - method is appropriate to the operating system). But sometimes + minate before continuing its work. So normally you should pre- + fix the command by "start ", which flags to latexmk that it + should do the detaching of the previewer itself (by whatever + method is appropriate to the operating system). But sometimes letting latexmk do the detaching is not appropriate (for a vari- - ety of non-trivial reasons), so you should put the "start " bit + ety of non-trivial reasons), so you should put the "start " bit in yourself, whenever it is needed. $pdf_update_command [""] - When the pdf previewer is set to be updated by running a com- - mand, this is the command that is run. See the information for + When the pdf previewer is set to be updated by running a com- + mand, this is the command that is run. See the information for the variable $pdf_update_method. $pdf_update_method [1 under UNIX, 3 under MS-Windows] - How the pdf viewer updates its display when the pdf file has - changed. See the information on the variable $dvi_update_method + How the pdf viewer updates its display when the pdf file has + changed. See the information on the variable $dvi_update_method for the codes. (Note that information needs be changed slightly - so that for the value 4, to run a command to do the update, the - command is specified by the variable $pdf_update_command, and - for the value 2, to specify update by signal, the signal is + so that for the value 4, to run a command to do the update, the + command is specified by the variable $pdf_update_command, and + for the value 2, to specify update by signal, the signal is specified by $pdf_update_signal.) Note that acroread under MS-Windows (but not UNIX) locks the pdf @@ -4021,7 +4021,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 61 + 31 January 2024 61 @@ -4037,47 +4037,47 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $pdf_update_method = 4; $pdf_update_command = "xpdf -remote %R -reload"; - The first setting arranges for the xpdf program to be used in - its "remote server mode", with the server name specified as the - rootname of the TeX file. The second setting arranges for up- - dating to be done in response to a command, and the third set- + The first setting arranges for the xpdf program to be used in + its "remote server mode", with the server name specified as the + rootname of the TeX file. The second setting arranges for up- + dating to be done in response to a command, and the third set- ting sets the update command. $pdf_update_signal [Under UNIX: SIGHUP, which is a system-dependent value] - The number of the signal that is sent to the pdf viewer when it - is updated by sending a signal -- see the information on the - variable $pdf_update_method. The default value is the one ap- + The number of the signal that is sent to the pdf viewer when it + is updated by sending a signal -- see the information on the + variable $pdf_update_method. The default value is the one ap- propriate for gv on a UNIX system. $pid_position[1 under UNIX, -1 under MS-Windows] - The variable $pid_position is used to specify which word in - lines of the output from $pscmd corresponds to the process ID. - The first word in the line is numbered 0. The default value of + The variable $pid_position is used to specify which word in + lines of the output from $pscmd corresponds to the process ID. + The first word in the line is numbered 0. The default value of 1 (2nd word in line) is correct for Solaris 2.6, Linux, and OS-X with their default settings of $pscmd. - Setting the variable to -1 is used to indicate that $pscmd is + Setting the variable to -1 is used to indicate that $pscmd is not to be used. $postscript_mode [0] - If nonzero, generate a postscript version of the document. + If nonzero, generate a postscript version of the document. Equivalent to the -ps option. - If some other request is made for which a postscript file is + If some other request is made for which a postscript file is needed, then $postscript_mode will be set to 1. $pre_tex_code [''] - Sets TeX code to be executed before inputting the source file. - This works if the relevant one of $latex, etc contains a suit- + Sets TeX code to be executed before inputting the source file. + This works if the relevant one of $latex, etc contains a suit- able command line with a %P or %U substitution. For example you could do $latex = 'latex %O %P'; $pre_tex_code = '\AtBeginDocument{An initial message\par}'; - To set all of $latex, $pdflatex, $lualatex, and $xelatex you + To set all of $latex, $pdflatex, $lualatex, and $xelatex you could use the subroutine alt_tex_cmds: &alt_tex_cmds; @@ -4087,7 +4087,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 62 + 31 January 2024 62 @@ -4097,41 +4097,41 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $preview_continuous_mode [0] - If nonzero, run a previewer to view the document, and continue + If nonzero, run a previewer to view the document, and continue running latexmk to keep .dvi up-to-date. Equivalent to the -pvc - option. Which previewer is run depends on the other settings, + option. Which previewer is run depends on the other settings, see the command line options -view=, and the variable $view. $preview_mode [0] If nonzero, run a previewer to preview the document. Equivalent - to the -pv option. Which previewer is run depends on the other - settings, see the command line options -view=, and the variable + to the -pv option. Which previewer is run depends on the other + settings, see the command line options -view=, and the variable $view. $printout_mode [0] - If nonzero, print the document using the command specified in + If nonzero, print the document using the command specified in the $lpr variable. Equivalent to the -p option. This is recom- - mended not to be set from an RC file, otherwise you could waste + mended not to be set from an RC file, otherwise you could waste lots of paper. $print_type = ["auto"] - Type of file to printout: possibilities are "auto", "dvi", + Type of file to printout: possibilities are "auto", "dvi", "none", "pdf", or "ps". See the option -print= for the meaning of the "auto" value. $pscmd Command used to get all the processes currently run by the user. - The -pvc option uses the command specified by the variable - $pscmd to determine if there is an already running previewer, - and to find the process ID (needed if latexmk needs to signal + The -pvc option uses the command specified by the variable + $pscmd to determine if there is an already running previewer, + and to find the process ID (needed if latexmk needs to signal the previewer about file changes). Each line of the output of this command is assumed to correspond - to one process. See the $pid_position variable for how the + to one process. See the $pid_position variable for how the process number is determined. - The default for pscmd is "NONE" under MS-Windows and cygwin - (i.e., the command is not used), "ps -ww -u $ENV{USER}" under - OS-X, and "ps -f -u $ENV{USER}" under other operating systems + The default for pscmd is "NONE" under MS-Windows and cygwin + (i.e., the command is not used), "ps -ww -u $ENV{USER}" under + OS-X, and "ps -f -u $ENV{USER}" under other operating systems (including Linux). In these specifications "$ENV{USER}" is sub- stituted by the username. @@ -4140,20 +4140,20 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $ps_filter [empty] The postscript file filter to be run on the newly produced post- - script file before other processing. Equivalent to specifying + script file before other processing. Equivalent to specifying the -pF option. $ps_previewer ["start gv %O %S", but start %O %S under MS-Windows] - The command to invoke a ps-previewer. (The default under MS- + The command to invoke a ps-previewer. (The default under MS- Windows will cause to be run whatever command the system has as- sociated with .ps files.) - Note that gv could be used with the -watch option updates its - display whenever the postscript file changes, whereas ghostview + Note that gv could be used with the -watch option updates its + display whenever the postscript file changes, whereas ghostview - 10 January 2024 63 + 31 January 2024 63 @@ -4162,22 +4162,22 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - does not. However, different versions of gv have slightly dif- - ferent ways of writing this option. You can configure this + does not. However, different versions of gv have slightly dif- + ferent ways of writing this option. You can configure this variable appropriately. WARNING: Linux systems may have installed one (or more) versions - of gv under different names, e.g., ggv, kghostview, etc, but + of gv under different names, e.g., ggv, kghostview, etc, but perhaps not one actually called gv. - Important note: Normally you will want to have a previewer run + Important note: Normally you will want to have a previewer run detached, so that latexmk doesn't wait for the previewer to ter- - minate before continuing its work. So normally you should pre- - fix the command by "start ", which flags to latexmk that it - should do the detaching of the previewer itself (by whatever - method is appropriate to the operating system). But sometimes + minate before continuing its work. So normally you should pre- + fix the command by "start ", which flags to latexmk that it + should do the detaching of the previewer itself (by whatever + method is appropriate to the operating system). But sometimes letting latexmk do the detaching is not appropriate (for a vari- - ety of non-trivial reasons), so you should put the "start " bit + ety of non-trivial reasons), so you should put the "start " bit in yourself, whenever it is needed. @@ -4186,29 +4186,29 @@ LATEXMK(1) General Commands Manual LATEXMK(1) The command to invoke a ps-previewer in landscape mode. $ps_update_command [""] - When the postscript previewer is set to be updated by running a - command, this is the command that is run. See the information + When the postscript previewer is set to be updated by running a + command, this is the command that is run. See the information for the variable $ps_update_method. $ps_update_method [0 under UNIX, 1 under MS-Windows] - How the postscript viewer updates its display when the .ps file - has changed. See the information on the variable $dvi_up- - date_method for the codes. (Note that information needs be + How the postscript viewer updates its display when the .ps file + has changed. See the information on the variable $dvi_up- + date_method for the codes. (Note that information needs be changed slightly so that for the value 4, to run a command to do - the update, the command is specified by the variable $ps_up- - date_command, and for the value 2, to specify update by signal, + the update, the command is specified by the variable $ps_up- + date_command, and for the value 2, to specify update by signal, the signal is specified by $ps_update_signal.) $ps_update_signal [Under UNIX: SIGHUP, which is a system-dependent value] - The number of the signal that is sent to the pdf viewer when it - is updated by sending a signal -- see $ps_update_method. The + The number of the signal that is sent to the pdf viewer when it + is updated by sending a signal -- see $ps_update_method. The default value is the one appropriate for gv on a UNIX system. $pvc_timeout [0] - If this variable is nonzero, there will be a timeout in pvc - mode after a period of inactivity. Inactivity means a period - when latexmk has detected no file changes and hence has not + If this variable is nonzero, there will be a timeout in pvc + mode after a period of inactivity. Inactivity means a period + when latexmk has detected no file changes and hence has not taken any actions like compiling the document. The period of in- activity is in the variable $pvc_timeout_mins. @@ -4219,7 +4219,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 64 + 31 January 2024 64 @@ -4235,57 +4235,57 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $quote_filenames [1] This specifies whether substitutions for placeholders in command specifications (as in $pdflatex) are surrounded by double - quotes. If this variable is 1 (or any other value Perl regards + quotes. If this variable is 1 (or any other value Perl regards as true), then quoting is done. Otherwise quoting is omitted. - The quoting method used by latexmk is tested to work correctly - under UNIX systems (including Linux and Mac OS-X) and under MS- - Windows. It allows the use of filenames containing special - characters, notably spaces. (But note that many versions of - *latex cannot correctly deal with TeX files whose names contain - spaces. Latexmk's quoting only ensures that such filenames are - correctly treated by the operating system in passing arguments + The quoting method used by latexmk is tested to work correctly + under UNIX systems (including Linux and Mac OS-X) and under MS- + Windows. It allows the use of filenames containing special + characters, notably spaces. (But note that many versions of + *latex cannot correctly deal with TeX files whose names contain + spaces. Latexmk's quoting only ensures that such filenames are + correctly treated by the operating system in passing arguments to programs.) $rc_report [1] - After initialization, whether to give a list of the RC files + After initialization, whether to give a list of the RC files read. $recorder [1] - Whether to use the -recorder option to *latex. Use of this op- - tion results in a file of extension .fls containing a list of - the files that these programs have read and written. Latexmk + Whether to use the -recorder option to *latex. Use of this op- + tion results in a file of extension .fls containing a list of + the files that these programs have read and written. Latexmk will then use this file to improve its detection of source files and generated files after a run of *latex. - It is generally recommended to use this option (or to configure - the $recorder variable to be on.) But it only works if *latex - supports the -recorder option, which is true for most current + It is generally recommended to use this option (or to configure + the $recorder variable to be on.) But it only works if *latex + supports the -recorder option, which is true for most current implementations - Note about the name of the .fls file: Most implementations of - *latex produce an .fls file with the same basename as the main + Note about the name of the .fls file: Most implementations of + *latex produce an .fls file with the same basename as the main document's LaTeX, e.g., for Document.tex, the .fls file is Docu- - ment.fls. However, some implementations instead produce files + ment.fls. However, some implementations instead produce files named for the program, i.e., latex.fls or pdflatex.fls. In this - second case, latexmk copies the latex.fls or pdflatex.fls to a - file with the basename of the main LaTeX document, e.g., Docu- + second case, latexmk copies the latex.fls or pdflatex.fls to a + file with the basename of the main LaTeX document, e.g., Docu- ment.fls. $search_path_separator [See below for default] The character separating paths in the environment variables TEX- - INPUTS, BIBINPUTS, and BSTINPUTS. This variable is mainly used - by latexmk when the -outdir, -output-directory, -auxdir, and/or - -aux-directory options are used. In that case latexmk needs to + INPUTS, BIBINPUTS, and BSTINPUTS. This variable is mainly used + by latexmk when the -outdir, -output-directory, -auxdir, and/or + -aux-directory options are used. In that case latexmk needs to communicate appropriately modified search paths to bibtex, dvipdf, dvips, and *latex. - [Comment to technically savvy readers: *latex doesn't actually - need the modified search path. But, surprisingly, dvipdf and + [Comment to technically savvy readers: *latex doesn't actually + need the modified search path. But, surprisingly, dvipdf and - 10 January 2024 65 + 31 January 2024 65 @@ -4294,25 +4294,25 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - dvips do, because sometimes graphics files get generated in the + dvips do, because sometimes graphics files get generated in the output or aux directories.] - The default under MSWin and Cygwin is ';' and under UNIX-like - operating systems (including Linux and OS-X) is ':'. Normally - the defaults give correct behavior. But there can be difficul- - ties if your operating system is of one kind, but some of your - software is running under an emulator for the other kind of op- - erating system; in that case you'll need to find out what is - needed, and set $search_path_separator explicitly. (The same - goes, of course, for unusual operating systems that are not in + The default under MSWin and Cygwin is ';' and under UNIX-like + operating systems (including Linux and OS-X) is ':'. Normally + the defaults give correct behavior. But there can be difficul- + ties if your operating system is of one kind, but some of your + software is running under an emulator for the other kind of op- + erating system; in that case you'll need to find out what is + needed, and set $search_path_separator explicitly. (The same + goes, of course, for unusual operating systems that are not in the MSWin, Linux, OS-X, Unix collection.) $show_time [0] - Whether to show time used, both the total and for individual + Whether to show time used, both the total and for individual steps. Note: On MS Windows, this is clock time. On other OSs it is the - CPU time used (by latexmk and the child processes it invokes). + CPU time used (by latexmk and the child processes it invokes). The OS-dependence is because of a limitation of Windows. If you wish to force the use of clock instead of CPU time, you can set @@ -4321,37 +4321,37 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $silence_logfile_warnings [0] - Whether after a run of *latex to summarize warnings in the log - file about undefined citations and references. Setting $si- + Whether after a run of *latex to summarize warnings in the log + file about undefined citations and references. Setting $si- lence_logfile_warnings=0 gives the summary of warnings (provided - silent mode isn't also set), and this is useful to locate unde- - fined citations and references without searching through the - much more verbose log file or the screen output of *latex. But - the summary can also be excessively annoying. The default is - not to give these warnings. The command line options -si- - lence_logfile_warning_list and -silence_logfile_warning_list- + silent mode isn't also set), and this is useful to locate unde- + fined citations and references without searching through the + much more verbose log file or the screen output of *latex. But + the summary can also be excessively annoying. The default is + not to give these warnings. The command line options -si- + lence_logfile_warning_list and -silence_logfile_warning_list- also set this variable. - Note that multiple occurrences for the same undefined object on + Note that multiple occurrences for the same undefined object on the same page and same line will be compressed to a single warn- ing. $silent [0] - Whether to run silently. Setting $silent to 1 has the same ef- + Whether to run silently. Setting $silent to 1 has the same ef- fect as the -quiet of -silent options on the command line. $sleep_time [2] - The time to sleep (in seconds) between checking for source-file - changes when running with the -pvc option. If non-zero, it is + The time to sleep (in seconds) between checking for source-file + changes when running with the -pvc option. If non-zero, it is subject to a minimum value give by the $min_sleep_time variable. But a zero value is also allowed. - 10 January 2024 66 + 31 January 2024 66 @@ -4360,24 +4360,24 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - A value of exactly 0 gives no delay between checks for source- - file changes; it typically results in 100% CPU usage, which may + A value of exactly 0 gives no delay between checks for source- + file changes; it typically results in 100% CPU usage, which may not be desirable. - In old versions of latexmk, the default value of $sleep_time of - 2 wB-pvctmodegand theeamountlofcCPUrusage.beOnemodernpocomputers + In old versions of latexmk, the default value of $sleep_time of + 2 waB-pvc modeiandatheaamounteofoCPUousage.etOnemodernocomputers in - with fast multi-core CPUs, a smaller value, e.g., 0.1 can give + with fast multi-core CPUs, a smaller value, e.g., 0.1 can give good results, especially when working with small documents whose compilation may take well under a second. $texfile_search [""] - This is an obsolete variable, replaced by the @default_files + This is an obsolete variable, replaced by the @default_files variable. - For backward compatibility, if you choose to set $tex- - file_search, it is a string of space-separated filenames, and + For backward compatibility, if you choose to set $tex- + file_search, it is a string of space-separated filenames, and then latexmk replaces @default_files with the filenames in $tex- file_search to which is added "*.tex". @@ -4385,39 +4385,39 @@ LATEXMK(1) General Commands Manual LATEXMK(1) See the documentation for $compiling_cmd. $tmpdir [See below for default] - Directory to store temporary files that latexmk may generate + Directory to store temporary files that latexmk may generate while running. - The default under MSWindows (including cygwin), is to set $tm- - pdir to the value of the first of whichever of the system envi- - ronment variables TMPDIR or TEMP exists, otherwise to the cur- - rent directory. Under other operating systems (expected to be - UNIX/Linux, including OS-X), the default is the value of the - system environment variable TMPDIR if it exists, otherwise + The default under MSWindows (including cygwin), is to set $tm- + pdir to the value of the first of whichever of the system envi- + ronment variables TMPDIR or TEMP exists, otherwise to the cur- + rent directory. Under other operating systems (expected to be + UNIX/Linux, including OS-X), the default is the value of the + system environment variable TMPDIR if it exists, otherwise "/tmp". $use_make_for_missing_files [0] Whether to use make to try and make files that are missing after - a run of *latex, and for which a custom dependency has not been - found. This is generally useful only when latexmk is used as - part of a bigger project which is built by using the make pro- + a run of *latex, and for which a custom dependency has not been + found. This is generally useful only when latexmk is used as + part of a bigger project which is built by using the make pro- gram. Note that once a missing file has been made, no further calls to - make will be made on a subsequent run of latexmk to update the - file. Handling this problem is the job of a suitably defined - Makefile. See the section "USING latexmk WITH make" for how to - do this. The intent of calling make from latexmk is merely to + make will be made on a subsequent run of latexmk to update the + file. Handling this problem is the job of a suitably defined + Makefile. See the section "USING latexmk WITH make" for how to + do this. The intent of calling make from latexmk is merely to detect dependencies. $view ["default"] - Which kind of file is to be previewed if a previewer is used. - The possible values are "default", "dvi", "ps", "pdf". The + Which kind of file is to be previewed if a previewer is used. + The possible values are "default", "dvi", "ps", "pdf". The value of "default" means that the "highest" of the kinds of file - 10 January 2024 67 + 31 January 2024 67 @@ -4430,60 +4430,60 @@ LATEXMK(1) General Commands Manual LATEXMK(1) $warnings_as_errors [0] - Normally latexmk copies the behavior of latex in treating unde- - fined references and citations and multiply defined references - as conditions that give a warning but not an error. The vari- + Normally latexmk copies the behavior of latex in treating unde- + fined references and citations and multiply defined references + as conditions that give a warning but not an error. The vari- able $warnings_as_errors controls whether this behavior is modi- fied. - When the variable is non-zero, latexmk at the end of its run - will return a non-zero status code to the operating system if - any of the files processed gives a warning about problems with + When the variable is non-zero, latexmk at the end of its run + will return a non-zero status code to the operating system if + any of the files processed gives a warning about problems with citations or references (i.e., undefined citations or references or multiply defined references). This is after latexmk has com- - pleted all the runs it needs to try and resolve references and - citations. Thus $warnings_as_errors being nonzero causes la- + pleted all the runs it needs to try and resolve references and + citations. Thus $warnings_as_errors being nonzero causes la- texmk to treat such warnings as errors, but only when they occur on the last run of *latex and only after processing is complete. - A non-zero value $warnings_as_errors can be set by the command- + A non-zero value $warnings_as_errors can be set by the command- line option -Werror. The default behavior is normally satisfactory in the usual edit- - compile-edit cycle. But, for example, latexmk can also be used - as part of a build process for some bigger project, e.g., for - creating documentation in the build of a software application. - Then it is often sensible to treat citation and reference warn- - ings as errors that require the overall build process to be + compile-edit cycle. But, for example, latexmk can also be used + as part of a build process for some bigger project, e.g., for + creating documentation in the build of a software application. + Then it is often sensible to treat citation and reference warn- + ings as errors that require the overall build process to be aborted. Of course, since multiple runs of *latex are generally - needed to resolve references and citations, what matters is not + needed to resolve references and citations, what matters is not the warnings on the first run, but the warnings on the last run; latexmk takes this into account appropriately. - In addition, when preview-continuous mode is used, a non-zero - value for $warnings_as_errors changes the use of the commands - $failure_cmd, $warning_cmd, and $success_cmd after a complia- + In addition, when preview-continuous mode is used, a non-zero + value for $warnings_as_errors changes the use of the commands + $failure_cmd, $warning_cmd, and $success_cmd after a complia- tion. If there are citation or reference warnings, but no other - errors, the behavior is as follows. If $warning_cmd is set, it - is used. If it is not set, then then if $warnings_as_errors is - non-zero and $failure_cmd is set, then $failure_cmd. Otherwise - $success_cmd is used, if it is set. (The foregoing explanation + errors, the behavior is as follows. If $warning_cmd is set, it + is used. If it is not set, then then if $warnings_as_errors is + non-zero and $failure_cmd is set, then $failure_cmd. Otherwise + $success_cmd is used, if it is set. (The foregoing explanation is rather complicated, because latexmk has to deal with the case that one or more of the commands isn't set.) $xdv_mode [0] - If one, generate an xdv version of the document by use of xela- + If one, generate an xdv version of the document by use of xela- tex. $xdvipdfmx ["xdvipdfmx -E -o %D %O %S"] - The program to make a pdf file from an xdv file (used in con- + The program to make a pdf file from an xdv file (used in con- junction with xelatex when $pdf_mode=5). - 10 January 2024 68 + 31 January 2024 68 @@ -4496,60 +4496,60 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Switch(es) for the xdvipdfmx program when silent mode is on. $xelatex ["xelatex %O %S"] - Specifies the command line for the LaTeX processing program of - when the xelatex program is called for. See the documentation - of the -xelatex option for some special properties of latexmk's + Specifies the command line for the LaTeX processing program of + when the xelatex program is called for. See the documentation + of the -xelatex option for some special properties of latexmk's use of xelatex. - Note about xelatex: latexmk uses xelatex to make an .xdv rather - than .pdf file, with the .pdf file being created in a separate + Note about xelatex: latexmk uses xelatex to make an .xdv rather + than .pdf file, with the .pdf file being created in a separate step. This is enforced by the use of the -no-pdf option. If %O - is part of the command for invoking xelatex, then latexmk will + is part of the command for invoking xelatex, then latexmk will insert the -no-pdf option automatically, otherwise you must pro- - vide the option yourself. See the documentation for the -pdfxe + vide the option yourself. See the documentation for the -pdfxe option for why latexmk makes a .xdv file rather than a .pdf file when xelatex is used. - To do a coordinated setting of all of $dvilualatex, $hilatex, + To do a coordinated setting of all of $dvilualatex, $hilatex, $latex, $pdflatex, $lualatex, and $xelatex, see the section "Ad- vanced Configuration". %xelatex_input_extensions - This variable specifies the extensions tried by latexmk when it - finds that an xelatex run resulted in an error that a file has - not been found, and the file is given without an extension. - This typically happens when LaTeX commands of the form \in- - put{file} or \includegraphics{figure}, when the relevant source + This variable specifies the extensions tried by latexmk when it + finds that an xelatex run resulted in an error that a file has + not been found, and the file is given without an extension. + This typically happens when LaTeX commands of the form \in- + put{file} or \includegraphics{figure}, when the relevant source file does not exist. - In this situation, latexmk searches for custom dependencies to - make the missing file(s), but restricts it to the extensions - specified by the variable %xelatex_input_extensions. The de- + In this situation, latexmk searches for custom dependencies to + make the missing file(s), but restricts it to the extensions + specified by the variable %xelatex_input_extensions. The de- fault extensions are 'tex', 'pdf', 'jpg, and 'png'. See details of the %latex_input_extensions for other information that equally applies to %xelatex_input_extensions. $xelatex_silent_switch ["-interaction=batchmode"] - Switch(es) for the xelatex program (specified in the variable + Switch(es) for the xelatex program (specified in the variable $xelatex) when silent mode is on. - See details of the $latex_silent_switch for other information + See details of the $latex_silent_switch for other information that equally applies to $xelatex_silent_switch. CUSTOM DEPENDENCIES - In any RC file a set of custom dependencies can be set up to convert a + In any RC file a set of custom dependencies can be set up to convert a file with one extension to a file with another. An example use of this would be to allow latexmk to convert a .fig file to .eps to be included in the .tex file. - 10 January 2024 69 + 31 January 2024 69 @@ -4560,9 +4560,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Defining a custom dependency: The old method of configuring latexmk to use a custom dependency was to - directly manipulate the @cus_dep_list array that contains information - defining the custom dependencies. (See the section "Old Method of - Defining Custom Dependencies" for details.) This method still works, + directly manipulate the @cus_dep_list array that contains information + defining the custom dependencies. (See the section "Old Method of + Defining Custom Dependencies" for details.) This method still works, but is no longer preferred. A better method is to use the subroutines that allow convenient manipu- @@ -4575,47 +4575,47 @@ LATEXMK(1) General Commands Manual LATEXMK(1) The arguments are as follows: from extension: - The extension of the file we are converting from (e.g. "fig"). + The extension of the file we are converting from (e.g. "fig"). It is specified without a period. to extension: The extension of the file we are converting to (e.g. "eps"). It is specified without a period. - must: If non-zero, the file from which we are converting must exist, - if it doesn't exist latexmk will give an error message and exit + must: If non-zero, the file from which we are converting must exist, + if it doesn't exist latexmk will give an error message and exit unless the -f option is specified. If must is zero and the file - we are converting from doesn't exist, then no action is taken. + we are converting from doesn't exist, then no action is taken. Generally, the appropriate value of must is zero. function: - The name of the subroutine that latexmk should call to perform - the file conversion. The first argument to the subroutine is + The name of the subroutine that latexmk should call to perform + the file conversion. The first argument to the subroutine is the base name of the file to be converted without any extension. - The subroutines are declared in the syntax of Perl. The func- - tion should return 0 if it was successful and a nonzero number + The subroutines are declared in the syntax of Perl. The func- + tion should return 0 if it was successful and a nonzero number if it failed. - Naturally add_cus_dep adds a custom dependency with the specified from - and to extensions. If a custom dependency has been previously defined - (e.g., in an rcfile that was read earlier), then it is replaced by the + Naturally add_cus_dep adds a custom dependency with the specified from + and to extensions. If a custom dependency has been previously defined + (e.g., in an rcfile that was read earlier), then it is replaced by the new one. - The subroutine remove_cus_dep removes the specified custom dependency. + The subroutine remove_cus_dep removes the specified custom dependency. The subroutine show_cus_dep causes a list of the currently defined cus- tom dependencies to be sent to the screen output. How custom dependencies are used: An instance of a custom dependency rule is created whenever latexmk de- - tects that a run of *latex needs to read a file, like a graphics file, - whose extension is the to-extension of a custom dependency. Then la- - texmk examines whether a file exists with the same name, but with the + tects that a run of *latex needs to read a file, like a graphics file, + whose extension is the to-extension of a custom dependency. Then la- + texmk examines whether a file exists with the same name, but with the - 10 January 2024 70 + 31 January 2024 70 @@ -4624,45 +4624,45 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - corresponding from-extension, as specified in the custom-dependency. - If it does, then a corresponding instance of the custom dependency is - created, after which the rule is invoked whenever the destination file + corresponding from-extension, as specified in the custom-dependency. + If it does, then a corresponding instance of the custom dependency is + created, after which the rule is invoked whenever the destination file (the one with the to-extension) is out-of-date with respect to the cor- responding source file. - To make the new destination file, the Perl subroutine specified in the + To make the new destination file, the Perl subroutine specified in the rule is invoked, with an argument that is the base name of the files in - question. Simple cases just involve a subroutine invoking an external - program; this can be done by following the templates below, even by - those without knowledge of the Perl programming language. Of course, + question. Simple cases just involve a subroutine invoking an external + program; this can be done by following the templates below, even by + those without knowledge of the Perl programming language. Of course, experts could do something much more elaborate. - One item in the specification of each custom-dependency rule, labeled - "must" above, specifies how the rule should be applied when the source + One item in the specification of each custom-dependency rule, labeled + "must" above, specifies how the rule should be applied when the source file fails to exist. - When latex reports that an input file (e.g., a graphics file) does not + When latex reports that an input file (e.g., a graphics file) does not exist, latexmk tries to find a source file and a custom dependency that can be used to make it. If it succeeds, then it creates an instance of - the custom dependency and invokes it to make the missing file, after + the custom dependency and invokes it to make the missing file, after which the next pass of latex etc will be able to read the newly created file. - Note for advanced usage: The operating system's environment variable + Note for advanced usage: The operating system's environment variable TEXINPUTS can be used to specify a search path for finding files by la- - tex etc. Correspondingly, when a missing file is reported, latexmk - looks in the directories specified in TEXINPUTS as well as in the cur- - rent directory, to find a source file from which an instance of a cus- + tex etc. Correspondingly, when a missing file is reported, latexmk + looks in the directories specified in TEXINPUTS as well as in the cur- + rent directory, to find a source file from which an instance of a cus- tom dependency can be used to make the missing file. Function to implement custom dependency, traditional method: - The function that implements a custom dependency gets the information + The function that implements a custom dependency gets the information on the files to be processed in two ways. The first is through its one - argument; the argument contains the base name of the source and desti- + argument; the argument contains the base name of the source and desti- nation files. The second way is described later. - A simple and typical example of code in an initialization rcfile using + A simple and typical example of code in an initialization rcfile using the first method is: add_cus_dep( 'fig', 'eps', 0, 'fig2eps' ); @@ -4670,18 +4670,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) system( "fig2dev -Leps \"$_[0].fig\" \"$_[0].eps\"" ); } - The first line adds a custom dependency that converts a file with ex- + The first line adds a custom dependency that converts a file with ex- tension "fig", as created by the xfig program, to an encapsulated post- - script file, with extension "eps". The remaining lines define a sub- - routine that carries out the conversion. If a rule for converting - "fig" to "eps" files already exists (e.g., from a previously read-in - initialization file), the latexmk will delete this rule before making + script file, with extension "eps". The remaining lines define a sub- + routine that carries out the conversion. If a rule for converting + "fig" to "eps" files already exists (e.g., from a previously read-in + initialization file), the latexmk will delete this rule before making the new one. - 10 January 2024 71 + 31 January 2024 71 @@ -4690,25 +4690,25 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - Suppose latexmk is using this rule to convert a file "figure.fig" to - "figure.eps". Then it will invoke the fig2eps subroutine defined in - the above code with a single argument "figure", which is the basename - of each of the files (possibly with a path component). This argument - is referred to by Perl as $_[0]. In the example above, the subroutine + Suppose latexmk is using this rule to convert a file "figure.fig" to + "figure.eps". Then it will invoke the fig2eps subroutine defined in + the above code with a single argument "figure", which is the basename + of each of the files (possibly with a path component). This argument + is referred to by Perl as $_[0]. In the example above, the subroutine uses the Perl command system to invoke the program fig2dev. The double quotes around the string are a Perl idiom that signify that each string - of the form of a variable name, $_[0] in this case, is to be substi- + of the form of a variable name, $_[0] in this case, is to be substi- tuted by its value. - If the return value of the subroutine is non-zero, then latexmk will - assume an error occurred during the execution of the subroutine. In - the above example, no explicit return value is given, and instead the - return value is the value returned by the last (and only) statement, + If the return value of the subroutine is non-zero, then latexmk will + assume an error occurred during the execution of the subroutine. In + the above example, no explicit return value is given, and instead the + return value is the value returned by the last (and only) statement, i.e., the invocation of system, which returns the value 0 on success. - If you use pdflatex, lualatex or xelatex instead of latex, then you - will probably prefer to convert your graphics files to pdf format, in - which case you would replace the above code in an initialization file + If you use pdflatex, lualatex or xelatex instead of latex, then you + will probably prefer to convert your graphics files to pdf format, in + which case you would replace the above code in an initialization file by add_cus_dep( 'fig', 'pdf, 0, 'fig2pdf' ); @@ -4716,30 +4716,30 @@ LATEXMK(1) General Commands Manual LATEXMK(1) system( "fig2dev -Lpdf \"$_[0].fig\" \"$_[0].pdf\"" ); } - Note 1: In the command lines given in the system commands in the above - examples, double quotes have been inserted around the file names (im- - plemented by '\"' in the Perl language). They immunize the running of - the program against special characters in filenames. Very often these - quotes are not necessary, i.e., they can be omitted. But it is nor- - mally safer to keep them in. Even though the rules for quoting vary - between operating systems, command shells and individual pieces of + Note 1: In the command lines given in the system commands in the above + examples, double quotes have been inserted around the file names (im- + plemented by '\"' in the Perl language). They immunize the running of + the program against special characters in filenames. Very often these + quotes are not necessary, i.e., they can be omitted. But it is nor- + mally safer to keep them in. Even though the rules for quoting vary + between operating systems, command shells and individual pieces of software, the quotes in the above examples do not cause problems in the cases I have tested. - Note 2: One case in which the quotes are important is when the files - are in a subdirectory and your operating system is Microsoft Windows. - Then the separator character for directory components can be either a - forward slash '/' or Microsoft's more usual backward slash '\'. For- - ward slashes are generated by latexmk, to maintain its sanity from - software like MiKTeX that mixes both directory separators; but their + Note 2: One case in which the quotes are important is when the files + are in a subdirectory and your operating system is Microsoft Windows. + Then the separator character for directory components can be either a + forward slash '/' or Microsoft's more usual backward slash '\'. For- + ward slashes are generated by latexmk, to maintain its sanity from + software like MiKTeX that mixes both directory separators; but their correct use normally requires quoted filenames. (See a log file from a - run of MiKTeX (at least in v. 2.9) for an example of the use of both + run of MiKTeX (at least in v. 2.9) for an example of the use of both directory separators.) - Note 3: The subroutines implementing custom dependencies in the exam- - ples given just have a single line invoking an external program. - That's the usual situation. But since the subroutines are in the Perl - language, you can implement much more complicated processing if you + Note 3: The subroutines implementing custom dependencies in the exam- + ples given just have a single line invoking an external program. + That's the usual situation. But since the subroutines are in the Perl + language, you can implement much more complicated processing if you need it. @@ -4747,7 +4747,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 72 + 31 January 2024 72 @@ -4757,19 +4757,19 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Removing custom dependencies, and when you might need to do this: - If you have some general custom dependencies defined in the system or - user initialization file, you may find that for a particular project - they are undesirable. So you might want to delete the unneeded ones. - A situation where this would be desirable is where there are multiple - custom dependencies with the same from-extension or the same to-exten- - sion. In that case, latexmk might choose a different one from the one + If you have some general custom dependencies defined in the system or + user initialization file, you may find that for a particular project + they are undesirable. So you might want to delete the unneeded ones. + A situation where this would be desirable is where there are multiple + custom dependencies with the same from-extension or the same to-exten- + sion. In that case, latexmk might choose a different one from the one you want for a specific project. As an example, to remove any "fig" to "eps" rule you would use: remove_cus_dep( 'fig', 'eps' ); - If you have complicated sets of custom dependencies, you may want to - get a listing of the custom dependencies. This is done by using the + If you have complicated sets of custom dependencies, you may want to + get a listing of the custom dependencies. This is done by using the line show_cus_dep(); @@ -4780,29 +4780,29 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Function implementing custom dependency, alternative methods: So far the examples for functions to implement custom dependencies have used the argument of the function to specify the base name of converted - file. This method has been available since very old versions of la- + file. This method has been available since very old versions of la- texmk, and many examples can be found, e.g., on the web. - However in later versions of latexmk the internal structure of the im- + However in later versions of latexmk the internal structure of the im- plementation of its "rules" for the steps of processing, including cus- tom dependencies, became much more powerful. The function implementing a custom dependency is executed within a special context where a number - of extra variables and subroutines are defined. Publicly documented - ones, intended to be long-term stable, are listed below, under the + of extra variables and subroutines are defined. Publicly documented + ones, intended to be long-term stable, are listed below, under the heading "Variables and subroutines for processing a rule". - Examples of their use is given in the following examples, concerning + Examples of their use is given in the following examples, concerning multiple index files and glossaries. - The only index-file conversion built-in to latexmk is from an ".idx" - file written on one run of *latex to an ".ind" file to be read in on a - subsequent run. But with the index.sty package, for example, you can - create extra indexes with extensions that you configure. Latexmk does + The only index-file conversion built-in to latexmk is from an ".idx" + file written on one run of *latex to an ".ind" file to be read in on a + subsequent run. But with the index.sty package, for example, you can + create extra indexes with extensions that you configure. Latexmk does not know how to deduce the extensions from the information it has. But - you can easily write a custom dependency. For example if your latex + you can easily write a custom dependency. For example if your latex file uses the command "\newindex{special}{ndx}{nnd}{Special index}" you - will need to get latexmk to convert files with the extension .ndx to - .nnd. The most elementary method is to define a custom dependency as + will need to get latexmk to convert files with the extension .ndx to + .nnd. The most elementary method is to define a custom dependency as follows: add_cus_dep( 'ndx', 'nnd', 0, 'ndx2nnd' ); @@ -4813,7 +4813,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 73 + 31 January 2024 73 @@ -4822,14 +4822,14 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - Notice the added line compared with earlier examples. The extra line + Notice the added line compared with earlier examples. The extra line gets the extensions "ndx" and "nnd" added to the list of extensions for generated files; then the extra index files will be deleted by clean-up operations - But if you have yet more indexes with yet different extensions, e.g., - "adx" and "and", then you will need a separate function for each pair - of extensions. This is quite annoying. You can use the Run_subst + But if you have yet more indexes with yet different extensions, e.g., + "adx" and "and", then you will need a separate function for each pair + of extensions. This is quite annoying. You can use the Run_subst function to simplify the definitions to use a single function: add_cus_dep( 'ndx', 'nnd', 0, 'dx2nd' ); @@ -4848,38 +4848,38 @@ LATEXMK(1) General Commands Manual LATEXMK(1) } push @generated_exts, 'ndx', 'nnd', 'adx', 'and'; - This last example uses the command specification in $makeindex, and so - any customization you have made for the standard index also applies to + This last example uses the command specification in $makeindex, and so + any customization you have made for the standard index also applies to your extra indexes. Similar techniques can be applied for glossaries. Those of you with experience with Makefiles, may get concerned that the - .ndx file is written during a run of *latex and is always later than + .ndx file is written during a run of *latex and is always later than the .nnd last read in. Thus the .nnd appears to be perpetually out-of- - date. This situation, of circular dependencies, is endemic to latex, - and is one of the issues that latexmk is programmed to overcome. It - examines the contents of the files (by use of a checksum), and only + date. This situation, of circular dependencies, is endemic to latex, + and is one of the issues that latexmk is programmed to overcome. It + examines the contents of the files (by use of a checksum), and only does a remake when the file contents have actually changed. - Of course if you choose to write random data to the .nnd (or the .aux - file, etc) that changes on each new run, then you will have a problem. + Of course if you choose to write random data to the .nnd (or the .aux + file, etc) that changes on each new run, then you will have a problem. For real experts: See the %hash_calc_ignore_pattern if you have to deal with such problems. Old Method of Defining Custom Dependencies: - In much older versions of latexmk, the only method of defining custom - dependencies was to directly manipulate the table of custom dependen- + In much older versions of latexmk, the only method of defining custom + dependencies was to directly manipulate the table of custom dependen- cies. This is contained in the @cus_dep_list array. It is an array of - strings, and each string in the array has four items in it, each sepa- - rated by a space, the from-extension, the to-extension, the "must" - item, and the name of the subroutine for the custom dependency. These + strings, and each string in the array has four items in it, each sepa- + rated by a space, the from-extension, the to-extension, the "must" + item, and the name of the subroutine for the custom dependency. These were all defined above. - 10 January 2024 74 + 31 January 2024 74 @@ -4889,7 +4889,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) An example of the old method of defining custom dependencies is as fol- - lows. It is the code in an RC file to ensure automatic conversion of + lows. It is the code in an RC file to ensure automatic conversion of .fig files to .eps files: push @cus_dep_list, "fig eps 0 fig2eps"; @@ -4897,21 +4897,21 @@ LATEXMK(1) General Commands Manual LATEXMK(1) return system( "fig2dev -Lps \"$_[0].fig\" \"$_[0].eps\"" ); } - This method still works, and is almost equivalent to the code given - earlier that used the add_cus_dep subroutine. However, the old method - doesn't delete any previous custom-dependency for the same conversion. + This method still works, and is almost equivalent to the code given + earlier that used the add_cus_dep subroutine. However, the old method + doesn't delete any previous custom-dependency for the same conversion. So the new method is preferable. Advanced configuration: Some extra resources and advanced tricks - For most purposes, simple configuration for latexmk along the lines of - the examples given is sufficient. But sometimes you need something - harder. In this section, I indicate some extra possibilities. Gener- - ally to use these, you need to be fluent in the Perl language, since + For most purposes, simple configuration for latexmk along the lines of + the examples given is sufficient. But sometimes you need something + harder. In this section, I indicate some extra possibilities. Gener- + ally to use these, you need to be fluent in the Perl language, since this is what is used in the rc files. - See also the section DEALING WITH ERRORS, PROBLEMS, ETC. See also the + See also the section DEALING WITH ERRORS, PROBLEMS, ETC. See also the examples in the directory example_rcfiles in the latexmk distributions. Even if none of the examples apply to your case, they may give you use- ful ideas @@ -4920,13 +4920,13 @@ Advanced configuration: Some extra resources and advanced tricks Utility subroutines ensure_path( var, values ...) - The first parameter is the name of one of the system's environ- - ment variables for search paths. The remaining parameters are - values that should be in the variable. For each of the value - parameters, if it isn't already in the variable, then it is + The first parameter is the name of one of the system's environ- + ment variables for search paths. The remaining parameters are + values that should be in the variable. For each of the value + parameters, if it isn't already in the variable, then it is prepended to the variable; in that case the environment variable - is created if it doesn't already exist. For separating values, - the character appropriate the the operating system is used -- + is created if it doesn't already exist. For separating values, + the character appropriate the the operating system is used -- see the configuration variable $search_path_separator. Example: @@ -4934,18 +4934,18 @@ Advanced configuration: Some extra resources and advanced tricks ensure_path( 'TEXINPUTS', './custom_cls_sty_files//' ); (In this example, the trailing '//' is documented by TeX systems - to mean that *latex search for files in the specified directory + to mean that *latex search for files in the specified directory and in all subdirectories.) - Technically ensure_path works by setting Perl's variable - $ENV{var}, where var is the name of the target variable. The - changed value is then passed as an environment variable to any + Technically ensure_path works by setting Perl's variable + $ENV{var}, where var is the name of the target variable. The + changed value is then passed as an environment variable to any invoked programs. - 10 January 2024 75 + 31 January 2024 75 @@ -4956,22 +4956,22 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Variables and subroutines for processing a rule A step in the processing is called a rule. One possibility to implement - the processing of a rule is by a Perl subroutine. This is always the - case for custom dependencies. Also, for any other rule, you can use a - subroutine by prefixing the command specification by the word "inter- + the processing of a rule is by a Perl subroutine. This is always the + case for custom dependencies. Also, for any other rule, you can use a + subroutine by prefixing the command specification by the word "inter- nal" -- see the section FORMAT OF COMMAND SPECIFICATIONS. - When you use a subroutine for processing a rule, all the possibilities + When you use a subroutine for processing a rule, all the possibilities of Perl programming are available, of course. In addition, some of la- - texmk's internal variables and subroutines are available. The ones - listed below are intended to be available to (advanced) users, and + texmk's internal variables and subroutines are available. The ones + listed below are intended to be available to (advanced) users, and their specifications will generally have stability under upgrades. Gen- - erally, the variables should be treated as read-only: Changing their - values can have bad consequences, since it is liable to mess up the + erally, the variables should be treated as read-only: Changing their + values can have bad consequences, since it is liable to mess up the consistency of what latexmk is doing. - $rule This variable has the name of the rule, as known to latexmk. - Note that the exact contents of this variable for a given rule + $rule This variable has the name of the rule, as known to latexmk. + Note that the exact contents of this variable for a given rule may be dependent on the version of latexmk $$Psource @@ -4979,39 +4979,39 @@ LATEXMK(1) General Commands Manual LATEXMK(1) dollar signs. $$Pdest - This gives the name of the main output file if any. Note the + This gives the name of the main output file if any. Note the double dollar signs. pushd( path ), popd() - These subroutines are used when it is needed to temporarily + These subroutines are used when it is needed to temporarily change the working directory, as in pushd( 'some_directory' ); - ... Processing done with 'some_directory' as the working + ... Processing done with 'some_directory' as the working directory popd() - They perform exactly the same function as the commands of the + They perform exactly the same function as the commands of the same names in operating system command shells like bash on Unix, and cmd.exe on the Windows. rdb_add_generated( file, ... ) This subroutine is to be used in the context of a rule, that is, - from within a subroutine that is carrying out processing of a + from within a subroutine that is carrying out processing of a rule. Such is the case for the subroutine implementing a custom - dependency, or the subroutine invoked by using the "internal" - keyword in the command specification like that in the variable + dependency, or the subroutine invoked by using the "internal" + keyword in the command specification like that in the variable $latex. - Its arguments are a sequence of filenames which are generated - during the running of the rule. The names might arise from an + Its arguments are a sequence of filenames which are generated + during the running of the rule. The names might arise from an analysis of the results of the run, e.g., in a log file, or from - 10 January 2024 76 + 31 January 2024 76 @@ -5020,64 +5020,64 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - knowledge of properties of the specific rule. Calling - rdb_add_generated with these filenames ensures that these files - are flagged as generated by the rule in latexmk's internal data + knowledge of properties of the specific rule. Calling + rdb_add_generated with these filenames ensures that these files + are flagged as generated by the rule in latexmk's internal data structures. Basically, no action is taken if the files have al- ready been flagged as generated. - A main purpose of using this subroutine is for the situation - when a generated file is also the source file for some rule, so - that latexmk can correctly link the dependency information in + A main purpose of using this subroutine is for the situation + when a generated file is also the source file for some rule, so + that latexmk can correctly link the dependency information in its network of rules. Note: Unlike some other subroutines in this section, there is no - argument for a rule for rdb_add_generated. Instead, the subrou- - tine is to be invoked during the processing of a rule when la- + argument for a rule for rdb_add_generated. Instead, the subrou- + tine is to be invoked during the processing of a rule when la- texmk has set up an appropriate context (i.e., appropriate vari- - ables). In contrast, subroutines with a rule argument can be + ables). In contrast, subroutines with a rule argument can be used also outside a rule context. rdb_ensure_file( $rule, file ) - This subroutine ensures that the given file is among the source + This subroutine ensures that the given file is among the source files for the specified rule. It is typically used when, during - the processing of a rule, it is known that a particular extra + the processing of a rule, it is known that a particular extra file is among the dependencies that latexmk should know, but its - default methods don't find the dependency. Almost always the - first argument is the name of the rule currently being + default methods don't find the dependency. Almost always the + first argument is the name of the rule currently being processed, so it is then appropriate to specify it by $rule. - For examples of its use, see some of the files in the directory - example_rcfiles of latexmk's distribution. Currently the cases - that use this subroutine are bib2gls-latexmkrc, exceltex_la- - texmkrc and texinfo-latexmkrc. These illustrate typical cases - where latexmk's normal processing fails to detect certain extra + For examples of its use, see some of the files in the directory + example_rcfiles of latexmk's distribution. Currently the cases + that use this subroutine are bib2gls-latexmkrc, exceltex_la- + texmkrc and texinfo-latexmkrc. These illustrate typical cases + where latexmk's normal processing fails to detect certain extra source files. Note that rdb_ensure_file only has one filename argument, unlike other subroutines in this section. If you want to apply its ac- - tion to multiple files, you will need one call to rdb_en- + tion to multiple files, you will need one call to rdb_en- sure_file for each file. rdb_remove_files( $rule, file, ... ) - This subroutine removes one or more files from the dependency + This subroutine removes one or more files from the dependency list for the given rule. rdb_remove_generated( file, ... ) This subroutine is to be used in the context of a rule, that is, - from within a subroutine that is carrying out processing of a - rule. It performs the opposite action to rdb_add_generated. - Its effect is to ensure that the given filenames are not listed - in latexmk's internal data structures as being generated by the + from within a subroutine that is carrying out processing of a + rule. It performs the opposite action to rdb_add_generated. + Its effect is to ensure that the given filenames are not listed + in latexmk's internal data structures as being generated by the rule. - 10 January 2024 77 + 31 January 2024 77 @@ -5087,7 +5087,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) rdb_list_source( $rule ) - This subroutine returns the list of source files (i.e., the de- + This subroutine returns the list of source files (i.e., the de- pendency list) for the given rule. @@ -5095,9 +5095,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1) rdb_set_source( $rule, @files ) - This subroutine sets the dependency list for the given rule to + This subroutine sets the dependency list for the given rule to be the specified files. Files that are already in the list have - unchanged information. Files that were not in the list are + unchanged information. Files that were not in the list are added to it. Files in the previous dependency list that are not in the newly specified list of files are removed from the depen- dency list. @@ -5105,18 +5105,18 @@ LATEXMK(1) General Commands Manual LATEXMK(1) Run_subst( command_spec ) This subroutine runs the command specified by command_spec. The - specification is a string in the format listed in the section - "Format of Command Specifications". An important action of the + specification is a string in the format listed in the section + "Format of Command Specifications". An important action of the Run_subst is to make substitutions of placeholders, e.g., %S and - %D for source and destination files; these get substituted be- + %D for source and destination files; these get substituted be- fore the command is run. In addition, the command after substi- - tution is printed to the screen unless latexmk is running in + tution is printed to the screen unless latexmk is running in silent mode. Coordinated Setting of Commands for *latex To set all of $dvilualatex, $hilatex, $latex, $pdflatex, $lualatex, and - $xelatex to a common pattern, you can use one of the following subrou- + $xelatex to a common pattern, you can use one of the following subrou- tines, std_tex_cmds, alt_tex_cmds, and set_tex_cmds. To get the standard commands, use @@ -5124,26 +5124,26 @@ LATEXMK(1) General Commands Manual LATEXMK(1) &std_tex_cmds; This results in $latex = 'latex %O %S', and similarly for $dvilualatex, - $hilatex, $pdflatex, $lualatex, and $xelatex. Note the ampersand in - the invocation; this indicates to Perl that a subroutine is being - called. (The use of this subroutine enables you to override previous - redefinitions of the $latex, etc variables, which might have occurred + $hilatex, $pdflatex, $lualatex, and $xelatex. Note the ampersand in + the invocation; this indicates to Perl that a subroutine is being + called. (The use of this subroutine enables you to override previous + redefinitions of the $latex, etc variables, which might have occurred in an earlier-read rc file.) - To be able to use the string provided by the -pretex option (if any), + To be able to use the string provided by the -pretex option (if any), you can use &alt_tex_cmds; - This results in $latex = 'latex %O %P', etc. Again note the ampersand - in the invocation; this indicates to Perl that a subroutine is being + This results in $latex = 'latex %O %P', etc. Again note the ampersand + in the invocation; this indicates to Perl that a subroutine is being called. A more general way of specifying the variables is using - 10 January 2024 78 + 31 January 2024 78 @@ -5154,9 +5154,9 @@ LATEXMK(1) General Commands Manual LATEXMK(1) set_tex_cmds( 'CMD_SPEC' ); - Here CMD_SPEC is the command line without the program name. This re- - sults in $latex = 'latex CMD_SPEC', and similarly for $pdflatex, etc. - (An ampersand preceding the subroutine name is not necessary here, + Here CMD_SPEC is the command line without the program name. This re- + sults in $latex = 'latex CMD_SPEC', and similarly for $pdflatex, etc. + (An ampersand preceding the subroutine name is not necessary here, since the parentheses show Perl that a subroutine is being invoked.) An example that provides the --interaction=batchmode option to the *la- @@ -5164,52 +5164,52 @@ LATEXMK(1) General Commands Manual LATEXMK(1) set_tex_cmds( '--interaction=batchmode %O %S' ); - This results in $latex = 'latex --interaction=batchmode %O %S ', etc. - Note that when '%O' appears after the added option, as here, options + This results in $latex = 'latex --interaction=batchmode %O %S ', etc. + Note that when '%O' appears after the added option, as here, options provided on the command line to latexmk can override the supplied one. A more general command line can be set up by using the placeholder '%C' in CMD_SPEC. The '%C' is substituted by the basic name of the command, i.e., whichever of 'latex', 'pdflatex', etc is appropriate. (More than - one occurrence of '%C' is allowed.) For example to use the develop- + one occurrence of '%C' is allowed.) For example to use the develop- ment/pre-release versions of latex, etc, which have names, 'latex-dev', 'pdflatex-dev', etc, you could use set_tex_cmds( '%C-dev %O %S' ); This results in $latex = 'latex-dev %O %S', etc. (The pre-release pro- - grams latex-dev etc are provided in current distributions of TeXLive + grams latex-dev etc are provided in current distributions of TeXLive and MiKTeX.) Advanced configuration: Using latexmk with make - This section is targeted only at advanced users who use the make pro- + This section is targeted only at advanced users who use the make pro- gram for complex projects, as for software development, with the depen- dencies specified by a Makefile. - Now the basic task of latexmk is to run the appropriate programs to - make a viewable version of a LaTeX document. However, the usual make - program is not suited to this purpose for at least two reasons. First + Now the basic task of latexmk is to run the appropriate programs to + make a viewable version of a LaTeX document. However, the usual make + program is not suited to this purpose for at least two reasons. First is that the use of LaTeX involves circular dependencies (e.g., via .aux files), and these cannot be handled by the standard make program. Sec- - ond is that in a large document the set of source files can change - quite frequently, particularly with included graphics files; in this - situation keeping a Makefile manually updated is inappropriate and er- + ond is that in a large document the set of source files can change + quite frequently, particularly with included graphics files; in this + situation keeping a Makefile manually updated is inappropriate and er- ror-prone, especially when the dependencies can be determined automati- cally. Latexmk solves both of these problems robustly. - Thus for many standard LaTeX documents latexmk can be used by itself - without the make program. In a complex project it simply needs to be - suitably configured. A standard configuration would be to define cus- - tom dependencies to make graphics files from their source files (e.g., - as created by the xfig program). Custom dependencies are latexmk's + Thus for many standard LaTeX documents latexmk can be used by itself + without the make program. In a complex project it simply needs to be + suitably configured. A standard configuration would be to define cus- + tom dependencies to make graphics files from their source files (e.g., + as created by the xfig program). Custom dependencies are latexmk's equivalent of pattern rules in Makefiles. - Nevertheless there are projects for which a Makefile is appropriate, + Nevertheless there are projects for which a Makefile is appropriate, - 10 January 2024 79 + 31 January 2024 79 @@ -5220,13 +5220,13 @@ LATEXMK(1) General Commands Manual LATEXMK(1) and it is useful to know how to use latexmk from a Makefile. A typical example would be to generate documentation for a software project. Po- - tentially the interaction with the rest of the rules in the Makefile + tentially the interaction with the rest of the rules in the Makefile could be quite complicated, for example if some of the source files for a LaTeX document are generated by the project's software. In this section, I give a couple of examples of how latexmk can be use- - fully invoked from a Makefile. The examples use specific features of - current versions of GNU make, which is the default on both linux and + fully invoked from a Makefile. The examples use specific features of + current versions of GNU make, which is the default on both linux and OS-X systems. They may need modifications for other versions of make. The simplest method is simply to delegate all the relevant tasks to la- @@ -5238,33 +5238,33 @@ LATEXMK(1) General Commands Manual LATEXMK(1) %.pdf : %.tex FORCE_MAKE latexmk -pdf -dvi- -ps- $< - (Note: the last line must be introduced by a tab for the Makefile to - function correctly!) Naturally, if making try.pdf from its associated - LaTeX file try.tex were the only task to be performed, a direct use of - latexmk without a Makefile would normally be better. The benefit of - using a Makefile for a LaTeX document would be in a larger project, + (Note: the last line must be introduced by a tab for the Makefile to + function correctly!) Naturally, if making try.pdf from its associated + LaTeX file try.tex were the only task to be performed, a direct use of + latexmk without a Makefile would normally be better. The benefit of + using a Makefile for a LaTeX document would be in a larger project, where lines such as the above would be only be a small part of a larger Makefile. The above example has a pattern rule for making a .pdf file from a .tex - file, and it is defined to use latexmk in the obvious way. There is a + file, and it is defined to use latexmk in the obvious way. There is a conventional default target named "all", with a prerequisite of - try.pdf. So when make is invoked, by default it makes try.pdf. The - only complication is that there may be many source files beyond + try.pdf. So when make is invoked, by default it makes try.pdf. The + only complication is that there may be many source files beyond try.tex, but these aren't specified in the Makefile, so changes in them - will not by themselves cause latexmk to be invoked. Instead, the pat- - tern rule is equipped with a "phony" prerequisite FORCE_MAKE; this has - the effect of causing the rule to be always out-of-date, so that la- - texmk is always run. It is latexmk that decides whether any action is - needed, e.g., a rerun of pdflatex. Effectively the Makefile delegates - all decisions to latexmk, while make has no knowledge of the list of + will not by themselves cause latexmk to be invoked. Instead, the pat- + tern rule is equipped with a "phony" prerequisite FORCE_MAKE; this has + the effect of causing the rule to be always out-of-date, so that la- + texmk is always run. It is latexmk that decides whether any action is + needed, e.g., a rerun of pdflatex. Effectively the Makefile delegates + all decisions to latexmk, while make has no knowledge of the list of source files except for primary LaTeX file for the document. If there are, for example, graphics files to be made, these must be made by cus- tom dependencies configured in latexmk. - But something better is needed in more complicated situations, for ex- + But something better is needed in more complicated situations, for ex- ample, when the making of graphics files needs to be specified by rules - in the Makefile. To do this, one can use a Makefile like the follow- + in the Makefile. To do this, one can use a Makefile like the follow- ing: TARGETS = document1.pdf document2.pdf @@ -5275,7 +5275,7 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 80 + 31 January 2024 80 @@ -5295,53 +5295,53 @@ LATEXMK(1) General Commands Manual LATEXMK(1) %.pdf : %.fig fig2dev -Lpdf $< $@ - (Again, the lines containing the commands for the rules should be + (Again, the lines containing the commands for the rules should be started with tabs.) This example was inspired by how GNU automake han- dles automatic dependency tracking of C source files. - After each run of latexmk, dependency information is put in a file in - the .deps subdirectory. The Makefile causes these dependency files to + After each run of latexmk, dependency information is put in a file in + the .deps subdirectory. The Makefile causes these dependency files to be read by make, which now has the full dependency information for each - target .pdf file. To make things less trivial it is specificed that - two files document1.pdf and document2.pdf are the targets. The depen- + target .pdf file. To make things less trivial it is specificed that + two files document1.pdf and document2.pdf are the targets. The depen- dency files are .deps/document1.pdfP and .deps/document2.pdfP. - There is now no need for the phony prerequisite for the rule to make + There is now no need for the phony prerequisite for the rule to make .pdf files from .tex files. But I have added a rule to make .pdf files - from .fig files produced by the xfig program; these are commonly used - for graphics insertions in LaTeX documents. Latexmk is arranged to + from .fig files produced by the xfig program; these are commonly used + for graphics insertions in LaTeX documents. Latexmk is arranged to output a dependency file after each run. It is given the -recorder op- - tion, which improves its detection of files generated during a run of - pdflatex; such files should not be in the dependency list. The -e op- - tions are used to turn off all custom dependencies, and to document - this. Instead the -use-make is used to delegate the making of missing + tion, which improves its detection of files generated during a run of + pdflatex; such files should not be in the dependency list. The -e op- + tions are used to turn off all custom dependencies, and to document + this. Instead the -use-make is used to delegate the making of missing files to make itself. - Suppose in the LaTeX file there is a command \includegraphics{graph}, - and an xfig file "graph.fig" exists. On a first run, pdflatex reports - a missing file, named "graph". Latexmk succeeds in making "graph.pdf" + Suppose in the LaTeX file there is a command \includegraphics{graph}, + and an xfig file "graph.fig" exists. On a first run, pdflatex reports + a missing file, named "graph". Latexmk succeeds in making "graph.pdf" by calling "make graph.pdf", and after completion of its work, it lists "fig.pdf" among the dependents of the file latexmk is making. Then let - "fig.fig" be updated, and then let make be run. Make first remakes + "fig.fig" be updated, and then let make be run. Make first remakes "fig.pdf", and only then reruns latexmk. - Thus we now have a method by which all the subsidiary processing is + Thus we now have a method by which all the subsidiary processing is delegated to make. - Escaping of characters in dependency lists: There are certain special - characters that need to be escaped when names of files and directories - containing them appear in a dependency list used by a make program. + Escaping of characters in dependency lists: There are certain special + characters that need to be escaped when names of files and directories + containing them appear in a dependency list used by a make program. Generally, such special characters are best avoided. - By default, latexmk does no escaping of this kind, and the user will + By default, latexmk does no escaping of this kind, and the user will have to arrange to deal with the issue separately, if the relevant spe- - cial characters are used. Note that the rules for escaping depend on + cial characters are used. Note that the rules for escaping depend on which make program is used, and on its version. - 10 January 2024 81 + 31 January 2024 81 @@ -5350,20 +5350,20 @@ LATEXMK(1) General Commands Manual LATEXMK(1) LATEXMK(1) General Commands Manual LATEXMK(1) - One special case is of spaces, since those are particularly prevalent, - notably in standard choices of name for a user's home directory. So - latexmk does provide an option to escape spaces. See the option + One special case is of spaces, since those are particularly prevalent, + notably in standard choices of name for a user's home directory. So + latexmk does provide an option to escape spaces. See the option -deps_escape=... and the variable $deps_escape for details. NON_ASCII CHARACTERS IN FILENAMES, RC FILES, ETC Modern operating systems and file systems allow non-ASCII characters in - the names of files and directories that encompass the full Unicode + the names of files and directories that encompass the full Unicode range. Mostly, latexmk deals with these correctly. However, there are - some situations in which there are problems, notably on Microsoft Win- + some situations in which there are problems, notably on Microsoft Win- dows. Prior to version 4.77, latexmk had problems with non-ASCII file- - names on Windows, even though there were no corresponding problems on + names on Windows, even though there were no corresponding problems on macOS and Linux. These problems are corrected in the present version. DETAILS TO BE FILLED IN @@ -5376,38 +5376,38 @@ SEE ALSO BUGS (SELECTED) Sometimes a viewer (gv) tries to read an updated .ps or .pdf file after - its creation is started but before the file is complete. Work around: + its creation is started but before the file is complete. Work around: manually refresh (or reopen) display. Or use one of the other preview- ers and update methods. - (The following isn't really a bug, but concerns features of preview- - ers.) Preview continuous mode only works perfectly with certain pre- - viewers: Xdvi on UNIX/Linux works for dvi files. Gv on UNIX/Linux - works for both postscript and pdf. Ghostview on UNIX/Linux needs a - manual update (reopen); it views postscript and pdf. Gsview under MS- - Windows works for both postscript and pdf, but only reads the updated - file when its screen is refreshed. Acroread under UNIX/Linux views - pdf, but the file needs to be closed and reopened to view an updated - version. Under MS-Windows, acroread locks its input file and so the - pdf file cannot be updated. (Remedy: configure latexmk to use suma- + (The following isn't really a bug, but concerns features of preview- + ers.) Preview continuous mode only works perfectly with certain pre- + viewers: Xdvi on UNIX/Linux works for dvi files. Gv on UNIX/Linux + works for both postscript and pdf. Ghostview on UNIX/Linux needs a + manual update (reopen); it views postscript and pdf. Gsview under MS- + Windows works for both postscript and pdf, but only reads the updated + file when its screen is refreshed. Acroread under UNIX/Linux views + pdf, but the file needs to be closed and reopened to view an updated + version. Under MS-Windows, acroread locks its input file and so the + pdf file cannot be updated. (Remedy: configure latexmk to use suma- trapdf instead.) THANKS TO - Authors of previous versions. Many users with their feedback, and es- + Authors of previous versions. Many users with their feedback, and es- pecially David Coppit (username david at node coppit.org) who made many - useful suggestions that contributed to version 3, and Herbert Schulz. - (Please note that the e-mail addresses are not written in their stan- + useful suggestions that contributed to version 3, and Herbert Schulz. + (Please note that the e-mail addresses are not written in their stan- dard form to avoid being harvested too easily.) AUTHOR - Current version, by John Collins (Version 4.82a). Report bugs etc to + Current version, by John Collins (Version 4.83). Report bugs etc to his e-mail (jcc8 at psu.edu). - Released version can be obtained from CTAN: + Released version can be obtained from CTAN: - 10 January 2024 82 + 31 January 2024 82 @@ -5416,7 +5416,7 @@ AUTHOR LATEXMK(1) General Commands Manual LATEXMK(1) - , and from the author's website + , and from the author's website . Modifications and enhancements by Evan McLean (Version 2.0) Original script called "go" by David J. Musliner (RCS Version 3.2) @@ -5473,6 +5473,6 @@ LATEXMK(1) General Commands Manual LATEXMK(1) - 10 January 2024 83 + 31 January 2024 83 diff --git a/support/splint/INSTALL b/support/splint/INSTALL index 033877aba0..a8a1634b55 100644 --- a/support/splint/INSTALL +++ b/support/splint/INSTALL @@ -1,4 +1,4 @@ -% Copyright 2012-2020, Alexander Shibakov +% Copyright 2012-2024, Alexander Shibakov % This file is part of SPLinT % % SPLinT is free software: you can redistribute it and/or modify @@ -40,7 +40,13 @@ compiled and used. For this purpose, make variables BISON_ROOT and FLEX_ROOT can be set to the appropriate locations in makefile.loc. The appropriate versions of bison and flex can be downloaded from http://ftp.gnu.org/gnu/bison/ and http://flex.sourceforge.net/, -respectively. The installation instructions in those packages are easy +respectively. Due to the changes in glibc, the bison that comes with the +distribution (bison-2.7) needs to be patched first. Uncompress the archive +(bison-2.7.tar.gz) in some directory, copy bison_patch1 to it and run + + # patch -p0 < bison_patch1 + +The installation instructions in those packages are easy to follow (the standard ./configure --prefix= &&\ make && cp src/bison && cp -a data/* \ /share/bison should work). diff --git a/support/splint/Makefile b/support/splint/Makefile index b7f0269350..e122cfb363 100644 --- a/support/splint/Makefile +++ b/support/splint/Makefile @@ -1,4 +1,4 @@ -# Copyright 2012-2020, Alexander Shibakov +# Copyright 2012-2024, Alexander Shibakov # This file is part of SPLinT # # SPLinT is free software: you can redistribute it and/or modify @@ -13,11 +13,16 @@ # # You should have received a copy of the GNU General Public License # along with SPLinT. If not, see . +SPLINT_EXAMPLES_BASE = expression ld +SPLINT_EXAMPLES_EXTRA = symbols xxpression +SPLINT_EXAMPLE_OTHER = $(if $BISON_IS_CRIPPLED,,$SPLINT_EXAMPLES_EXTRA) -SPLINT_EXAMPLE_OTHER = $(if $BISON_IS_CRIPPLED,,symbols xxpression) +SPLINT_EXAMPLES_DIRS = ${SPLINT_EXAMPLES_BASE} ${SPLINT_EXAMPLE_OTHER} +SPLINT_EXAMPLES_DIRS_ALL = ${SPLINT_EXAMPLES_BASE} ${SPLINT_EXAMPLES_EXTRA} -SPLINT_EXAMPLES_DIRS = expression ld ${SPLINT_EXAMPLE_OTHER} -SPLINT_EXAMPLES_DIRS_ALL = expression ld symbols xxpression +# the install directory; should be replaced by the appropriate local directory +# in makefile.loc +SPLINT_INSTALL_DIR = /tmp DO_SUBMAKE = for dir in ${SPLINT_EXAMPLES_DIRS}; do cd ${SPLINT_ROOT}examples/$$dir && ${MAKE} $(1); done CLEAN_SUBMAKE = for dir in ${SPLINT_EXAMPLES_DIRS_ALL}; do cd ${SPLINT_ROOT}examples/$$dir && ${MAKE} $(1); done @@ -31,12 +36,28 @@ lists: tex/*.sty perl scripts/cslist.pl $^ > cseqs.lst manual: - cd ${SPLINT_ROOT}cweb && ${MAKE} splint.pdf + cd ${SPLINT_ROOT}cweb && ${MAKE} docs docs: - cd ${SPLINT_ROOT}cweb && ${MAKE} splint.pdf && ${MAKE} ssffo.pdf + cd ${SPLINT_ROOT}cweb && ${MAKE} docs $(call DO_SUBMAKE,docs) +# install a stand alone version of all the parsers in the package + +install: all + @cp ${SPLINT_ROOT}tex/*.sty ${SPLINT_INSTALL_DIR}/tex/ + @cp ${SPLINT_ROOT}cweb/*.tok ${SPLINT_INSTALL_DIR}/cweb/ + @cp -a ${SPLINT_ROOT}other/ ${SPLINT_INSTALL_DIR}/other/ + @cp ${SPLINT_XPTABLES} ${SPLINT_INSTALL_DIR}/cweb/ + @cp ${SPLINT_XLTABLES} ${SPLINT_INSTALL_DIR}/cweb/ + @cd ${SPLINT_ROOT}examples/ld && ${MAKE} install + +uninstall: + @cd ${SPLINT_ROOT}examples/ld && ${MAKE} uninstall + @rm -f ${SPLINT_INSTALL_DIR}/tex/* + @rm -f ${SPLINT_INSTALL_DIR}/cweb/* + @rm -rf ${SPLINT_INSTALL_DIR}/other/texmf/ + # clean will erase all automatically generated files in the current directory clean: clean_core diff --git a/support/splint/README b/support/splint/README index 9665ca2e7c..56e01e55d4 100644 --- a/support/splint/README +++ b/support/splint/README @@ -1,6 +1,6 @@ To make the licensing part clear, SPLinT is GPL v.~3: -% Copyright 2012-2020, Alexander Shibakov +% Copyright 2012-2022, Alexander Shibakov % This file is part of SPLinT % % SPLinT is free software: you can redistribute it and/or modify @@ -38,7 +38,6 @@ cweb/* - executables and documentation: fo.w - parser for the flex grammar so.w - lexer for the flex grammar np.w - scanner and parser for token names - ssffo.w - lexer for state grabbing mkeparser.w - parser output `driver' mkscanner.w - lexer output `driver' splint.w - documentation @@ -51,7 +50,7 @@ tex/* - \TeX\ macros xarithm.sty - expandable arithmetic for parsing macros grabstates.sty - macros for state grabbing *tokenset.sty - token typesetting definitions - gindex.sty -generic indexing macros + gindex.sty - generic indexing macros dcols.sty - multiple column output noweb.sty - noweb style references (local within a page) limbo.sty - limbo section macros @@ -85,4 +84,4 @@ VERSION - the current version The most recent version of this software can be downloaded at - math.tntech.edu/alex/splint.tar.bz2 + www.shibakov.org/splint/archive/splint.tar.bz2 diff --git a/support/splint/TODO b/support/splint/TODO index 95e44e9459..ad8473cb6d 100644 --- a/support/splint/TODO +++ b/support/splint/TODO @@ -4,22 +4,32 @@ o Typo and style fixes ... sometime in the future -o Change generic macro names (such as \table, \symstream, etc) to something more specific +* Add an `install_macros' (or the like) to makefile.loc to automate macro installation + for the parser generated by this package (the parsers and lexers are not separated + into different directories, the new targets are `install' and `uninstall') +* Fix the double column output macros to correctly process the \mark commands (every time + an output routine runs it resets the \topmark; this needs to be corrected) +* Change generic macro names (such as \table) to something more specific (\table will stay + but most macro names are unique enough) +* Add a macro to index arbitrary strings in an arbitrary domain (store the string in a + global array and pass the pointer to the indexing macros) +* Reimplement the action for the bison parser using lists * Add \bgrulealign and \egrulealign macros to align rules across sections (a simple way to implement this is given as an example in the included package, a more flexible method would have to wait) * Rewrite yytexlex.sty for better \TeX\ pretty printing macros (* the new macros are still not ideal but are very unlikely to change in the near future) - o Change the name of the namespace (currently 'index') used by the \TeXx macros to avoid - confusion with the special '[index]' namespace used by the parser for inserted symbols - (like an empty right hand side and implicit terms) + * Change the name of the namespace (currently `index') used by the \TeXx macros to avoid + confusion with the special `[index]' namespace used by the parser for inserted symbols + (like an empty right hand side and implicit terms) (`index' has been changed to `index:tex') o Develop a 'loose' parsing scheme for \TeX\ macros by requiring some macros to follow stricter rules * Rewrite limbo.sty to provide a more logical structure (* several changes have been implemented) * Add indexing features to \TeXx macros (* there is a mechanism to do this) +o Optimize \yyinput to minimize expansion in the most common cases o Change CWEB macros so that \pdfoutput=0 does not cause conflicts (this is a bug in cwebmac.tex) -o Change the support for named references so that the driver generates references while outputting - the 'action switch' (using code like stack_depth = $$ - $[name]) +* Change the support for named references so that the driver generates references while outputting + the 'action switch' (using code like stack_depth = $$ - $[name];* done using `lazy' postprocessing) ... very remote future diff --git a/support/splint/VERSION b/support/splint/VERSION index 9084fa2f71..f0bb29e763 100644 --- a/support/splint/VERSION +++ b/support/splint/VERSION @@ -1 +1 @@ -1.1.0 +1.3.0 diff --git a/support/splint/cweb/Makefile b/support/splint/cweb/Makefile index 1c3b4d6bc3..f80b6b5886 100644 --- a/support/splint/cweb/Makefile +++ b/support/splint/cweb/Makefile @@ -1,4 +1,4 @@ -# Copyright 2012-2020, Alexander Shibakov +# Copyright 2012-2024, Alexander Shibakov # This file is part of SPLinT # # SPLinT is free software: you can redistribute it and/or modify @@ -13,17 +13,30 @@ # # You should have received a copy of the GNU General Public License # along with SPLinT. If not, see . +docs: splint.pdf include ../makefile.inc -all: ${SPLINT_PTABLES} ${SPLINT_LTABLES} +tables: ${SPLINT_PTABLES} ${SPLINT_LTABLES} -b%out: mkeparser.c b%.c - ${CC} ${BISON_STATE} -DPARSER_FILE=\"$(lastword $^)\" -DYYPARSE_PARAMETERS= -o $@ $< +bdout bbout bgout \ +bfout:b%out: mkeparser.c b%.c + ${CC} ${BISON_STATE} -DPARSER_FILE=\"$(lastword $^)\" -DYYPARSE_PARAMETERS= -o $@ $< -b%.yy: bo.x +bd.yy bg.yy \ +bb.yy bf.yy:b%.yy: bo.u bo.m ${CTANGLE} $< +bd.yx bg.yx \ +bb.yx bf.yx:%.yx: %.yy + ${BRACK} --replace-only --bison-link=bo.m $*.yy $*.yx + +bd.y bg.y \ +bb.y bf.y:%.y: %.yx + cp -f $^ $@ + +byytab.tex gyytab.tex \ +dyytab.tex fyytab.tex:\ %yytab.tex: b%out ${SPLINT_DRIVER_DIR}/$< --optimize-actions $@ @@ -33,15 +46,13 @@ ltab.tex: ltout ltout: mkscanner.c lo_states.h lo.c ${CC} -DLEXER_FILE=\"$(lastword $^)\" -o $@ $< -ssffo.ll lo.ll: \ -%.ll: %.x +lo.ll: %.ll: %.x ${CTANGLE} $< && rm $(patsubst %.x, %.c, $^) fil.ll: so.x ${CTANGLE} $< && rm $(patsubst %.x, %.c, $^) -fip.yy rep.yy rap.yy \ -ddp.yy: fo.x +fip.yy rep.yy rap.yy ddp.yy: fo.x ${CTANGLE} $< && rm $(patsubst %.x, %.c, $^) # flex parser @@ -52,19 +63,21 @@ fil.c: fil.l fil_out: mkscanner.c fil_states.h fil.c ${CC} -DLEXER_FILE=\"$(lastword $^)\" -o $@ $< -fil_states.h: so.tex lstab.tex byytab.tex - ${PDFTEX} $< - filtab.tex: fil_out ${SPLINT_DRIVER_DIR}/$< --optimize-actions --optimize-tables $@ -fip.c rep.c rap.c \ -ddp.c:%.c: %.y +# state parsing for the \flex\ input scanner + +fil_states.h: so.tex ssfstab.tex ddptab.tex ${SPLINT_ROOT}tex/grabstates.sty + @echo "Generating state list for the flex lexer ..." + @${PDFTEX} $< + +fip.c rep.c rap.c ddp.c:%.c: %.y ${BISON} -o $@ $< fip_out rap_out \ -ddp_out rep_out:%_out: mkeparser.c %.c - ${CC} ${BISON_STATE} -DPARSER_FILE=\"$(lastword $^)\" -DYYPARSE_PARAMETERS= -o $@ $< +ddp_out rep_out:%_out: mkeparser.c %.c + ${CC} ${BISON_STATE} -DPARSER_FILE=\"$(lastword $^)\" -DYYPARSE_PARAMETERS= -o $@ $< fiptab.tex raptab.tex \ ddptab.tex reptab.tex:%tab.tex: %_out @@ -74,10 +87,11 @@ so.tex: so.x ${CWEAVE} $< fo.tex: fo.x - ${CWEAVE} $< + -${CWEAVE} $< -fo.tok: fo.tex ltab.tex byytab.tex - ${TEX} ${MODEBOOTSTRAP} \\input $< +fo.tok: fo.tex ltab.tex dyytab.tex bo.tok + @echo "Generating token equivalences for flex input parser ..." + @${TEX} ${MODEBOOTSTRAP} \\input $< lo.c: lo.l ${FLEX} -o $@ $< @@ -86,10 +100,24 @@ mkscanner.c mkeparser.c: \ %.c: %.w ${CTANGLE} $< +# bootstrap flex parser + +ssfs.ll: so.x + ${CTANGLE} $< && rm $(patsubst %.x, %.c, $^) + +ssfs.c: ssfs.l + ${FLEX} -o $@ $< + +ssfs_out: mkscanner.c ssfs.c + ${CC} -DLEXER_FILE=\"$(lastword $^)\" -o $@ $< + +ssfstab.tex: ssfs_out + ${SPLINT_DRIVER_DIR}/$< --optimize-actions --optimize-tables $@ + # name parser -smallp_out: mkeparser.c small_parser.c - ${CC} ${BISON_STATE} -DPARSER_FILE=\"$(lastword $^)\" -DYYPARSE_PARAMETERS= -o $@ $< +smallp_out: mkeparser.c small_parser.c + ${CC} ${BISON_STATE} -DPARSER_FILE=\"$(lastword $^)\" -DYYPARSE_PARAMETERS= -o $@ $< smalll_out: mkscanner.c small_lexer.c ${CC} -DLEXER_FILE=\"$(lastword $^)\" -o $@ $< @@ -105,71 +133,56 @@ small_lexer.ll: np.x @${CTANGLE} $< bo.tex: bo.x - -${CWEAVE} -x $< + -${CWEAVE} -x $< 1>/dev/null splint.tex \ splint.idx \ splint.scn: splint.x bo.x lo.x fo.x so.x np.x common.w bs.w \ fk.w philosophy.w checklists.w references.w alphas.hx - -${CWEAVE} $< + -${CWEAVE} $< 1>/dev/null alphas.hx: - ${MISCCW} --alpha-list --alpha-length=1 $@ - -ssffo.tex \ -ssffo.idx ssffo.scn: ssffo.x - ${CWEAVE} $< + @${MISCCW} --alpha-list --alpha-length=1 $@ bo.tok: bo.tex ltab.tex byytab.tex - ${TEX} ${MODEBOOTSTRAP} \\input $< - -ssffo.pdf: %.pdf: ${SPLINT_DOC_PREREQS_XREF} - ${PDFTEX} $*.tex - -ssffo.dvi: %.dvi: ${SPLINT_DOC_PREREQS_XREF} - ${TEX} $*.tex + @echo "Making token equivalence tables for the bison parser ..." + @${TEX} ${MODEBOOTSTRAP} \\input $< #1>/dev/null -splint.gdx: %.gdx: ${SPLINT_DOC_PREREQS_XREF} +splint.gdx splint.aux: ${SPLINT_DOC_PREREQS_XREF} @echo "Making the bison and TeX indices ..." - ${PDFTEX} $*.tex + @${PDFTEX} splint.tex #1>/dev/null + +# remove the implicit rule before building the main index %.gdy: %.gdx splint.gdy: splint.gdx ${BINDX} --fine $^ $@ -splint.xxr: %.xxr: ${SPLINT_DOC_PREREQS_XREF} - @echo "Generating the cross references ..." - ${PDFTEX} $*.tex - -splint.pdf: %.pdf: ${SPLINT_DOC_PREREQS_XREF} %.gdy %.xxr - ${PDFTEX} \\input $*.tex && touch $*.gdy && touch $*.pdf +splint.pdf: %.pdf: ${SPLINT_DOC_PREREQS_XREF} %.gdy %.aux + @echo "Generating SPLinT documentation (splint.pdf) ..." + while test "`diff --new-file splint.pdf /tmp/splint.pdf`"; do \ + echo "Files differ" && mv splint.pdf /tmp/; \ + ${PDFTEX} \\input $*.tex && touch $*.gdy && touch $*.pdf; \ + done splint.dvi: %.dvi: ${SPLINT_DOC_PREREQS_XREF} %.gdy - ${TEX} $*.tex && touch $*.gdy && touch $*.dvi && rm $*.xxr && rm $*.ftn - -${SPLINT_ROOT}tex/btokenset.sty: # stupid make weirdness - @ + @${TEX} $*.tex && touch $*.gdy && touch $*.dvi && rm $*.ftn # state parsing -lstabout: mkscanner.c ssffo.c - ${CC} -DLEXER_FILE=\"$(lastword $^)\" -o $@ $< - -lstab.tex: lstabout - ${SPLINT_DRIVER_DIR}/$< --optimize-actions $@ - lo.tex: lo.x ${CWEAVE} $< -lo_states.h: lo.tex lstab.tex byytab.tex - ${PDFTEX} $< +lo_states.h: lo.tex ssfstab.tex ddptab.tex ${SPLINT_ROOT}tex/grabstates.sty + @echo "Generating state list for the bison lexer ..." + @${PDFTEX} $< # clean will erase all automatically generated files in the current directory clean: clean_core - -rm -f ctablesout b?out ltout smallp_out \ - smalll_out lstabout fil_out fip_out rep_out rap_out ddp_out + -rm -f ctablesout b?out ltout smallp_out /tmp/splint.pdf \ + smalll_out ssfs_out fil_out fip_out rep_out rap_out ddp_out include ${SPLINT_ROOT}makefile.loc @@ -178,9 +191,9 @@ include ${SPLINT_ROOT}makefile.loc # of bo.tok, lo.tex, eventually leading to remaking of splint.pdf; # the special target below tells make to treat bg.yy as if it were not an intermediate file -.PRECIOUS: %.yy bo.tok fo.tok %.ll b%.y splint.gdx splint.xxr +.PRECIOUS: %.yy bo.tok fo.tok %.ll b%.y splint.gdx # the files below appear as targets but are really intermediaries for other files -.INTERMEDIATE: smallp_out smalll_out lstabout ltout fil_out \ +.INTERMEDIATE: smallp_out smalll_out ssfs_out ltout fil_out \ fip_out rep_out rap_out ddp_out splint.gdx diff --git a/support/splint/cweb/bo.w b/support/splint/cweb/bo.w index fe7bf59f52..630602559e 100644 --- a/support/splint/cweb/bo.w +++ b/support/splint/cweb/bo.w @@ -1,4 +1,4 @@ -% Copyright 2012-2020, Alexander Shibakov +% Copyright 2012-2024, Alexander Shibakov % Copyright 2002-2014 Free Software Foundation, Inc. % This file is part of SPLinT % @@ -24,6 +24,20 @@ \fi @**The \eatone{bison}\bison\ parser stack. +{% +\newdimen\halfhsize +\newdimen\preskip +\halfhsize=\hsize +\divide\halfhsize by2 +\def\mypar{% +\parshape 6 +0pt \hsize +0pt \hsize +0pt \hsize +0pt \hsize +0pt \hsize +\halfhsize \halfhsize +}% The input language for \bison\ loosely follows the {\sc BNF} notation, with a few enhancements, such as the syntax for {\em actions}, to implement the syntax-directed translation@^syntax-directed translation@>, as @@ -33,8 +47,8 @@ On the one hand, the language is relatively easy to handle, is nearly whitespace agnostic, on the other, a primitive parser is required for some basic setup even at a very early stage, so the design must be carefully thought out. This {\em -bootstrapping\/}@^bootstrapping@> step is discussed in more details -later on. +bootstrapping\/}@^bootstrapping@> step is discussed in more detail +further down. The path chosen here is by no means optimal. What it lacks in efficiency, though, it may amply gain in practicality, as we reuse the @@ -47,13 +61,13 @@ As was described in the stacks \endlink\fi@^parser stack@> above, to pretty print a variety of grammar fragments, one may employ a {\em parser stack\/} derived from the original grammar. The most -natural and common unit of a \bison\ grammar is a set of +common unit of a \bison\ grammar is a set of productions. It is thus natural to begin our discussion of the parsers in the \bison\ stack with the parser responsible for processing individual rules. -One should note that the productions below are not concerned with the -typesetting of the grammar. Instead this task is delegated to the +One should note that the productions below are not directly concerned with the +typesetting of the grammar. Instead, this task is delegated to the macros in \.{yyunion.sty} and its companions. The first pass of the parser merely constructs an `executable abstract syntax tree' (or \EAST\footnote{One may argue that \EAST\ is still merely a syntactic @@ -61,7 +75,11 @@ construct requiring a proper macro framework for its execution and should be called a `weak executable syntax tree' or \WEST. This acronym extravagnza is heading south so we shall stop here.}) which can serve very diverse purposes: from collecting token declarations in -the boostrapping pass to typesetting the grammar rules. +the boostrapping pass to typesetting the grammar rules. This allows for a +great deal of flexibility in where and when the parsing results are +used. A clear divide between the parsing step and the typesetting step +provides for better debugging facilities, as well as more reliable +macro design. It would be impossible to completely avoid the question of the visual presentation of the \bison\ input, however. It has already been @@ -72,14 +90,23 @@ variety of typographic devices that take advantage of the meaningful positioning of text on the page: skips, indents, etc. Therefore, the macros for \bison\ pretty printing trade a number of \bison\ syntax elements (such as \.{\yl}, \.{;}, action braces, etc.) for the careful -placement of each fragment of the input on the page. +placement of each fragment of the input on the page. The syntax tree +generated by the parsers in the \bison\ stack is not fully {\em faithful\/} in +that it does not preserve every syntactic element from the original input. +Thus, e.g.\ optional semicolons (\prodstyle{semi.opt}) never find their way into +the tree and their original position is lost\footnote{The opposite is true about +the {\em whitespace\/} the parser sees (or {\em stash\/} as it is called +in this document): all of it is carefully packaged into streams, as was described +\locallink{parser.streams}earlier\endlink.}. Let's take a short break for a broad overview of the input file. The basic structure is that of an ordinary \bison\ file that produces plain \Cee\ output. The \Cee\ actions, however, are programmed to output \TeX. The \bison\ sections (separated by \.{\%\%} (shown (pretty printed) as \prodstyle{\%\%} below)) appear between the successive dotted lines. - +A number of sections are empty, since the generated \Cee\ is rather trivial. +}% +%\checktabletrue @(bg.yy@>= @G Switch to generic mode. %{@> @ @=%} @@ -94,11 +121,13 @@ as \prodstyle{\%\%} below)) appear between the successive dotted lines. %% @g -@ Bootstrap\namedspot{bootstrapping}@^bootstrapping@> mode is next. -The reason for a separate bootstrap parser is to -collect the minimal amount of information to `spool up' the `production' -parsers. To understand the mechanics and the reasons behind it, consider what happens -following a declaration such as \.{\%token TOKEN "token"} +@*1 Bootstrapping. +%\checktablefalse +Bootstrap\namedspot{bootstrapping}@^bootstrapping@> parser is +defined next. The purpose of the bootstrapping parser is to +collect a minimal amount of information to `spool up' the `production' +parsers. To understand its inner workings and the reasons behind it, +consider what happens following a declaration such as \.{\%token TOKEN "token"} (or, as it would be typeset by the macros in this package `\prodstyle{\%token} \.{TOKEN} \.{token}'; see the index entries for more details)% @@ -119,8 +148,8 @@ equivalences or find some other means to find out the numerical values of the tokens. One approach is to parse the file containing the {\it declarations\/} -and extract the equivalences between the names from it. This is the -function of the bootstrap parser. Since the lexer is reused, some +and extract the equivalences between the names from it. This is +precisely the function of the bootstrap parser. Since the lexer is reused, some token values need to be known in advance (and the rest either ignored or replaced by some `made up' values). These tokens are `hard coded' into the parser file generated by \bison\ and output using a special @@ -145,25 +174,43 @@ which it would need a parser for a subset of \bison\ syntax $\ldots$ it is a genuine `chicken and egg' problem). Hence the need for `bootstrap'. Once a functional parser for a large enough subset of the \bison\ input grammar is operational, {\it it\/} can be used to pair -up the token names. - -The second function of the bootstrap parser is to collect information -about the scanner's states. The mechanism is slightly different for -states. While the token equivalences are collected purely in -`\TeX\ mode', the bootstrap parser collects all the state names into a +up the token names. The bootstrap parser is not strictly minimal in that +it is also capable of parsing the \prodstyle{\%nterm} declarations. +This ability is not utilized by the parsers in \splint, however (nor +is the accompanying bootstrap lexer designed to output the +\prodstyle{\%nterm} tokens), and was added for the scenarios other +than bootstrapping. + +The second, perhaps even more important function of the bootstrap process +is to collect information about the scanner's states. The mechanism +is slightly different from that for token definition gathering. +While the token equivalences are collected purely in +`\TeX\ mode', the bootstrap mode parser collects all the state names into a special \Cee\ header file. The reason is simple: unlike the token values, the numerical values of the scanner states are not passed to -the `driver' program in any data structure and are instead defined as -ordinary macros. The header file is the information the `driver' file -needs to output the state values. - -An additional subtlety in the case of the state value output is that the -main lexer for the \bison\ grammar utilizes states extensively and thus -cannot be easily used with the bootstrap parser before the state -values are known. The solution is to substitute a very simple scanner barely -capable of lexing state declarations. Such a scanner is implemented -in \.{ssffo.w} (the somewhat cryptic name stands for `{\bf s}imple {\bf s}canner -{\bf f}or {\bf f}lex {\bf o}ptions'). +the `driver' program in any data structure (the |yytname| array) and are instead defined as +ordinary (\Cee) macros. The header file is the information the `driver' file +needs to output the state values for the use by the lexer. + +Naturally, to accomplish their task, the lexer and the parser emplyed in +state gathering need the state and token information, as well. Fortunately, +the parser is a subset of the \flex\ input parser that does not define +any `string' names for it tokens. Similarly, the lexer collects all the necessary +tokens in the \flexsnstyle{INITIAL} state\footnote{An additional subtlety is +the necessity to gracefully handle (and, in some cases, cause) the multiple +possible {\em failures\/} for which the lexer redefines \inlineTeXx{/yyBEGIN}\ +to fail immediately when attempting to switch states. Note that the bootstrap +mode parser looks at sections other than those where the declarations reside +and must fail quickly and quietly in such cases.}. + +To reiterate a point made in the middle of this section, the bootstrapping +process described here is necessary to `spool up' the \bison\ and \flex\ input parsers. +A simpler procedure may be followed while designing other custom parsers where +the programmer uses, say the full \bison\ parser to collect information about +the token equivalences (whether such information is needed to make the parser operational +or just to facilitate the typesetting of the token names). By adding custom +`bootstrapping' macros to the ones defined in \.{yyunion.sty}, a number of different +preprocessing tasks can be accomplished. @(bb.yy@>= @G Switch to generic mode. %{ @@ -177,13 +224,11 @@ in \.{ssffo.w} (the somewhat cryptic name stands for `{\bf s}imple {\bf s}canner %% @> @ @= @> @ @= - @> @<\flex\ options parser productions@> @= - @> @ @= - @> @ @= %% @g -@ The prologue parser is responsible for parsing various grammar +@*1 Prologue and full parsers. +The prologue parser is responsible for parsing various grammar declarations as well as parser options. @(bd.yy@>= @G Switch to generic mode. @@ -201,7 +246,12 @@ declarations as well as parser options. @ The full \bison\ input parser is used when a complete \bison\ file is expected. It is also capable of parsing a `skeleton' of such a file, -similar to the one that follows this paragraph. +similar to the one that follows this paragraph. As a stopgap measure, +the skeleton of a \flex\ scanner is also parsed by this parser, as they have +an almost identical structure. This is not a perfect arrangement, however, since +it precludes one from putting the constructs that this parser does not +recognize into the outline. To give an example, one cannot put \flex\ specific +options into such `skeleton'. @(bf.yy@>= @G Switch to generic mode. %{@> @ @=%} @@ -227,7 +277,7 @@ parsing algorithm to be used (provided the supplied grammar is in the appropriate class): {\sc LALR}($n$), {\sc LR}($n$), {\sc GLR}, etc. The default is to use the {\sc LALR}($1$) algorithm (with the corresponding assumption about the grammar) which can also be set -explicitly by putting +explicitly by putting\gtextidx{\bison\ options example}{bison options example}{\bisonidxdomain}% \medskip \beginprod \%define lr.type canonical-lr @@ -259,7 +309,6 @@ special bootstrapping parser as explained earlier. \iffalse \checktrailingstashtrue % see what is left at the end \checktabletrue % display the table - \let\stashnext\stashnextwithnothing % collect the stash expanded \fi @= @G @@ -289,7 +338,6 @@ the original parser. \iffalse \checktrailingstashfalse \checktablefalse - \let\stashnext\stashnextwithnothingnx \fi @= @G @@ -339,17 +387,6 @@ the original parser. %token PERCENT_PARAM "%param"; @g -@ \namedspot{flex.options}Extra tokens for typesetting \flex\ state -declarations and options are declared in addition to the ones that a -standard \bison\ parser recognizes. This extension of the original -grammar has become unnecessary with the addition of the \flex\ input -parser(s) but is left as part of the extended grammar for convenience and -`historical' reasons. -@= -@G -%token FLEX_OPTION FLEX_STATE_X FLEX_STATE_S -@g - @*1 Grammar productions. We are ready to describe the top levels of the parse tree. The first `sub parser' we consider is a `full' parser, that is the parser that @@ -373,10 +410,15 @@ parser on the stack. @t}\vb{\inline}{@> input: prologue_declarations - "%%" grammar epilogue.opt {@> TeX_( "/getsecond{/yy(3)}/to/table" ); @=} + "%%" grammar epilogue.opt {@> @ @=} ; @g +@ @= + @[TeX_( "/finishlist{/expandafter/yyfirstoftwo/the/yy(3)}" );@]@; /* complete the list */ + @[TeX_( "/table/expandafter{/romannumeral0" );@]@; + @[TeX_( " /executelistat{/expandafter/yyfirstoftwo/the/yy(3)}{0}}" );@]@; + @ Another subgrammar deals with the syntax of isolated \bison\ rules. This is the most commonly used `subparser' since a rules cluster is the most natural `unit' to include in a \CWEB\ file. @@ -384,10 +426,15 @@ natural `unit' to include in a \CWEB\ file. @G @t}\vb{\inline}{@> input: - grammar epilogue.opt {@> TeX_( "/getsecond{/yy(1)}/to/table" ); @=} + grammar epilogue.opt {@> @ @=} ; @g +@ @= + @[TeX_( "/finishlist{/expandafter/yyfirstoftwo/the/yy(1)}" );@]@; /* complete the list */ + @[TeX_( "/table/expandafter{/romannumeral0" );@]@; + @[TeX_( " /executelistat{/expandafter/yyfirstoftwo/the/yy(1)}{0}}" );@]@; + @ The bootstrap parser has a very narrow set of goals: it is concerned with \prodstyle{\%token} declarations only in order to supply the token information to the lexer (since, as noted @@ -395,7 +442,7 @@ above, such information is not kept in the |yytname| array). The parser can also parse \prodstyle{\%nterm} declarations but the bootstrap lexer ignores the \prodstyle{\%nterm} token, since the \bison\ grammar does not use one. -It also extends the syntax of a \prodstyle{grammar\_declaration} by allowing a +It also extends the syntax of a \prodstyle{grammar_declaration} by allowing a declaration with or without a semicolon at the end (the latter is only allowed in the prologue). This works since the token declarations have been carefully separated from the rest of the grammar in different @@ -410,11 +457,8 @@ input: @t}\vb{\resetf}{@> grammar_declarations: symbol_declaration semi.opt {@> @ @=} -| flex_declaration semi.opt {@> @ @=} | grammar_declarations symbol_declaration semi.opt {@> TeX_( "/yy0{/the/yy(1)/the/yy(2)}" ); @=} -| grammar_declarations - flex_declaration semi.opt {@> TeX_( "/yy0{/the/yy(1)/the/yy(2)}" ); @=} ; @t}\vb{\inline\flatten}{@> semi.opt: {} | ";" {}; @@ -429,35 +473,42 @@ is undocumented so we supply an explicit action in each case. @ Next comes a subgrammar for processing prologue declarations. Finer differentiation is possible but the `subparsers' described here work pretty well and impose a mild style on the grammar writer. Note that -these roles are not part of the official \bison\ input grammar and are +these rules are not part of the official \bison\ input grammar and are added to make the typesetting of `file outlines' (e.g.~|@(bb.yy@>| above) possible. @= @G @t}\vb{\inline}{@> input: - prologue_declarations epilogue.opt {@> TeX_( "/getsecond{/yy(1)}/to/table" ); @=} + prologue_declarations epilogue.opt {@> @ @=} | prologue_declarations - "%%" "%%" EPILOGUE {@> TeX_( "/getsecond{/yy(1)}/to/table" ); @=} + "%%" "%%" EPILOGUE {@> @ @=} | prologue_declarations - "%%" "%%" {@> TeX_( "/getsecond{/yy(1)}/to/table" ); @=} + "%%" "%%" {@> @ @=} ; @g +@ @= + @[TeX_( "/finishlist{/expandafter/yyfirstoftwo/the/yy(1)}" );@]@; /* complete the list */ + @[TeX_( "/table/expandafter{/romannumeral0" );@]@; + @[TeX_( " /executelistat{/expandafter/yyfirstoftwo/the/yy(1)}{0}}" );@]@; + @ {\it Declarations: before the first \prodstyle{\%\%}}. We are now -ready to deal with the specifics of the declarations themselves. The -\.{\\grammar} macro is a `structure', whose first `field' is the -grammar itself, whereas the second carries the type of the last -declaration added to the grammar. +ready to deal with the specifics of the declarations themselves. @= @G prologue_declarations: - {@> TeX_( "/yy0{/nx/grammar{}{/nx/empty}}" ); @=} + {@> @ @=} | prologue_declarations prologue_declaration {@> @ @=} ; @g +@ @= + @[TeX_( "/initlist{/prologuedeclarationsprefix prologue_declarations}" );@]@; + @[TeX_( "/yy0{{/prologuedeclarationsprefix prologue_declarations}{/nx/empty}}" );@]@; + @[TeX_( "/edef/prologuedeclarationsprefix{./prologuedeclarationsprefix}" );@]@; + @ @= @@; @@ -466,6 +517,7 @@ prologue. The scanner returns the `stream pointers' for all the keywords so the declaration `structures' pass on those pointers to the grammar list. The original syntax has been left intact even though for the purposes of this parser some of the inline rules are unnecessary. +\eraselocalformattrue @= @G prologue_declaration: @@ -474,10 +526,13 @@ prologue_declaration: | "%" {@> TeX_( "/yy0{/nx/optionflag/the/yy(1)}" ); @=} | "%define" variable value {@> TeX_( "/yy0{/nx/vardef{/the/yy(2)}{/the/yy(3)}/the/yy(1)}" ); @=} | "%defines" {@> TeX_( "/yy0{/nx/optionflag{defines}{}/the/yy(1)}" ); @=} -| "%defines" STRING {@> @[TeX_( "/toksa{defines}" );@]@+@ @=} +| "%defines" STRING {@> @t}\vb{\stashed{\Xmark prologue.decls:\Xmark}}{@> @= + @> @[TeX_( "/toksa{defines}" );@]@+@ @=} | "%error-verbose" {@> TeX_( "/yy0{/nx/optionflag{error verbose}{}/the/yy(1)}" ); @=} -| "%expect" INT {@> @[TeX_( "/toksa{expect}" );@]@+@ @=} -| "%expect-rr" INT {@> @[TeX_( "/toksa{expect-rr}" );@]@+@ @=} +| "%expect" INT {@> @t}\vb{\stashed{\Xmark prologue.decls(g):\Xmark}}{@> @= + @> @[TeX_( "/toksa{expect}" );@]@+@ @=} +| "%expect-rr" INT {@> @t}\vb{\stashed{\Xmark prologue.decls(g):\Xmark}}{@> @= + @> @[TeX_( "/toksa{expect-rr}" );@]@+@ @=} | "%file-prefix" STRING {@> @[TeX_( "/toksa{file prefix}" );@]@+@ @=} | "%glr-parser" {@> TeX_( "/yy0{/nx/optionflag{glr parser}{}/the/yy(1)}" ); @=} | "%initial-action" "{...}" {@> TeX_( "/yy0{/nx/initaction/the/yy(2)}" ); @=} @@ -485,12 +540,14 @@ prologue_declaration: | "%name-prefix" STRING {@> @[TeX_( "/toksa{name prefix}" );@]@+@ @=} | "%no-lines" {@> TeX_( "/yy0{/nx/optionflag{no lines}{}/the/yy(1)}" ); @=} | "%nondeterministic-parser" {@> TeX_( "/yy0{/nx/optionflag{nondet. parser}{}/the/yy(1)}" ); @=} -| "%output" STRING {@> @[TeX_( "/toksa{output}" );@]@+@ @=} +| "%output" STRING {@> @t}\vb{\stashed{\Xmark prologue.decls:\Xmark}}{@> @= + @> @[TeX_( "/toksa{output}" );@]@+@ @=} @t}\vb{\flatten}{@> -| "%param" {} +| "%param" {@> @t}\vb{\stashed{\rm (we simply return pointers below)}}{@> @=} params {@> TeX_( "/yy0{/nx/paramdef{/the/yy(3)}/the/yy(1)}" ); @=} @t}\vb{\fold}{@> -| "%require" STRING {@> @[TeX_( "/toksa{require}" );@]@+@ @=} +| "%require" STRING {@> @t}\vb{\stashed{\Xmark prologue.decls:\Xmark}}{@> @= + @> @[TeX_( "/toksa{require}" );@]@+@ @=} | "%skeleton" STRING {@> @[TeX_( "/toksa{skeleton}" );@]@+@ @=} | "%token-table" {@> TeX_( "/yy0{/nx/optionflag{token table}{}/the/yy(1)}" ); @=} | "%verbose" {@> TeX_( "/yy0{/nx/optionflag{verbose}{}/the/yy(1)}" ); @=} @@ -507,69 +564,22 @@ params: @ This is a typical parser action: encapsulate the `type' of the construct just parsed and attach some auxiliary info, in this case the stream pointers. +\eraselocalformatfalse +\smallskip +\rulereferencex{\showlastactionfalse}{\nx\inline\nx\flatten}{prologue.decls} +\smallskip +\noindent The productions above are typical examples. @= @[TeX_( "/yy0{/nx/oneparametricoption{/the/toksa}{/nx/stringify/the/yy(2)}/the/yy(1)}" );@]@; -@ @= +@ A variation on the theme above where the parameter is not a \prodstyle{STRING}. +\smallskip +\rulereferencex{\showlastactionfalse}{\nx\inline\nx\flatten}{prologue.decls(g)} +\smallskip +\noindent A sample of the rules to which the code below applies are given above. +@= @[TeX_( "/yy0{/nx/oneparametricoption{/the/toksa}{/the/yy(2)}/the/yy(1)}" );@]@; -@ These rules handle extra declarations to typeset \flex\ options and -declarations. These are not part of the \bison\ syntax but their -structure is similar enough that they can be included in the -grammar. As was pointed out \locallink{flex.options}earlier \endlink -the addition of the \flex\ input parser to \splint\ made this -extension of the original \bison\ grammar obsolete but it was kept as -part of the extended grammar for convenience and `historical' -reasons. The convenience results from simplifying the bootstrap -procedure by using a single parser. -@= -@G -prologue_declaration: - flex_declaration {@> @ @=} -; -@g -@<\flex\ options parser productions@>@; - -@ The syntax of \flex\ options was extracted from \flex\ documentation -so it is not guaranteed to be correct. -@<\flex\ options parser productions@>= -@G -flex_declaration: - FLEX_OPTION flex_option_list {@> @ @=} -| flex_state symbols.1 {@> @ @=} -; - -flex_state: - FLEX_STATE_X {@> TeX_( "/yy0{/nx/flexxstatedecls/the/yy(1)}" ); @=} -| FLEX_STATE_S {@> TeX_( "/yy0{/nx/flexsstatedecls/the/yy(1)}" ); @=} -; - -flex_option_list: - flex_option {@> @ @=} -| flex_option_list flex_option {@> @ @=} -; - -flex_option: - ID {@> TeX_( "/yy0{/nx/flexoptionpair{/nx/idit/the/yy(1)}{}}" ); @=} -| ID "=" symbol {@> TeX_( "/yy0{/nx/flexoptionpair{/nx/idit/the/yy(1)}{/the/yy(3)}}" ); @=} -; -@g - -@ @= - @[TeX_( "/yy0{/nx/flexoptiondecls{/the/yy(2)}/the/yy(1)}" );@]@; - -@ @= - @[TeX_( "/getfirst{/yy(1)}/to/toksa" );@]@; - @[TeX_( "/getsecond{/yy(1)}/to/toksb" );@]@; - @[TeX_( "/getthird{/yy(1)}/to/toksc" );@]@; - @[TeX_( "/yy0{/the/toksa{/the/yy(2)}{/the/toksb}{/the/toksc}}" );@]@; - -@ @= - @[TeX_( "/getsecond{/yy(2)}/to/toksa" );@]@; /* the identifier */ - @[TeX_( "/getfourth{/toksa}/to/toksb" );@]@; /* the format pointer */ - @[TeX_( "/getfifth{/toksa}/to/toksc" );@]@; /* the stash pointer */ - @[TeX_( "/yy0{/the/yy(1)/nx/hspace{/the/toksb}{/the/toksc}/the/yy(2)}" );@]@; - @ {\it Grammar declarations}. These declarations can appear in both the prologue and the rules sections. Their treatment is very similar to the prologue-only options. @@ -578,7 +588,8 @@ the prologue-only options. grammar_declaration: precedence_declaration {@> @ @=} | symbol_declaration {@> @ @=} -| "%start" symbol {@> @[TeX_( "/toksa{start}" );@]@+@ @=} +| "%start" symbol {@> @t}\vb{\stashed{\Xmark prologue.decls(g):\Xmark}}{@> @= + @> @[TeX_( "/toksa{start}" );@]@+@ @=} | code_props_type "{...}" generic_symlist {@> @ @=} | "%default-prec" {@> TeX_( "/yy0{/nx/optionflag{default prec.}{}/the/yy(1)}" ); @=} | "%no-default-prec" {@> TeX_( "/yy0{/nx/optionflag{no default prec.}{}/the/yy(1)}" ); @=} @@ -617,7 +628,6 @@ union_name: grammar_declaration: "%union" union_name "{...}" {@> @ @=} ; - symbol_declaration: "%type" TAG symbols.1 {@> @ @=} ; @@ -637,6 +647,7 @@ tag.opt: {@> TeX_( "/yy0{}" ); @=} | TAG {@> @ @=} ; +@t}\vb{\insertraw{\beginfoldedsections}}{@> @g @ @= @@ -644,6 +655,7 @@ tag.opt: @ @= @[TeX_( "/yy0{/nx/typedecls{/nx/tagit/the/yy(2)}{/the/yy(3)}/the/yy(1)}" );@]@; +@t}\endfoldedsections{@> @ @= @[TeX_( "/getthird{/yy(1)}/to/toksa" );@]@; /* format pointer */ @@ -677,7 +689,9 @@ symbol_declaration: @ {\it Just like \prodstyle{symbols.1} but accept \prodstyle{INT} for the sake of \POSIX}. Perhaps the only point worth mentioning here is -the inserted separator (\.{\\hspace\{}$p_0$\.{\}\{}$p_1$\.{\}}, +the inserted separator (% +\texrefx{/hspace}{other}% +\.{\{}$p_0$\.{\}\{}$p_1$\.{\}}, typeset as |TeXa("/hspace"); TeXao(@t\TeXlit"\{\hbox{$p_0$}\}\{\hbox{$p_1$}\}\hbox{$\!$}"@>);|). @q A string "..." is a syntactic unit in \CWEB\ so it is impossible@> @@ -700,22 +714,16 @@ symbol.prec: ; @g -@ {\it One or more symbols to be \prodstyle{\%type}'d}. The |@| rules below are reused in the boostrap parser and are put -in a separate section for this reason. +@ {\it One or more symbols to be \prodstyle{\%type}'d}. @= - @@; - -@ @= @G +%type symbols.1 symbol; + symbols.1: symbol {@> @ @=} -| symbols.1 symbol {@> TeX_( "/yy0{/the/yy(1)/nx/hspace{0}{0}/the/yy(2)}" ); @=} +| symbols.1 symbol {@> TeX_( "/yy0{/the/yy(1)/nx/hspace{0}{0}/the$[symbol]}" ); @=} ; -@g -@ @= -@G generic_symlist: generic_symlist_item {@> @ @=} | generic_symlist generic_symlist_item {@> TeX_( "/yy0{/the/yy(1)/nx/hspace{0}{0}/the/yy(2)}" ); @=} @@ -772,42 +780,50 @@ grammar: ; @g -@ {\it As a \bison\ extension, one can use the grammar declarations in the +@*2 Rules syntax. {\it As a \bison\ extension, one can use the grammar declarations in the body of the grammar}. What follows is the syntax of the right hand -side of a grammar rule. +side of a grammar rule. The type declarations for various non-terminals are used exclusively +by the postprocessor whenever the `native' \bison\ term references are used (see elsewhere +for details). @= @G +%type rhs id_colon named_ref.opt rhses.1 "|"; + rules_or_grammar_declaration: - rules {@> @ @=} + rules {@> @

@=} | grammar_declaration ";" {@> @ @=} | error ";" {@> TeX_( "/errmessage{parsing error!}" ); @=} ; @t}\vb{\flatten\inline}{@> rules: - id_colon named_ref.opt {@> TeX_( "/relax" ); @=} + id_colon named_ref.opt {@> @t}\vb{\stashed{\rm (we simply return pointers below)}}{@> @=} rhses.1 {@> @ @=} ; @t}\vb{\resetf}{@> rhses.1[o]: rhs {@> @ @=} -| rhses.1[a] "|"[b] {@> @ @=}[c] +| rhses.1[rhses] "|"[mid] {@> @ @=}[c] rhs[d] {@> @ @=} -| rhses.1 ";" {@> @ @=} +| rhses.1 ";" {@> @ @=} ; @g @ The next few actions describe what happens when a left hand side is attached to a rule. @= - @[TeX_( "/getfirst{/yy(1)}/to/toksa" );@]@; - @[TeX_( "/yy0{/nx/grammar{/the/yy(1)}{/the/toksa}}" );@]@; + @[TeX_( "/initlist{/grammarprefix grammar}" );@]@; + @[TeX_( "/getfirst{/yy(1)}/to/toksa" );@]@; /* type of the last addition */ + @[TeX_( "/yy0{{/grammarprefix grammar}{/the/toksa}}" );@]@; + @[TeX_( "/appendtolistx{/grammarprefix grammar}{/the/yy(1)}" );@]@; + @[TeX_( "/edef/grammarprefix{./grammarprefix}" );@]@; @ @= - @[TeX_( "/getthird{/yy(1)}/to/toksa" );@]@; /* type of the last rule */ - @[TeX_( "/getsecond{/yy(1)}/to/toksc" );@]@; /* accumulated rules */ + @[TeX_( "/getsecond{/yy(1)}/to/toksa" );@]@; /* type of the last rule */ + @[TeX_( "/getfirst{/yy(1)}/to/toksc" );@]@; /* pointer to the accumulated rules */ @[TeX_( "/getfirst{/yy(2)}/to/toksb" );@]@; /* type of the new rule */ @[TeX_( "/let/default/positionswitchdefault" );@]@; @[TeX_( "/switchon{/the/toksb}/in/positionswitch" );@]@; /* determine the position of the first token in the group */ + @; /* determine the spacing between sections */ @[TeX_( "/edef/next{/the/toksa}" );@]@; @[TeX_( "/edef/default{/the/toksb}" );@]@; /* reuse \.{\\default} */ @[TeX_( "/ifx/next/default" );@]@; @@ -818,9 +834,10 @@ attached to a rule. @[TeX_( " /let/default/separatorswitchdefaultneq" );@]@; @[TeX_( " /switchon{/the/toksa}/in/separatorswitchneq" );@]@; @[TeX_( "/fi" );@]@; - @[TeX_( "/yy0{/nx/grammar{/the/toksc/the/postoks/the/toksd/the/yy(2)}{/the/toksb}}" );@]@; + @[TeX_( "/appendtolistx{/the/toksc}{/the/postoks/the/toksd/the/yy(2)}" );@]@; + @[TeX_( "/yy0{{/the/toksc}{/the/toksb}}" );@]@; -@ @= +@ @= @[TeX_( "/getsecond{/yy(1)}/to/toksa" );@]@; /* \.{\\prodheader} */ @[TeX_( "/getsecond{/toksa}/to/toksb" );@]@; /* \.{\\idit} */ @[TeX_( "/getfourth{/toksb}/to/toksc" );@]@; /* format stream pointer */ @@ -828,90 +845,152 @@ attached to a rule. @[TeX_( "/getthird{/yy(1)}/to/toksb" );@]@; /* \.{\\rules} */ @[TeX_( "/yy0{/nx/oneproduction{/the/toksa/the/toksb}{/the/toksc}{/the/toksd}}" );@]@; -@ @= - @[TeX_( "/getfourth{/yy(1)}/to/toksa" );@]@; /* format stream pointer */ - @[TeX_( "/getfifth{/yy(1)}/to/toksb" );@]@; /* stash stream pointer */ - @[TeXb( "/yy0{/nx/pcluster{/nx/prodheader{/the/yy(1)}{/the/yy(2)}" );@]@; - @[TeXao( "{/the/toksa}{/the/toksb}}{/the/yy(4)}}" );@]@; +@ Several productions for a given nonterminal are collected in a `production cluster': +\smallskip +\thisrulereference{}% +\smallskip +\noindent The inline action does nothing at the moment and is omitted in the main text. +@= + @[TeX_( "/getfourth{$[id_colon]}/to/toksa" );@]@; /* format stream pointer */ + @[TeX_( "/getfifth{$[id_colon]}/to/toksb" );@]@; /* stash stream pointer */ + @[TeX_( "/finishlist{/the$[rhses.1]}" );@]@; /* complete the list of rules */ + @[TeXb_( "/yy0{/nx/pcluster{/nx/prodheader{/the$[id_colon]}{/the$[named_ref.opt]}" );@]@; + @[TeXfo_( " {/the/toksa}{/the/toksb}}{/nx/rules{/nx/executelist{/the$[rhses.1]}}}}" );@]@; @ It is important to format the right hand side properly, since we would like to indicate that an action is inlined by an -indentation. The `format' of the \.{\\rhs} `structure' includes the -stash pointers and a `boolean' to indicate whether the right hand side ends -with an action. Since the action can be implicit, this decision has to -be postponed until, say, a semicolon is seen. -No formatting or stash pointers are added for implicit actions. +indentation. +\smallskip +\thisrulereference{\nx\inline\nx\flatten} +\smallskip +\noindent The `layout' of the \texref{/rhs} `structure' includes +a `boolean' to indicate whether the right hand side ends with an action. Since +the action can be implicit, this decision has to be postponed until, say, +a semicolon is seen. No formatting or stash pointers are added for implicit actions. @= - @[TeX_( "/rhsbool{/yy(1)}/to/toksa /the/toksa" );@]@; - @[TeX_( "/getthird{/yy(1)}/to/toksb" );@]@; /* the format pointer */ - @[TeX_( "/getfourth{/yy(1)}/to/toksc" );@]@; /* the stash pointer */ + @[TeX_( "/initlist{/rhsesoneprefix rhses1}" );@]@; + @[TeX_( "/yy0{/rhsesoneprefix rhses1}" );@]@; + @[TeX_( "/edef/rhsesoneprefix{./rhsesoneprefix}" );@]@; + @[TeX_( "/rhsbool{$[rhs]}/to/toksa /the/toksa" );@]@; @[TeX_( "/ifrhsfull" );@]@; - @[TeX_( " /yy0{/nx/rules{/the/yy(1)}{/the/toksb}{/the/toksc}}" );@]@; - @[TeX_( "/else" );@]@; /* it does not end with an action, fake one */ - @[TeX_( " /rhscont{/yy(1)}/to/toksa" );@]@; /* rules */ - @[TeX_( " /edef/next{/the/toksa}" );@]@; - @[TeX_( " /ifx/next/empty" );@]@; - @[TeX_( " /toksa{/emptyterm}" );@]@; - @[TeX_( " /fi" );@]@; - @[TeXb( " /yy0{/nx/rules{/nx/rhs{/the/toksa/nx/rarhssep{0}{0}" );@]@; - @[TeXfo( " /nx/actbraces{}{}{0}{0}/nx/bdend}{}{/nx/rhsfulltrue}}{/the/toksb}{/the/toksc}}" );@]@; + @[TeX_( " /appendtolistx{/the/yyval}{/the$[rhs]}" );@]@; + @[TeX_( "/else" );@]@; /* right hand side does not end with an action, fake one */ + @[TeX_( " /rhscont{$[rhs]}/to/toksa" );@]@; /* rules */ + @[TeX_( " /yytoksempty/toksa{/toksa{/emptyterm}}{}" );@]@; + @[TeXb( " /appendtolistx{/the/yyval}{/nx/rhs{/the/toksa/nx/rarhssep{0}{0}" );@]@; + @[TeXfo( " /nx/actbraces{}{}{0}{0}/nx/bdend}{}{/nx/rhsfulltrue}}" );@]@; @[TeX_( "/fi" );@]@; @ Using standard notation, here is what the middle action -does. +does. The part of the rule this action applies to is given below for +reference. This action may have been omitted altogether but it serves +as a good illustration of how `inline actions' work. +\smallskip +\rulereference{\nx\inline\nx\flatten}{|@|}% +\smallskip +\noindent The terms are counted from left (deeper in the value stack) to right +(on top of the value stack) although \texref{/yy(0)} +(which is the same as \texref{/yyval}) is the {\it right\/}most term, +i.e.\ the implicit action itself. + +What the parser sees at this point +are the first two terms on the stack (i.e.\ \prodstyle{rhses.1} and +{\toksa\expandafter{\expandafter'\vl'}\expandafter\prodtstyle\expandafter{\the\toksa}}) +and is ready to make a reduction which will push +the value of the term corresponding to the inline action (i.e.\ |@|) on the stack. + +The way \bison\ does this is by +introducing a new grammar term (named \prodstyle{bogus_inline} for some integer +$n$) for each inline action and adding a new rule that reduces an +empty sequence of terms to \prodstyle{bogus_inline}. The action for this rule is +the inline action. In our case this would read as +\begingroup +\medskip +\def\skipalltoks#1\par{} +\def\preparsefallbacktext#1{% + \let\postparse\relax + \message{#1}% + \skipalltoks +} + +\extendswitch\multicharswitch\at\stashed\by\PB\to\multicharswitchadjust +\let\multicharswitch\multicharswitchadjust +\def\textproductionsetup{% + \rulereftextproductionsetup + \let\acharswitch\texcharadjust + \let\onecharswitch\texcsadjust +}% +\beginprod +\inline\flatten + bogus_inline: + \{|@|\} +\endprod +\medskip +\endgroup +\noindent$\ldots$except the parser knows what the state of the stack is at this +point and thus the code inside |@| can now refer +to the terms on the stack as described above. @= - @[TeX_( "/rhscont{/yy(1)}/to{/yy(0)}" );@]@; - @[TeX_( "/yy0{/the/yy(0)/nx/midf/the/yy(2)}" );@]@; + @[TeX_( "/appendtolistx{/the/yy(1)}{/nx/midf/the/yy(2)}" );@]@; @ However, if the length of the rule preceding the inline action -is not known a different way of accessing the stack is necessary. -@= +is not known to the parser in advance (as is the case for the parsers +\splint\ generates using any version of \bison\ that is $\geq3.0$) +a different way of accessing the stack is necessary. This notation is also more +natural as it counts the terms from right to left, i.e.\ `into the depths +of the stack' (for example \texref{/bb2\{\}} is the register holding the value +of~\prodstyle{rhses1}). It is worth noting that in this case +\texref{/yy(0)} and \texref{/yyval} are still the same +register, the one that holds the value of the term corresponding to +the inline action itself. +@= @[TeX_( "/bb2{/toksa}/bb1{/toksb}" );@]@; - @[TeX_( "/rhscont{/toksa}/to{/yy(0)}" );@]@; - @[TeX_( "/yy0{/the/yy(0)/nx/midf/the/toksb}" );@]@; - -@ @= - @[TeX_( "/rhsbool{/yy(4)}/to/toksa /the/toksa" );@]@; - @[TeX_( "/ifrhsfull" );@]@; - @[TeX_( " /yy0{/nx/rules{/the/yy(3)/nx/rrhssep/the/yy(2)/the/yy(4)}/the/yy(2)}" );@]@; - @[TeX_( "/else" );@]@; - @[TeX_( " /rhscont{/yy(4)}/to/toksa" );@]@; - @[TeX_( " /edef/next{/the/toksa}" );@]@; - @[TeX_( " /ifx/next/empty" );@]@; - @[TeX_( " /toksa{/emptyterm}" );@]@; - @[TeX_( " /fi" );@]@; - @[TeXb( " /yy0{/nx/rules{/the/yy(3)/nx/rrhssep/the/yy(2)" );@]@; - @[TeXf( " /nx/rhs{/the/toksa/nx/rarhssep{0}{0}" );@]@; /* streams have already been grabbed */ - @[TeXfo( " /nx/actbraces{}{}{0}{0}/nx/bdend}{}{/nx/rhsfulltrue}}/the/yy(2)}" );@]@; - @[TeX_( "/fi" );@]@; + @[TeX_( "/appendtolistx{/the/toksa}{/nx/midf/the/toksb}" );@]@; -@ No pointers are provided for an {\it implicit\/} action. Processing a set of rules involves a large number of -reexpansions. This seems to be a good place to use an array to store {\sc AST} nodes ({\let\writetexidxentry\writetextxtidxentry -\def\texnspace{texline}\def\texispace{index}\inlineTeXx{/astarray}}). While +@ Finally, using the `native' way of referring to term values results +in the most natural code. In this case, one can mix numeric and +symbolic references for both implicit and explicit rules. +@= + @[TeX_( "/appendtolistx{/the$[rhses]}{/nx/midf/the$[mid]}" );@]@; + +@ Productions are collected in a `productions cluster' (not an official term) by the +following action: +\smallskip +\thisrulereference{\nx\inline\nx\flatten} +\smallskip\noindent +As can be seen in the code below, no pointers are provided for an {\it implicit\/} +action (since there are no tokens associated with it). + +Processing a set of rules involves a large number of +reexpansions. This seems to be a good place to use a list to store the nodes +(see \.{yycommon.sty} for details on list macros). While providing a noticeable speed up, this technique significantly complicates the debugging of the grammar. In particular, inspecting a -parsed table supplies very little information if the {\sc AST} nodes are not +parsed table supplies very little information if the list not expanded. The macros in \.{yyunion.sty} provide a special debugging namespace where the expansion of the parser produced control sequences may be modified to safely expand the generated table. + +The code below relies on the inline action |@| above +to store the relevant information from \texref{/yy(1)} (corresponding to +\prodstyle{rhses1}) in \texref{/yy(3)} (which is +the inline action `term' \inlineactionsymbol\ in the production above). +@q Note that one cannot use \prodstyle{...} above to display \inlineactionsymbol@> +@q since the \prodstyle{...} macro relies on the name parser. See yyunion.sty @> +@q for further details about the special terms like this. @> @= @[TeX_( "/rhsbool{/yy(4)}/to/toksa /the/toksa" );@]@; @[TeX_( "/ifrhsfull" );@]@; - @[TeX_( " /yypushx{/the/yy(3)/nx/rrhssep/the/yy(2)/the/yy(4)}/on/astarray" );@]@; + @[TeX_( " /appendtolistx{/the/yy(1)}{/nx/rrhssep/the/yy(2)/the/yy(4)}" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /rhscont{/yy(4)}/to/toksa" );@]@; - @[TeX_( " /edef/next{/the/toksa}" );@]@; - @[TeX_( " /ifx/next/empty" );@]@; - @[TeX_( " /toksa{/emptyterm}" );@]@; - @[TeX_( " /fi" );@]@; - @[TeXb( " /yypushx{/the/yy(3)/nx/rrhssep/the/yy(2)" );@]@; + @[TeX_( " /yytoksempty/toksa{/toksa{/emptyterm}}{}" );@]@; + @[TeXb( " /appendtolistx{/the/yy(1)}{/nx/rrhssep/the/yy(2)" );@]@; @[TeXf( " /nx/rhs{/the/toksa/nx/rarhssep{0}{0}" );@]@; /* streams have already been grabbed */ - @[TeXfo( " /nx/actbraces{}{}{0}{0}/nx/bdend}{}{/nx/rhsfulltrue}}/on/astarray" );@]@; + @[TeXfo( " /nx/actbraces{}{}{0}{0}/nx/bdend}{}{/nx/rhsfulltrue}}" );@]@; @[TeX_( "/fi" );@]@; - @[TeX_( "/yy0{/nx/rules{/astarraylastcs}/the/yy(2)}" );@]@; - -@ @= - @@; + @[TeX_( "/yy0{/the/yy(1)}" );@]@; @ @= @G @@ -942,33 +1021,46 @@ named_ref.opt: ; @g -@ \saveparseoutputfalse +@ The simplest form of the right hand side is an empty rule. In this case the parser +must make a reduction based on the lookahead only (or the current state), i.e.\ no +tokens are consumed from the input. +\saveparseoutputfalse @= @[TeX_( "/yy0{/nx/rhs{}{}{/nx/rhsfullfalse}}" );@]@; -@ @= +@ Adding a \bison\ term to the right hand side involves collecting of several pieces of information. +One of them is the (optional) symbolic named that can be used by the action code to refer to +the place on the value stack that is allocated for this term. +\smallskip +\thisrulereference{\nx\inline\nx\flatten}% +\smallskip +\noindent The space between the term and the preceeding part of the rule may depend on the +type of rule element that appears at the end of the rule parsed so far. +@= @[TeX_( "/rhscont{/yy(1)}/to/toksa" );@]@; @[TeX_( "/rhscnct{/yy(1)}/to/toksb" );@]@; - @[TeX_( "/edef/next{/the/toksb}" );@]@; - @[TeX_( "/ifx/next/empty" );@]@; - @[TeX_( "/else" );@]@; + @[TeX_( "/yytoksempty/toksb{}{" );@]@; @[TeX_( " /getfourth{/yy(2)}/to/toksc" );@]@; @[TeX_( " /getfifth{/yy(2)}/to/toksd" );@]@; @[TeX_( " /appendr/toksb{{/the/toksc}{/the/toksd}}" );@]@; - @[TeX_( "/fi" );@]@; + @[TeX_( "}" );@]@; @[TeXb( "/yy0{/nx/rhs{/the/toksa/the/toksb" );@]@; @[TeXao( "/nx/termname{/the/yy(2)}{/the/yy(3)}}{/nx/hspace}{/nx/rhsfullfalse}}" );@]@; -@ @= +@ Action processing is somewhat complicated since the action can be either inline or terminal, +affecting the typesetting. +\smallskip +\thisrulereference{\nx\inline\nx\flatten}% +\smallskip +\noindent Additionally, an action may follow an empty rule in which case a special term +must be added to aid the reader. +@= @[TeX_( "/rhscont{/yy(1)}/to/toksa" );@]@; @[TeX_( "/rhsbool{/yy(1)}/to/toksb /the/toksb" );@]@; @[TeX_( "/ifrhsfull" );@]@; /* the first half ends with an action */ @[TeX_( " /appendr/toksa{/nx/arhssep{0}{0}/nx/emptyterm}" );@]@; /* no pointers to streams */ @[TeX_( "/fi" );@]@; - @[TeX_( "/edef/next{/the/toksa}" );@]@; - @[TeX_( "/ifx/next/empty" );@]@; - @[TeX_( " /toksa{/emptyterm}" );@]@; - @[TeX_( "/fi" );@]@; + @[TeX_( "/yytoksempty/toksa{/toksa{/emptyterm}}{}" );@]@; @[TeX_( "/getfirst{/yy(2)}/to/toksb" );@]@; /* the contents of the braced code */ @[TeX_( "/getsecond{/yy(2)}/to/toksc" );@]@; /* the format stream pointer */ @[TeX_( "/getthird{/yy(2)}/to/toksd" );@]@; /* the stash stream pointer */ @@ -982,10 +1074,7 @@ named_ref.opt: @[TeX_( "/ifrhsfull" );@]@; /* the first half ends with an action */ @[TeX_( " /appendr/toksa{/nx/arhssep{0}{0}/nx/emptyterm}" );@]@; /* no pointers to streams */ @[TeX_( "/fi" );@]@; - @[TeX_( "/edef/next{/the/toksa}" );@]@; - @[TeX_( "/ifx/next/empty" );@]@; - @[TeX_( " /toksa{/emptyterm}" );@]@; - @[TeX_( "/fi" );@]@; + @[TeX_( "/yytoksempty/toksa{/toksa{/emptyterm}}{}" );@]@; @[TeX_( "/getfirst{/yy(2)}/to/toksb" );@]@; /* the contents of the braced code */ @[TeX_( "/getsecond{/yy(2)}/to/toksc" );@]@; /* the format stream pointer */ @[TeX_( "/getthird{/yy(2)}/to/toksd" );@]@; /* the stash stream pointer */ @@ -993,16 +1082,17 @@ named_ref.opt: @[TeXf( " /nx/bpredicate{/the/toksb}{}{/the/toksc}{/the/toksd}/nx/bdend}" );@]@; @[TeXao( "{/nx/arhssep}{/nx/rhsfulltrue}}" );@]@; -@ @= +@ An empty right hand side may be specified explicitly by using \prodstyle{\%empty} as +the sole token in the production. This will increase the readability of the grammar by +making the programmer's intentions more transparent. +@= @[TeX_( "/rhscont{/yy(1)}/to/toksa" );@]@; @[TeX_( "/rhscnct{/yy(1)}/to/toksb" );@]@; - @[TeX_( "/edef/next{/the/toksb}" );@]@; - @[TeX_( "/ifx/next/empty" );@]@; - @[TeX_( "/else" );@]@; + @[TeX_( "/yytoksempty/toksb{}{" );@]@; @[TeX_( " /getfourth{/yy(2)}/to/toksc" );@]@; @[TeX_( " /getfifth{/yy(2)}/to/toksd" );@]@; @[TeX_( " /appendr/toksb{{/the/toksc}{/the/toksd}}" );@]@; - @[TeX_( "/fi" );@]@; + @[TeX_( "}" );@]@; @[TeXb( "/yy0{/nx/rhs{/the/toksa/the/toksb" );@]@; @[TeXao( "/nx/emptyterm}{/nx/hspace}{/nx/rhsfullfalse}}" );@]@; @@ -1045,13 +1135,17 @@ named_ref.opt: @[TeXao( "/nx/mergeop{/nx/tagit/the/yy(3)}/the/yy(2)}{/the/toksb}{/nx/rhsfullfalse}}" );@]@; @[TeX_( "/fi" );@]@; + @t}\beginfoldedsections{@> + @ @= @[TeX_( "/yy0{}" );@]@; @ @= @@; -@ Identifiers. + @t}\endfoldedsections{@> + +@*2 Identifiers and other symbols. {\it Identifiers are returned as |uniqstr| values by the scanner. Depending on their use, we may need to make them genuine symbols}. We, on the other hand, simply copy the values returned by the scanner. @@ -1095,6 +1189,7 @@ string_as_id: placeholders for the appropriate actions in case the parser gains some sophistication in processing low level types (or starts expecting different types from the scanner). +\beginfoldedsectionshere @= @[TeX_( "/yy0{/nx/idit/the/yy(1)}" );@]@; @@ -1113,6 +1208,8 @@ different types from the scanner). @ @= @[TeX_( "/yy0{/nx/stringify/the/yy(1)}" );@]@; +@t}\endfoldedsections{@> + @ {\it Variable and value. The \prodstyle{STRING} form of variable is deprecated and is not \.{M4}-friendly. For example, \.{M4} fails for \.{\%define "[" "value"}.} @@ -1151,8 +1248,6 @@ as they have to be inserted in a place that is aware of the internal definitions definitions are used. @= -#define YYPRINT(file, type, value) @[yyprint (file, type, value)@] - static void yyprint (FILE *file, int type, YYSTYPE value){} @ @= @@; @@ -1183,8 +1278,15 @@ token information from the grammar. @q _register_token_d(SEMICOLON) /* can be omitted in prologue */ @> @q _register_token_d(TAG) /* only encountered in the definition of PERCENT_PARAM */ @> -@ Union of types. This section of the \bison\ input lists the types +@*1 Union of types. This section of the \bison\ input lists the types that may appear on the value stack. Since \TeX\ does not provide any mechanism for type checking (nor is it clear how to translate a \Cee\ -|union| into any data structure usable in \TeX), this section is left empty. +|union| into any data structure usable in \TeX), this section is left (nearly) +empty. The reason for the lonely type below is the postprocessor that facilitates +the use of \bison\ `native' term references (see elsewhere). In order to +translate such references into appropriate \TeX\ code, the postprocessor +must let \bison\ calculate offsets into the value stack, which requires +assigning types to various terminals and non-terminals. The specific type +has no significance. @= + int intval; \ No newline at end of file diff --git a/support/splint/cweb/bs.w b/support/splint/cweb/bs.w index adefd23f8b..8b32617ef3 100644 --- a/support/splint/cweb/bs.w +++ b/support/splint/cweb/bs.w @@ -1,4 +1,4 @@ -@q Copyright 2012-2020, Alexander Shibakov@> +@q Copyright 2012-2024, Alexander Shibakov@> @q This file is part of SPLinT@> @q SPLinT is free software: you can redistribute it and/or modify@> @@ -31,7 +31,6 @@ be done here. _register_table_d(yypgoto)@; _register_table_d(yytable)@; _register_table_d(yycheck)@; - _register_table_d(yytoknum)@; _register_table_d(yystos)@; _register_table_d(yytname)@; _register_table_d(yyprhs)@; @@ -46,8 +45,13 @@ with version~\.{3.0}) does not generate |yyprhs| and |yyrhs| or any other arrays that contain similar information, so we fake them here if such a crippled version of \bison\ is used. +The |yyrimplicit| array will be used by the table output code, together with +the postprocessor to output right hand side lengths for the term references that +require them in the case when the `native' \bison\ references are +used. @= unsigned int yyrthree[YYNRULES + 1] = { 0 }; + int yyrimplicit[YYNRULES + 1] = { 0 }; #ifdef BISON_IS_CRIPPLED unsigned int yyrhs[YYNRULES + 1] = { -1 }; unsigned int yyprhs[YYNRULES + 1] = { 0 }; @@ -102,6 +106,23 @@ such a crippled version of \bison\ is used. @= _register_table_d(yyrthree)@; +@ We list some macros that are used to assist the post +processor and take advantage of the |yyrimlicit| array. As at this +time the size of the array is unknown (the preamble is included before +the parser file by \.{mkeparser.w} so the number of rules is unknown +at this point), we declare the array as a pointer. +@d BZ( term, anchor ) ( ((YYSTYPE *)&(term)) - ((YYSTYPE *)&(anchor)) + 1 ) +@d BZZ( term, anchor ) ( + (yyrimplicit_p[yyn] = ((yyrimplicit_p[yyn] < 0) ? + yyrimplicit_p[yyn] : ((YYSTYPE *)&(term)) - ((YYSTYPE *)&(anchor)) + 1)), + ((YYSTYPE *)&(term)) - ((YYSTYPE *)&(anchor)) + 1 +) +@<\Cee\ setup code specific to \bison@>= + int *yyrimplicit_p; + +@ @= + yyrimplicit_p = yyrimplicit; + @*2Actions. There are several ways of making |yyparse()| execute all portions of the action code. The one chosen here makes sure that none of the tables gets written past its last element. To see how it works, it @@ -154,6 +175,7 @@ change affects the generated parser. yyr1[i] = YYNTOKENS; yydefact[0] = i; + yyrimplicit[i] = -yyr2[i]; yyr2[i] = 0; yyparse(YYPARSE_PARAMETERS); @@ -173,18 +195,32 @@ change affects the generated parser. } + for ( int i = 1; i < YYNRULES + 1; i++ ) { + + if ( yyrimplicit[i] > 0 ) { + fprintf( tables_out, "\\yyimplicitlengthset{%d}{%d}%%\n", i, yyrimplicit[i] ); + } + + } + @*2Constants. A generic list of constants to be used later in different contexts is defined below. As before, the appropriate macro will be defined generically to do what is required with these names (for example, we can turn each name into a string for reporting purposes). @= _register_const_d(YYEMPTY)@; _register_const_d(YYPACT_NINF)@; - _register_const_d(YYEOF)@; _register_const_d(YYLAST)@; _register_const_d(YYNTOKENS)@; _register_const_d(YYNRULES)@; _register_const_d(YYNSTATES)@; _register_const_d(YYFINAL)@; +#ifndef YYEOF + _register_const_d(YYSYMBOL_YYEOF)@; +#endif + +@ Constants defined to maintain compatibility with the older versions of \bison. +@= + _register_const_d(YYSYMBOL_YYEOF, YYEOF)@; @*2Tokens. Similar techniques are employed in token output. Tokens are parser @@ -582,20 +618,32 @@ rules are not output if a crippled \bison\ is used. @ \TeX\ constant output is another place where the techniques described above are applied. As before, the macro handles the repetitive work of initialization, declaration, etc in -each place where the corresponding constant is mentioned. The one exception is \.{YYPACT\_NINF}, -which has to be handled separately because the underscore in its name makes it difficult to -use it as a command sequence name. +each place where the corresponding constant is mentioned. The exceptions are \.{YYPACT\_NINF} +and \.{YYSYMBOL\_YYEOF} that have to be handled separately because the +underscore in its name makes it difficult to use it as a command sequence name. \def\YYPACTxNINFxdesc{\.{YYPACT\_NINF\_}\\{desc}} +\def\YYSYMBOLxYYEOFxdesc{\.{YYSYMBOL\_YYEOF\_}\\{desc}} @s YYPACT_NINF_desc TeX +@s YYSYMBOL_YYEOF_desc TeX @= #define _register_const_d(c_name) @[c_name##_desc.format = "\\constset{%s}{%d}%%\n"; \ c_name##_desc.name = #c_name; \ + c_name##_desc.value = c_name; \ output_desc.output_##c_name = 1;@] @@; #undef _register_const_d +#ifdef YYEOF /* other values have already been set correctly */ +#define _register_const_d(c_name,vvalue) @[c_name##_desc.format = "\\constset{%s}{%d}%%\n"; \ + c_name##_desc.name = #c_name; \ + c_name##_desc.value = vvalue; \ + output_desc.output_##c_name = 1;@] + @@; +#undef _register_const_d +#endif YYPACT_NINF_desc.name = "YYPACTNINF"; +YYSYMBOL_YYEOF_desc.name = "YYSYMBOLxYYEOF"; @ Token definitions round off the \TeX\ output mode. diff --git a/support/splint/cweb/checklists.w b/support/splint/cweb/checklists.w index 754855d747..446bc46b96 100644 --- a/support/splint/cweb/checklists.w +++ b/support/splint/cweb/checklists.w @@ -1,4 +1,4 @@ -% Copyright 2012-2020, Alexander Shibakov +% Copyright 2012-2022, Alexander Shibakov % Copyright 2002-2014 Free Software Foundation, Inc. % This file is part of SPLinT % diff --git a/support/splint/cweb/common.w b/support/splint/cweb/common.w index 0f50fdcabd..5112fb5414 100644 --- a/support/splint/cweb/common.w +++ b/support/splint/cweb/common.w @@ -1,4 +1,4 @@ -@q Copyright 2012-2020, Alexander Shibakov@> +@q Copyright 2012-2024, Alexander Shibakov@> @q This file is part of SPLinT@> @q SPLinT is free software: you can redistribute it and/or modify@> @@ -454,6 +454,19 @@ code easier to look at. Further explanation is given in the grammar file. If the parser is doing its job, this is the only place where one would actually see these as functions (or, rather, macros). +In case one wishes to use the `native' \bison\ way of referencing +terms (i.e.\ something along the lines of~\.{\\the\char`\$[term]}) +these macros should be used with a trailing underscore (say, \.{TeXa\_}) +to let the postprocessor know that the code inside should be +postprocessed. The postprocessor will then create three files: one, +destined for \CWEAVE, will use the same macro withough the underscore +(i.e.\ \.{TeXa} to continue our example, and have the native \bison\ +terms replaced wih the appropriate \TeX\ commands. Another file is +intended for \CTANGLE, where the whole macro will be replaced first +with a special identifier, which in turn, after \CTANGLE\ finishes, +will be replaced by an appropriately constructed call to \.{TeX\_\_}. The +third file will contain the substitutions. + In compliance with paragraph 6.10.8(2)\footnote{[$\ldots$] {\it Any other predefined macro names shall begin with a leading underscore followed by an uppercase letter or a second underscore.}} of the \ISO\ @@ -482,7 +495,7 @@ macros which produces undesirable typesetting artefacts.}. @q \CWEB\ is not aware of variadic macros, so this has to be done the old way@> @<\Cee\ preamble@>= -#define TeX__( string, ... ) @[fprintf( tables_out, " " string "%s\n", __VA_ARGS__, "%" )@] +#define TeX__( string, ... ) @[fprintf( tables_out, " " string "%%\n", __VA_ARGS__ )@] @ If a full parser is not needed, the lexing mechanism is not required. To satisfy the compiler and the linker, the lexer and other functions still have to be declared and defined, since these functions @@ -524,27 +537,32 @@ values. When the names are concatenated with other tokens, however, the \Cee\ preprocessor postpones the macro expansion until the concatenation is complete (see clauses 6.10.3.1, 6.10.3.2, and 6.10.3.3 of the \ISO\ \Cee\ Standard, \cite[ISO/C11]). Unless the result of the -concatenation is still expandable, the expansion will halt. +concatenation is still expandable, the expansion will halt\footnote{Another trick +to halt expansion is to use {\it function macros} which will expand only when +they are followed by parentheses. Since we do not have control over how +constants are defined by \bison, we cannot take advantage of this feature of the +\Cee\ preprocessor.}. @= struct const_d { char *format; char *name; + int value; }; @ @= -#define _register_const_d(c_name) @[struct const_d c_name##_desc;@] +#define _register_const_d(c_name,...) @[struct const_d c_name##_desc;@] @@; #undef _register_const_d @ @= -#define _register_const_d(c_name) @[bool output_##c_name:1;@] +#define _register_const_d(c_name,...) @[bool output_##c_name:1;@] @@; #undef _register_const_d @ @= -#define _register_const_d(c_name) @[@[@].output_##c_name = 0,@[@]@] +#define _register_const_d(c_name,...) @[@[@].output_##c_name = 0,@[@]@] @@; #undef _register_const_d @@ -556,10 +574,10 @@ concatenation is still expandable, the expansion will halt. { int any_constants = 0; -#define _register_const_d(c_name) \ +#define _register_const_d(c_name,...) \ \ if ( output_desc.output_##c_name ) { \ - const_out( tables_out, c_name##_desc, c_name)@; \ + const_out( tables_out, c_name##_desc)@; \ any_constants = 1; \ } @@ -575,7 +593,7 @@ concatenation is still expandable, the expansion will halt. @= @ A macro to help with constant output. -@d const_out(stream, c_desc, c_name) fprintf(stream, c_desc.format, c_desc.name, c_name); +@d const_out(stream, c_desc) fprintf(stream, c_desc.format, c_desc.name, c_desc.value); @ Action switch output routines modify the automata tables and therefore have to be output last. Since action output is highly @@ -728,7 +746,7 @@ specific cases are added to in the course of adding new features. FOREVER { - c = getopt_long (argc, argv, ( char [] ){':'@t, @>@}, long_options, &option_index); + c = getopt_long (argc, argv, ( char [] )@[{':'@t, @>@}@], long_options, &option_index); if (c == -1) break; diff --git a/support/splint/cweb/fk.w b/support/splint/cweb/fk.w index fc0c5d2e14..c25a7e8cc2 100644 --- a/support/splint/cweb/fk.w +++ b/support/splint/cweb/fk.w @@ -1,4 +1,4 @@ -@q Copyright 2012-2020, Alexander Shibakov@> +@q Copyright 2012-2022, Alexander Shibakov@> @q This file is part of SPLinT@> @q SPLinT is free software: you can redistribute it and/or modify@> @@ -330,6 +330,7 @@ known to the \flex\ generated scanner. } @*2Constants. +The few hard coded constants needed for the lexer to work are listed here. @= _register_const_d(YY_END_OF_BUFFER_CHAR)@; _register_const_d(YY_NUM_RULES)@; @@ -427,6 +428,7 @@ are handled separately, because they contain underscores. @= #define _register_const_d(c_name) @[c_name##_desc.format = "\\constset{%s}{%d}%%\n"; \ c_name##_desc.name = #c_name; \ + c_name##_desc.value = c_name; \ output_desc.output_##c_name = 1;@] @@; #undef _register_const_d diff --git a/support/splint/cweb/fo.w b/support/splint/cweb/fo.w index 81694024c3..d34ca57d96 100644 --- a/support/splint/cweb/fo.w +++ b/support/splint/cweb/fo.w @@ -30,14 +30,23 @@ @q PURPOSE. @> @**The \ifbootstrapmode flex \else\flex\ \fi parser stack. -\ifbootstrapmode % this is a bootstrap run to generate the tables +\ifbootstrapmode % this is a bootstrap run to generate the token references \input limbo.sty \def\optimization{5} \input yy.sty + \def\bstrapparser{dyytab.tex}% use the full prologue parser + \def\bstraptokens{bo.tok}% for which we will need token equivalences \modebootstrap \else % otherwise set up the pretty printing of tokens \let\hostparsernamespace\flexnamespace \fi +% we can get away with the setup above because the minimal lexer +% used for bootstrapping does not know about the \prodstyle{\%left} +% token so in the declarations list below, the two tokens, +% \prodstyle{CCL_OP_DIFF} and \prodstyle{CCL_OP_UNION} become +% part of the previous \prodstyle{\%token} declaration which is a +% legal declaration syntax; see ldman.w and ldlex.w and ldgram.w for +% a more elaborate setup; The scanner generator, \flex, uses \bison\ to produce a parser for its input language. Its lexer is output by \flex\ itself so both are reused to generate the parser and the scanner for pretty printing @@ -69,7 +78,7 @@ any custom adjustments to the lexer state to operate correctly. @g @ The selection of options for \bison\ parsers suitable for \splint\ -have been discussed +has been discussed \ifbootstrapmode\else\locallink{bison.options}earlier \endlink\fi so we list them here without further comments. @= @@ -157,7 +166,7 @@ point of recognition, while the typesetting parser needs to be aware of them. @G %token TOP_OP POINTER_OP ARRAY_OP DEF_OP RE_DEF OPT_OTHER OPT_DEPRECATED -@ {\em \POSIX\ and \.{AT\&T} \lex\ place the +@ \namedspot{flex braces}{\em \POSIX\ and \.{AT\&T} \lex\ place the precedence of the repeat operator, \.{\{\}}, below that of concatenation. Thus, \.{ab\{3\}} is\/ \.{ababab}. Most other \POSIX\ utilities use an {\rm Extended Regular Expression (ERE)} precedence that has the repeat operator @@ -166,8 +175,8 @@ higher than concatenation. This causes \.{ab\{3\}} to yield\/ \.{abbb}. In order to support the \POSIX\ and \.{AT\&T} precedence and the \flex\ precedence we define two token sets for the begin and end tokens of the repeat operator, \prodstyle{BEGIN_REPEAT_POSIX} and\/ \prodstyle{END_REPEAT_POSIX}. The lexical scanner chooses -which tokens to return based on whether {\let\it\itbold\prodstyle{posix\_compat} or \prodstyle{lex\_compat} -are specified. Specifying either \prodstyle{posix\_compat} or \prodstyle{lex\_compat}} will +which tokens to return based on whether {\let\it\itbold\prodstyle{posix_compat} or \prodstyle{lex_compat} +are specified. Specifying either \prodstyle{posix_compat} or \prodstyle{lex_compat}} will cause \flex\ to parse scanner files as per the \.{AT\&T} and \POSIX-mandated behavior.} @= @G @@ -186,6 +195,7 @@ explanation). We can nevertheless get away with an empty \Cee\ preamble. @ @= @G +@t}\vb{\insertraw{\beginfoldedsections}}{@> @t}\vb{\inline\flatten}{@> goal: initlex sect1 sect1end @@ -202,12 +212,15 @@ initlex: @g @ @= - @[TeX_( "/yy0{/the/yy(2)/the/yy(4)}" );@]@; + @[TeX_( "/finishlist{/the/yy(4)}" );@]@; + @[TeX_( "/yy0{/the/yy(2)/nx/executelist{/the/yy(4)}}" );@]@; @ @= @@; @@; +@t}\endfoldedsections{@> + @ @= @G @t}\vb{\inline\flatten}{@> @@ -220,6 +233,7 @@ goal: @ @= @G +@t}\vb{\insertraw{\beginfoldedsections}}{@> sect1: sect1 startconddecl namelist1 {@> @ @=} | sect1 options {@> @ @=} @@ -266,8 +280,11 @@ namelist1: @ @= @[TeX_( "/yyerror" );@]@; +@t}\endfoldedsections{@> + @ @= @G +@t}\vb{\insertraw{\beginfoldedsections}}{@> options: OPTION_OP optionlist {@> @ @=} | POINTER_OP {@> @ @=} @@ -338,15 +355,19 @@ option: @ @= @[TeX_( "/yy0{/nx/flopt{deprecated}/the/yy(1)}" );@]@; +@t}\endfoldedsections{@> + @ @= @G +@t}\vb{\inline\flatten}{@> goal: sect2 {@> @ @=} ; @g @ @= - @[TeX_( "/table/yy(1)" );@]@; + @[TeX_( "/finishlist{/the/yy(1)}" );@]@; + @[TeX_( "/table/expandafter{/expandafter/executelist/expandafter{/the/yy(1)}}" );@]@; @ This portion of the grammar was changed to make it possible to read the action code. @@ -364,25 +385,54 @@ initforrule: ; @g -@ @= +@ The production below describes the most typical way a regular expression is +assigned an action. The redundant term \prodstyle{initforrule} is a standard +\bison\ trick to make sure that the appropriate initializations happen at +the right time. +\smallskip +\thisrulereference{\nx\inline\nx\flatten} +\smallskip\noindent +The original production has been modified so that the pretty printing parser has a chance +to consume the action code. The second \prodstyle{'\\n'} is output by the action +processing code. +@= @[TeX_( "/ifflcontinued@@action" );@]@; @[TeX_( " /toksb{/flactionc}" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /toksb{/flaction}" );@]@; @[TeX_( "/fi" );@]@; @[TeX_( "/toksa/expandafter{/astformat@@flaction}" );@]@; /* capture the formatting action */ - @[TeX_( "/yypushx{/the/yy(1)/the/toksb{/the/yy(2)}{/the/yy(4)}/the/yy(5)/the/yy(6){/the/toksa}}/on/astarray" );@]@; - @[TeX_( "/yy0{/astarraylastcs}" );@]@; + @[TeX_( "/yy0{/the/yy(1)}" );@]@; + @[TeX_( "/appendtolistx{/the/yy(1)}{/the/toksb{/the/yy(2)}{/the/yy(4)}/the/yy(5)/the/yy(6){/the/toksa}}" );@]@; @[TeX_( "/let/astformat@@flaction/empty" );@]@; /* reset the format */ -@ @= - @[TeX_( "/yy0{/the/yy(1)/nx/flactiongroup{/the/yy(2)}/the/yy(3){/the/yy(4)}/the/yy(5)}" );@]@; +@ For convenience, rules that are active in the same set of states may be grouped together. +This pattern is the subject of the next production. +\smallskip +\thisrulereference{\nx\inline\nx\flatten} +\smallskip\noindent +The original parser ignores the braces while the pretty printing parser +uses the pointers associated with the braces to collect and process the accumulated +stash. This is how comments and \CWEB\ section references are typeset. +@= + @[TeX_( "/yy0{/the/yy(1)}" );@]@; + @[TeX_( "/finishlist{/the/yy(4)}" );@]@; + @[TeX_( "/appendtolistx{/the/yy(1)}{/nx/flactiongroup{/the/yy(2)}/the/yy(3){/nx/executelist{/the/yy(4)}}/the/yy(5)}" );@]@; -@ @= - @[TeX_( "/yy0{}" );@]@; +@ Simple left recursive terms like~\prodstyle{sect2} are very suitable for being implemented as a list +(see the macros in \.{yycommon.sty} for the details on the list implementation). The `type' of~\prodstyle{sect2} +is a (symbolic pointer to a) list of items built up from an empty initial list. This production initializes +the list (with the name identical to the terminal on the left hand side of the production) +and updates the list name (rather the name's prefix) for future invocations of this action. + +@= + @[TeX_( "/initlist{/secttwoprefix sect2}" );@]@; + @[TeX_( "/yy0{/secttwoprefix sect2}" );@]@; + @[TeX_( "/edef/secttwoprefix{/secttwoprefix.}" );@]@; @ @= - @[TeX_( "/yy0{/the/yy(1)/nx/flbareaction/the/yy(2)}" );@]@; + @[TeX_( "/yy0{/the/yy(1)}" );@]@; + @[TeX_( "/appendtolistx{/the/yy(1)}{/nx/flbareaction/the/yy(2)}" );@]@; @ @= @G @@ -400,14 +450,23 @@ scon: namelist2: namelist2 ',' sconname {@> @ @=} | sconname {@> @ @=} - | error {@> @ @=} + | error {@> @ @=} ; @t}\vb{\inline\flatten}{@> sconname: NAME {@> @ @=} ; -@ @= +@ Start conditions are just names. The data structure that is output has +location pointers for the streams to enable interaction with \CWEB. These +pointers are in turn the values of the angle bracket tokens that enclose the +list of start conditions. + +Start condition lists may be collected in their own sections, while the list itself +may be followed by a comment. The pointers mentioned above are used to typeset the comments +and section references. +\beginfoldedsectionshere +@= @[TeX_( "/yy0{/nx/flsconlist{/the/yy(1)}{/the/yy(3)}{/the/yy(4)}}" );@]@; @ @= @@ -422,17 +481,24 @@ sconname: @ @= @@; -@ @= +@ @= @[TeX_( "/yyerror" );@]@; @ @= @[TeX_( "/yy0{/nx/flname/the/yy(1)}" );@]@; -@ @= +@t}\endfoldedsections{@> + +@*1 The syntax of regular expressions. The productions in this section define the +syntax of \flex\ regular expressions in detail. The same productions are used for +parsing isolated regular expressions (e.g.\ to present example code). A few of these +productions have been modified to suit the needs of the pretty printing parser. +@= @@; @ @= @G +@t}\vb{\inline\flatten}{@> goal: flexrule {@> @ @=} ; @@ -446,33 +512,48 @@ ensures that all the changes are local to the parsing macro. @= @[TeX_( "/table/yy(1)" );@]@; -@ @= +@ Regular expressions are parsed using the following productions. There are +two major cases: rules active only at the beginning of the line, and the rest. From the +typesetting parser's point of view, there is not much difference between the two +(certainly not enough to justify singling out the rules at the beginning of the line into +their own production) but it was decided to keep the original grammar rules +for consistency. +@= @G +@t}\vb{\insertraw{\beginfoldedsections}}{@> flexrule: - '^' rule {@> @ @=} + '^' rule {@> @ @=} | rule {@> @ @=} | EOF_OP {@> @ @=} | error {@> @ @=} ; -@ @= +@ @= @[TeX_( "/toksa/expandafter{/astformat@@flrule}" );@]@; @[TeX_( "/let/astformat@@flrule/empty" );@]@; @[TeX_( "/yy0{/nx/flbolrule{/the/yy(2)}{/the/toksa}}" );@]@; +@ @= + @[TeX_( "/yy0{/nx/fleof/the/yy(1)}" );@]@; + @ @= @[TeX_( "/toksa/expandafter{/astformat@@flrule}" );@]@; @[TeX_( "/let/astformat@@flrule/empty" );@]@; @[TeX_( "/yy0{/nx/flrule{/the/yy(1)}{/the/toksa}}" );@]@; -@ @= - @[TeX_( "/yy0{/nx/fleof/the/yy(1)}" );@]@; - @ @= @[TeX_( "/yyerror" );@]@; - -@ @= + +@t}\endfoldedsections{@> + +@ Another broad overview of regular expression types before diving into the details +of various operations. Note that the only trailing context that \splint\ output +lexer can process is the end of line (\prodstyle{'\$'}) due to the way the +scanner routine is written. It does not affect its ability to pretty print the appropriate +rules (for a lexer that is produced by \flex\ itself, for example). +@= @G +@t}\vb{\insertraw{\beginfoldedsections}}{@> rule: re2 re {@> @ @=} | re2 re '$' {@> @ @=} @@ -511,9 +592,22 @@ re2: @ @= @[TeX_( "/yy0{/nx/fltrail{/the/yy(1)}{/the/yy(2)}}" );@]@; + + @t}\endfoldedsections{@> -@ @= +@*2 Atoms. Every regular expression is assembled of atomic subexpressions, each +of which may be modified by an repetition operator that establishes how many +times a given pattern can repeat to stay part of the original atom. New atomic expressions +(or \prodstyle{singleton}s as they are called below) can be formed the usual way, by +enclosing a regular expression in parentheses. + +As explained \locallink{flex braces}above\endlink, braced repetition operators may +have different binding strengths, depending on the options supplied to \flex. The pretty +printing in both cases is identical as only the application scopes of the operator differ, and not +its meaning. +@= @G +@t}\vb{\insertraw{\beginfoldedsections}}{@> series: series singleton {@> @ @=} | singleton {@> @ @=} @@ -540,9 +634,12 @@ series: @ @= @@; - + +@t}\endfoldedsections{@> + @ @= @G +@t}\vb{\insertraw{\beginfoldedsections}}{@> singleton: singleton '*' {@> @ @=} | singleton '+' {@> @ @=} @@ -600,8 +697,15 @@ singleton: @ @= @[TeX_( "/yy0{/nx/flchar/the/yy(1)}" );@]@; -@ @= +@t}\endfoldedsections{@> + +@*2 Characters. Several facilities are available to specify sets of characters, including +built-in characters classes such as {\em whitespace}, {\em printable characters}, +{\em alphanumerics}, etc. Some simple boolean operaions are also supported to make specifying +character classes more efficient. +@= @G +@t}\vb{\insertraw{\beginfoldedsections}}{@> fullccl: fullccl CCL_OP_DIFF braceccl {@> @ @=} | fullccl CCL_OP_UNION braceccl {@> @ @=} @@ -610,7 +714,7 @@ fullccl: braceccl: '[' ccl ']' {@> @ @=} - | '[' '^' ccl ']' {@> @ @=} + | '[' '^' ccl ']' {@> @ @=} ; ccl: @@ -633,11 +737,13 @@ ccl: @ @= @[TeX_( "/yy0{/nx/flbraceccl{/the/yy(1)}{/the/yy(2)}{/the/yy(3)}}" );@]@; -@ @= - @[TeX_( "/yy0{/nx/flbracecclneg{/the/yy(1)}{/the/yy(3)}{/the/yy(4)}}" );@]@; +@ @= + @[TeXb( "/yy0{/nx/flbracecclneg" );@]@; + @[TeXfo( " {/the/yy(1)}{/the/yy(3)}{/the/yy(4)}}" );@]@; @ @= - @[TeX_( "/yy0{/the/yy(1)/nx/flcclrnge{/nx/flchar/the/yy(2)}{/nx/flchar/the/yy(4)}}" );@]@; + @[TeXb( "/yy0{/the/yy(1)/nx/flcclrnge" );@]@; + @[TeXfo( " {/nx/flchar/the/yy(2)}{/nx/flchar/the/yy(4)}}" );@]@; @ @= @[TeX_( "/yy0{/the/yy(1)/nx/flchar/the/yy(2)}" );@]@; @@ -648,7 +754,12 @@ ccl: @ @= @[TeX_( "/yy0{}" );@]@; -@ @= +@t}\endfoldedsections{@> + +@*3 Special character classes. Various character classes are predefined in \flex. +These include alphabetic and alphanumeric characters, digits, blank characters, upper and lower +case characters, etc. +@= @G ccl_expr: @t}\vb{\flatten}{@> @@ -696,7 +807,5 @@ string: @ @= @[TeX_( "/yy0{}" );@]@; -@ This is needed to get the |yytoknum| array. A trivial declaration suffices. +@ The postamble is empty for now. @= -#define YYPRINT(file, type, value) @[yyprint (file, type, value)@] - static void yyprint (FILE *file, int type, YYSTYPE value){} diff --git a/support/splint/cweb/lo.w b/support/splint/cweb/lo.w index 68ef1b6595..c2461787a9 100644 --- a/support/splint/cweb/lo.w +++ b/support/splint/cweb/lo.w @@ -1,4 +1,4 @@ -@q Copyright 2012-2020 Alexander Shibakov@> +@q Copyright 2012-2024 Alexander Shibakov@> @q Copyright 2002-2014 Free Software Foundation, Inc.@> @q This file is part of SPLinT@> @@ -18,6 +18,7 @@ @**The scanner for \ifx\bison\UNDEFINED\.{bison}\else\bison\fi\ syntax. \ifx\bison\UNDEFINED \input limbo.sty + \input yystype.sty \input grabstates.sty \immediate\openout\stlist=lo_states.h \fi @@ -95,7 +96,7 @@ output it in the form of a header file for the `real' lexer output @ {\it A \Cee-like comment in directives/rules}. @= -@G +@G(fs1) %x SC_YACC_COMMENT @g @@ -106,22 +107,26 @@ output it in the form of a header file for the `real' lexer output %\tracerulestrue %\traceactionstrue %\tracebadcharstrue +%\traceparseresultstrue +%\traceparserstatestrue %\prodstyle{\%\%}% -\traceparserstatesfalse -\tracestacksfalse -\tracerulesfalse -\traceactionsfalse -\tracebadcharsfalse -\yyflexdebugfalse @= -@G +@G(fs1) %x SC_ESCAPED_STRING SC_ESCAPED_CHARACTER @g @ {\it A identifier was just read in directives/rules. Special state to capture the sequence `\.{identifier:}'}. +\traceparserstatesfalse +\tracestacksfalse +\tracerulesfalse +\traceactionsfalse +\tracebadcharsfalse +\yyflexdebugfalse +\traceparseresultsfalse +\traceparserstatesfalse @= -@G +@G(fs1) %x SC_AFTER_IDENTIFIER @g @@ -131,7 +136,7 @@ disallow \prodstyle{NUL}, as this simplifies our implementation. We match angle brackets in nested pairs: several languages use them for generics/template types}. @= -@G +@G(fs1) %x SC_TAG @g @@ -150,25 +155,25 @@ Four types of user code: \aterm predicate (code between \.{\%?\{} and \.{\}} in middle section); }% @= -@G +@G(fs1) %x SC_PROLOGUE SC_BRACED_CODE SC_EPILOGUE SC_PREDICATE @g @ {\it \Cee\ and \Ceepp\ comments in code}. @= -@G +@G(fs1) %x SC_COMMENT SC_LINE_COMMENT @g @ {\it Strings and characters in code}. @= -@G +@G(fs1) %x SC_STRING SC_CHARACTER @g @ Bracketed identifiers support. @= -@G +@G(fs1) %x SC_BRACKETED_ID SC_RETURN_BRACKETED_ID @g @@ -179,9 +184,9 @@ Four types of user code: @ The code for the generated scanner is highly dependent on the options supplied. Most of the options below are essential for the scheme -adopted in this package to work. +adopted in this package to work.\gtextidx{\flex\ options example}{flex options example}{\flexidxdomain}% @= -@G +@G(fs1) %option bison-bridge %option noyywrap nounput noinput reentrant %option noyy_top_state @@ -194,7 +199,6 @@ adopted in this package to work. Here is a full list of regular expressions recognized by the \bison\ scanner. @= @@; - @@; @@; @@; @@; @@ -340,23 +344,11 @@ returns a pair of pointers as the value. } @g -@ Some additional constructs needed to typeset simple \flex\ -declarations. This is not part of the original \bison\ scanner. -@= -@G(fs2) - -{ - "%option" {@> @[TeX_( "/yylexreturnptr{FLEX_OPTION}" );@]@=} - "%x" {@> @[TeX_( "/yylexreturnptr{FLEX_STATE_X}" );@]@=} - "%s" {@> @[TeX_( "/yylexreturnptr{FLEX_STATE_S}" );@]@=} -} -@g - @ We present the `bad character' code first, before going into the details of the character matching by the rest of the lexer. @= - @[TeX_( "/edef/next{/nx/csname lexspecial[/the/yytextpure]/nx/endcsname}" );@]@; - @[TeX_( "/expandafter/expandafter/expandafter/ifx/next/relax" );@]@; + @[TeX_( "/expandafter/let/expandafter/next/csname lexspecial[/the/yytextpure]/endcsname" );@]@; + @[TeX_( "/ifx/next/relax" );@]@; @[TeX_( " /iftracebadchars" );@]@; @[TeX_( " /yyfatal{invalid character(s): /the/yytext}" );@]@; @[TeX_( " /fi" );@]@; @@ -436,13 +428,12 @@ later, after the context is known. @ @= @[TeX_( "/ifx/bracketedidstr/empty" );@]@; @[TeX_( " /bracketedidcontextstate/YYSTART /yyBEGIN{SC_BRACKETED_ID}" );@]@; - @[TeX_( " /let/next=/yylexnext" );@]@; + @[TeX_( " /yybreak/yylexnext" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /ROLLBACKCURRENTTOKEN" );@]@; @[TeX_( " /yyBEGIN{SC_RETURN_BRACKETED_ID}" );@]@; - @[TeX_( " /def/next{/yylexreturn{ID}}" );@]@; - @[TeX_( "/fi" );@]@; - @[TeX_( "/next" );@]@; + @[TeX_( " /yybreak{/yylexreturn{ID}}" );@]@; + @[TeX_( "/yycontinue" );@]@; @ @= @[TeX_( "/ifx/bracketedidstr/empty" );@]@; @@ -485,27 +476,25 @@ later, after the context is known. @[TeX_( "/ifx/bracketedidstr/empty" );@]@; @[TeX_( " /edef/bracketedidstr{{/the/yytextpure}{/the/yytext}" );@]@; @[TeX_( " {/the/yyfmark}{/the/yysmark}}" );@]@; - @[TeX_( " /let/next=/yylexnext" );@]@; + @[TeX_( " /yybreak/yylexnext" );@]@; @[TeX_( "/else" );@]@; - @[TeX_( " /def/next{/yywarn{unexpected identifier " );@]@; + @[TeX_( " /yybreak{/yywarn{unexpected identifier " );@]@; @[TeX_( " in bracketed name: /the/yytext}}" );@]@; - @[TeX_( "/fi" );@]@; - @[TeX_( "/next" );@]@; + @[TeX_( "/yycontinue" );@]@; @ @= @[TeX_( "/yyBEGINr/bracketedidcontextstate" );@]@; @[TeX_( "/ifx/bracketedidstr/empty" );@]@; - @[TeX_( " /def/next{/yywarn{an identifier expected}}" );@]@; + @[TeX_( " /yybreak{/yywarn{an identifier expected}}" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /ifnum/bracketedidcontextstate=/yylexstate{INITIAL}/relax" );@]@; @[TeX_( " /expandafter/yylval/expandafter{/bracketedidstr}" );@]@; @[TeX_( " /let/bracketedidstr=/empty" );@]@; - @[TeX_( " /def/next{/yylexreturn{BRACKETED_ID}}" );@]@; + @[TeX_( " /yybreak@@{/yylexreturn{BRACKETED_ID}}" );@]@; @[TeX_( " /else" );@]@; - @[TeX_( " /let/next=/yylexnext" );@]@; + @[TeX_( " /yybreak@@/yylexnext" );@]@; @[TeX_( " /fi" );@]@; - @[TeX_( "/fi" );@]@; - @[TeX_( "/next" );@]@; + @[TeX_( "/yycontinue" );@]@; @ @= @[TeX_( "/yyfatal{invalid character(s) in bracketed name: /the/yytext}" );@]@; @@ -621,11 +610,10 @@ The initial quote is already eaten}. @[TeX_( " {/the/yyfmark}{/the/yysmark}}}/next" );@]@; @[TeX_( " /STRINGFREE" );@]@; @[TeX_( " /yyBEGIN{INITIAL}" );@]@; - @[TeX_( " /def/next{/yylexreturn{TAG}}" );@]@; + @[TeX_( " /yybreak{/yylexreturn{TAG}}" );@]@; @[TeX_( "/else" );@]@; - @[TeX_( " /STRINGGROW/let/next=/yylexnext" );@]@; - @[TeX_( "/fi" );@]@; - @[TeX_( "/next" );@]@; + @[TeX_( " /STRINGGROW/yybreak/yylexnext" );@]@; + @[TeX_( "/yycontinue" );@]@; @ This is a slightly different rule from the original scanner. We do not perform |yyleng| computations, so it makes sense to raise the nesting level one by one. @@ -722,13 +710,12 @@ braced code. @[TeX_( "/ifnum/lonesting= @[TeX_( "/advance/lonesting/m@@ne" );@]@; @@ -736,12 +723,11 @@ braced code. @[TeX_( " /STRINGFINISH" );@]@; @[TeX_( " /edef/next{/yylval{{/the/laststring}{/the/yyfmark}{/the/yysmark}}}/next" );@]@; @[TeX_( " /yyBEGIN{INITIAL}" );@]@; - @[TeX_( " /def/next{/yylexreturn{BRACED_PREDICATE}}" );@]@; + @[TeX_( " /yybreak{/yylexreturn{BRACED_PREDICATE}}" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /STRINGGROW" );@]@; - @[TeX_( " /let/next=/yylexnext" );@]@; - @[TeX_( "/fi" );@]@; - @[TeX_( "/next" );@]@; + @[TeX_( " /yybreak/yylexnext" );@]@; + @[TeX_( "/yycontinue" );@]@; @ {\it Scanning some prologue: from \.{\%\{} (already scanned) to \.{\%\}}}. @= diff --git a/support/splint/cweb/mkeparser.w b/support/splint/cweb/mkeparser.w index f60ccf5d64..79505b3be4 100644 --- a/support/splint/cweb/mkeparser.w +++ b/support/splint/cweb/mkeparser.w @@ -1,4 +1,4 @@ -% Copyright 2012-2020, Alexander Shibakov +% Copyright 2012-2024, Alexander Shibakov % This file is part of SPLinT % % SPLinT is free software: you can redistribute it and/or modify @@ -24,7 +24,7 @@ Sourcer(er?) (\.{bs.w}) which will be included as soon as this paragraph is over. Since the main function of this code is to {\it dump\/} tables produced by \bison, and a {\it bison\/} is a large buffalo like animal, {\it and\/} the only reason it has to be done like this is due -to the less than optimal choices of a few developers, feel free to +to a less than optimal choices of a few developers, feel free to interpret the acronym as something easier to remember. @ @= @@ -32,6 +32,9 @@ interpret the acronym as something easier to remember. @ @= @@; +#ifdef YYEOF + @@; +#endif @ @= @@; @@ -83,6 +86,7 @@ interpret the acronym as something easier to remember. @ @<\Cee\ preamble@>= @@; + @<\Cee\ setup code specific to \bison@>@; @i common.w @i bs.w diff --git a/support/splint/cweb/mkscanner.w b/support/splint/cweb/mkscanner.w index e847428199..05f22bd6e3 100644 --- a/support/splint/cweb/mkscanner.w +++ b/support/splint/cweb/mkscanner.w @@ -1,4 +1,4 @@ -% Copyright 2012-2020, Alexander Shibakov +% Copyright 2012-2022, Alexander Shibakov % This file is part of SPLinT % % SPLinT is free software: you can redistribute it and/or modify diff --git a/support/splint/cweb/np.w b/support/splint/cweb/np.w index 58379649a5..a4216ee058 100644 --- a/support/splint/cweb/np.w +++ b/support/splint/cweb/np.w @@ -1,4 +1,4 @@ -@q Copyright 2012-2020, Alexander Shibakov@> +@q Copyright 2012-2024, Alexander Shibakov@> @q This file is part of SPLinT@> @q SPLinT is free software: you can redistribute it and/or modify@> @@ -18,7 +18,11 @@ name processing. This approach (i.e. using a `full blown' parser/scanner combination) is probably not the best way to implement such machinery but its main purpose is to demonstrate a way to create a separate -parser for local purposes. +parser for local purposes. The name parser is what allows one to +automatically typeset term names such as \.{example1} +and \.{\%option\_name} as \prodstyle{example1} and \prodstyle{\%option_name}. +@q The reference to \prodstyle{example1} above serves a dual role of correcting@> +@q an owerfull \vbox in the index.@> % We include the macros here since this file is intended to be % included by the documentation `aggregator' so putting bare \TeX\ % at the beginning of the file runs the risk of producing and error @@ -61,7 +65,7 @@ parser for local purposes. @G full_name: identifier_string suffixes.opt {@> @ @=} -| META_IDENTIFIER {@> @ @=} +| META_IDENTIFIER {@> @ @=} | quoted_name suffixes.opt {@> @ @=} ; @@ -123,7 +127,7 @@ qualifier: @ @= @[TeX_( "/yy0{/the/yy(1)/the/yy(2)}/namechars/yyval" );@]@; -@ @= +@ @= @[TeX_( "/getfirst{/yy(1)}/to/toksa" );@]@; @[TeX_( "/getsecond{/yy(1)}/to/toksb" );@]@; @[TeX_( "/yy0{/nx/idstr{/the/toksa}{/the/toksb}}/namechars/yyval" );@]@; @@ -138,7 +142,9 @@ qualifier: @[TeX_( "/getsecond{/yy(1)}/to/toksb" );@]@; @[TeX_( "/yy0{/nx/idstr{/the/toksa}{/the/toksb}}" );@]@; -@ @= +@ Tags are recognized as a separate syntax element although no special +processing is performed by the name parser or the associated macros. +@= @[TeX_( "/getfirst{/yy(2)}/to/toksa" );@]@; @[TeX_( "/getsecond{/yy(2)}/to/toksb" );@]@; @[TeX_( "/yy0{/nx/idstr{}{}}" );@]@; @@ -193,14 +199,15 @@ qualifier: @ An integer at the end of an identifier (such as |id1|) is interpreted as a suffix (similar to the way \MF\ treats identifiers, -and \mft\ typesets them\footnote{This allows, for example, names like -|$[term0]| while leaving |$[char2int]| in its `natural' form.}) to +and \mft\ typesets them,\footnote{This allows, for example, names like +|$[term0]| while leaving |$[char2int]| in its `natural' form.} as \prodstyle{id1}) to mitigate a well-intentioned but surprisingly inconvenient feature of \CTANGLE, namely outputting something like \.{id.1} as \.{id\ .1} in an attempt to make sure that integers do not interfere with structure dereferences. For this to produce meaningful results, a stricter interpretation of \prodstyle{IDENTIFIER} syntax is required, -represented by the \.{id\_strict} syntax below. +represented by the \flexrenstyle{id\_strict} syntax +\locallink{id_strict definition}below\endlink. @= @[TeX_( "/yy0{/the/yy(1)/nx/dotsp/nx/sfxi/the/yy(2)}" );@]@; @@ -251,8 +258,6 @@ as they have to be inserted in a place that is aware of the internal definitions definitions are used. @= -#define YYPRINT(file, type, value) @[yyprint (file, type, value)@] - static void yyprint (FILE *file, int type, YYSTYPE value){} @ Union of types. @@ -281,7 +286,10 @@ void define_all_states( void ) { @o @g -@ @= +@ \namedspot{id_strict definition}The tokens consumed by the name parser must +represent a relatively fine classification of various identifier substrings to be able to +detect various suffixes. +@= @@; @G(fs1) letter [_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ] @@ -300,7 +308,7 @@ int [0-9]+ @ Strings and characters in directives/rules. @= -@G +@G(fs1) %x SC_ESCAPED_STRING SC_ESCAPED_CHARACTER @g @@ -310,7 +318,7 @@ int [0-9]+ #include @ @= -@G +@G(fs1) %option bison-bridge %option noyywrap nounput noinput reentrant %option noyy_top_state diff --git a/support/splint/cweb/philosophy.w b/support/splint/cweb/philosophy.w index 7b173f5d2f..1f5c4a3dfc 100644 --- a/support/splint/cweb/philosophy.w +++ b/support/splint/cweb/philosophy.w @@ -1,4 +1,4 @@ -@q Copyright 2012-2020, Alexander Shibakov@> +@q Copyright 2012-2022, Alexander Shibakov@> @q This file is part of SPLinT@> @q SPLinT is free software: you can redistribute it and/or modify@> @@ -64,6 +64,12 @@ they set a special reading rhythm, which is an added bonus in many cases, although their presense openly violates the `universally gray pages are a must' dogma. +One final remark concerns the abundance of footnotes in this manual. I confess, +there is almost no reason for it $\ldots$ except {\em I like footnotes\/}! +They help introduce the air of mystery and adventure to an otherwise boring +text. They are akin to the author wispering a secret in the reader's +ear\footnote{Breaking convention by making the pages even less uniform is an added bonus.}. + @*1 Why GPL. Selecting the license for this project involves more than the availability of the source code. \TeX, by its very nature is an @@ -191,12 +197,19 @@ the language. `Make it object-oriented' is neither a good reason nor a clearly defined one, however. @*1 Why not $*$\TeX. -Simple. I never use it and have no idea of how packages, classes, +Simple. I rarely, if ever\footnote{In some cases, a publisher would only accept +a \LaTeX\ document, sadly. Better than most alternatives though.}, +use it and have no idea of how packages, classes, etc., are designed. I have heard it has impressive mechanisms for dealing with various problems commonly encountered in \TeX. Sadly, my -knowledge of $*$\TeX\ machinery is almost nonexistent. This may change -but right now I have tried to make the macros as generic as possible, -hopefully making $*$\TeX\ adaptation easy. +knowledge of $*$\TeX\ machinery is almost nonexistent\footnote{I am well familiar +with the programming that went into \LaTeX, which is of highest quality. I do not +share the design philosophy though and try to use only the most standard features}. +This may change but right now I have tried to make the macros as generic as possible, +hopefully making $*$\TeX\ adaptation easy\footnote{Unfortunately some redesign would +be certainly necessary. Thus, \splint\ relies on the way plain \TeX\ allocates token +registers so if the corresponding scheme in \LaTeX\ is drastically different, this +portion of the macros would have to be rewritten.}. The following quote from \cite[Ho] makes me feel particularly uneasy about the current state of development of various \TeX\ variants: @@ -205,7 +218,7 @@ and even more important is that the general impression is that of a finished boo sometimes it seems like\/ \.{WEB} actively discourages development. This is a subjective point, but nevertheless a quite important one.}'' -{\it Discouraging development\/} seems like a good thing to +{\it Discouraging development\/} seems like a good feature to me. Otherwise we are one step away from encouraging writing poor software with inadequate tools merely `to encourage development'. @@ -300,7 +313,7 @@ inserts \.{\\hbox\{\}}$\,$\TeX\ stuff$\,$\.{\{\}} into \CWEAVE's output. The cost of this hack (aside from looking and feeling rather ugly on the editor screen, not to mention disrupting the editor's brace accounting) is a superfluous \.{\\hbox\{\}} left behind {\em before\/} -the `\TeX\ stuff'. The programmer's provided \TeX\ code is unable to +the `\TeX\ stuff'. The programmer provided \TeX\ code is unable to remove this box (at the macro level, i.e.~in \TeX's `mouth' using D.~Knuth's terminology, one may still succeed with the \.{\\lastbox} approach unless the \.{\\hbox} was inserted in the main vertical mode) @@ -312,6 +325,16 @@ cases such side-effects are indeed desirable, and save the programmer some typing but it seems that the \.{@@t} facility was not well thought out in its entirety.}. +Continuing with the theme of inserting \TeX\ material into \CWEAVE\ output, +another one of \CWEB's inflexibilities is the lack of means of inserting +\TeX\ {\em between\/} sections. While inserting pure text may be arranged by +putting a codeless section after the one with the code (appropriate macros +can be written to suppress the generation of a reference to such a section), +inserting command sequences that affect, say, the typesetting style +of the consequent sections is not so easy. The trick with a `fake' section below +will be quite visible in the final output which is almost always undesirable. +Using the \.{@@t} mechanism is also far from ideal. + In general, the lack of structure in \CWEAVE's generated \TeX\ seems to hinder even seemingly legitimate uses of \.{cwebmac.tex} macros. Even such a natural desire as to use a different type size for diff --git a/support/splint/cweb/references.w b/support/splint/cweb/references.w index 83397c93bb..3824972d65 100644 --- a/support/splint/cweb/references.w +++ b/support/splint/cweb/references.w @@ -1,4 +1,4 @@ -@q Copyright 2012-2020, Alexander Shibakov@> +@q Copyright 2012-2022, Alexander Shibakov@> @q This file is part of SPLinT@> @q SPLinT is free software: you can redistribute it and/or modify@> diff --git a/support/splint/cweb/so.w b/support/splint/cweb/so.w index d7a7696b8c..944f2cb82f 100644 --- a/support/splint/cweb/so.w +++ b/support/splint/cweb/so.w @@ -32,6 +32,7 @@ @**The lexer for \ifx\flex\UNDEFINED\.{flex}\else\flex\ \fi syntax. \ifx\flex\UNDEFINED \input limbo.sty + \input yystype.sty \input grabstates.sty \immediate\openout\stlist=fil_states.h \fi @@ -43,16 +44,31 @@ to replace them with ordinary patterns and use |yyless()| in the actions. @G %{@> @ @=%} @> @ @= - @> @ @= + @> @ @= @> @ @= @> @ @= %% @> @ @= + @> @ @= @> @ @= %% @> @ @= @g +@ Bootstrap lexer. +@(ssfs.ll@>= +@G +%{@> @ @=%} + @> @ @= + @> @ @= + @> @ @= +%% + @> @ @= + @> @ @= +%% + @> @ @= +@g + @ @= @ There are a few options that are necessary to ensure that the lexer @@ -60,27 +76,31 @@ functions properly. Some of them (like \.{caseless}) directly affect the behavior of the scanner, others (e.g.~\.{noyy\_top\_state}) prevent generation of unnecessary code. @= -@G +@G(fs1) %option caseless nodefault stack noyy_top_state %option nostdinit -@g - -@ @= -@G %option bison-bridge %option noyywrap nounput noinput reentrant %option debug %option stack + +@ @= +@G(fs1) %option outfile="fil.c" @g +@ @= +@G(fs1) +%option outfile="ssfs.c" +@g + @*1 Regular expression and state definitions. The lexer uses a large number of states to control its operation. Both section~1 and section~2 rules rely on the scanner being in the appropriate state. Otherwise (see \.{symbols.sty} example) the lexer may parse the same fragment in a wrong context. @= -@G +@G(fs1) %x SECT2 SECT2PROLOG SECT3 CODEBLOCK PICKUPDEF SC CARETISBOL NUM QUOTE %x FIRSTCCL CCL ACTION RECOVER COMMENT ACTION_STRING PERCENT_BRACE_ACTION %x OPTION LINEDIR CODEBLOCK_MATCH_BRACE @@ -132,7 +152,7 @@ M4QEND "]]" @*1 Regular expressions for \flex\ input scanner. The code below treats \prodstyle{\%pointer} and \prodstyle{\%array} the same way it treats \prodstyle{\%option} while typesetting. -@= +@= @G(fs2) { ^{WS} {@> @[TeX_( "/flindented@@codetrue/yyBEGIN{CODEBLOCK}/yylexnext" );@]@=} @@ -211,7 +231,7 @@ The code below treats \prodstyle{\%pointer} and \prodstyle{\%array} the same way { \n {@> @[TeX_( "/yypopstate/yylexnext" );@]@=} - [[:digit:]]+ {@> @[TeX_( "/fllinenum=/number/yytext/yylexnext" );@]@=} + [[:digit:]]+ {@> @[TeX_( "/fllinenum=/number/the/yytext/yylexnext" );@]@=} \"[^"\n]*\" {@> @[TeX_( "/yylexnext" );@] /* ignore the file name in the line directives */ @=} . {@> @[TeX_( "/yylexnext" );@] /* ignore spurious characters */ @=} } @@ -257,10 +277,10 @@ The code below treats \prodstyle{\%pointer} and \prodstyle{\%array} the same way @ @= @[TeX_( "/iffldidadef" );@]@; @[TeX_( " /yylval/expandafter{/flnmdef}" );@]@; - @[TeX_( " /def/next{/flinc@@linenum/yyBEGIN{INITIAL}/yylexreturn{RE_DEF}}" );@]@; + @[TeX_( " /yybreak{/flinc@@linenum/yyBEGIN{INITIAL}/yylexreturn{RE_DEF}}" );@]@; @[TeX_( "/else" );@]@; - @[TeX_( " /def/next{/yyfatal{incomplete name definition}}" );@]@; - @[TeX_( "/fi/next" );@]@; + @[TeX_( " /yybreak{/yyfatal{incomplete name definition}}" );@]@; + @[TeX_( "/yycontinue" );@]@; @ @= @G(fs2) @@ -390,7 +410,6 @@ The code below treats \prodstyle{\%pointer} and \prodstyle{\%array} the same way .*{NL} {@> @[TeX_( "/flinc@@linenum/yyBEGIN{INITIAL}/yylexnext" );@] @=} @ Like \bison, \flex\ allows insertion of \Cee\ code in the middle of the input file. -\saveparseoutputtrue @= @G(fs2) { @@ -407,7 +426,6 @@ The code below treats \prodstyle{\%pointer} and \prodstyle{\%array} the same way } @ All the code inside is ignored. -\saveparseoutputfalse @= @[TeX_( "/flinc/flbracelevel/yyless{2}/yylexnext" );@]@; @@ -416,13 +434,16 @@ The code below treats \prodstyle{\%pointer} and \prodstyle{\%array} the same way @ @= @[TeX_( "/ifnum/flbracelevel>/z@@" );@]@; - @[TeX_( " /let/next/yylexnext" );@]@; + @[TeX_( " /yybreak/yylexnext" );@]@; @[TeX_( "/else" );@]@; - @[TeX_( " /def/next{/yysetbol{/@@ne}/yyBEGIN{SECT2}/yyless{0}/yylexnext}" );@]@; - @[TeX_( "/fi/next" );@]@; + @[TeX_( " /yybreak{/yysetbol{/@@ne}/yyBEGIN{SECT2}/yyless{0}/yylexnext}" );@]@; + @[TeX_( "/yycontinue" );@]@; @ A pattern below (for the character class processing) had to be broken into two lines. -A symbol ($\odot$@^$\odot$ separator, \flex@>) was inserted to indicate that a break had occured. The macros for \flex\ +A special symbol ($\odot$\gtextidx{$\odot$ separator, \flex}{0. separator, flex}{\flexidxdomain}) +has been inserted to indicate that a break had occured. + +The macros for \flex\ typesetting use a different mechanism from that of \bison\ macros and allow typographic corrections to be applied to sections of the \flex\ code represented by various nonterminals. These corrections can also be delayed. For the details, an interested reader may consult @@ -477,14 +498,14 @@ These corrections can also be delayed. For the details, an interested reader may @ @= @[TeX_( "/yyless{1}/yyBEGIN{NUM}" );@]@; @[TeX_( "/iffllex@@compat" );@]@; - @[TeX_( " /def/next{/yylexreturn{BEGIN_REPEAT_POSIX}}" );@]@; + @[TeX_( " /yybreak{/yylexreturn{BEGIN_REPEAT_POSIX}}" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /ifflposix@@compat" );@]@; - @[TeX_( " /def/next{/yylexreturn{BEGIN_REPEAT_POSIX}}" );@]@; + @[TeX_( " /yybreak@@{/yylexreturn{BEGIN_REPEAT_POSIX}}" );@]@; @[TeX_( " /else" );@]@; - @[TeX_( " /def/next{/yylexreturn{BEGIN_REPEAT_FLEX}}" );@]@; + @[TeX_( " /yybreak@@{/yylexreturn{BEGIN_REPEAT_FLEX}}" );@]@; @[TeX_( " /fi" );@]@; - @[TeX_( "/fi/next" );@]@; + @[TeX_( "/yycontinue" );@]@; @ @= @[TeX_( "/def/flbracelevel{1}" );@]@; @@ -492,17 +513,17 @@ These corrections can also be delayed. For the details, an interested reader may @[TeX_( "/ifflin@@rule" );@]@; @[TeX_( " /fldoing@@rule@@actiontrue" );@]@; @[TeX_( " /flin@@rulefalse" );@]@; - @[TeX_( " /def/next{/yylexreturnxchar/n}" );@]@; + @[TeX_( " /yybreak{/yylexreturnxchar/n}" );@]@; @[TeX_( "/else" );@]@; - @[TeX_( " /let/next/yylexnext" );@]@; - @[TeX_( "/fi/next" );@]@; + @[TeX_( " /yybreak/yylexnext" );@]@; + @[TeX_( "/yycontinue" );@]@; @ This action has been changed to accomodate the new grammar. The separator (\.{\yl}) is treated as an ordinary (empty) action. @= @[TeX_( "/ifflsf@@skip@@ws" );@]@;/* whitespace ignored, still inside a pattern */ @[TeX_( " /yylessafter{|}" );@]@; - @[TeX_( " /let/next/yylexnext" );@]@; + @[TeX_( " /yybreak/yylexnext" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /flinc@@linenum" );@]@; @[TeX_( " /fldoing@@rule@@actiontrue" );@]@; @@ -510,8 +531,8 @@ is treated as an ordinary (empty) action. @[TeX_( " /flcontinued@@actiontrue" );@]@; @[TeX_( " /unput{/n}" );@]@; @[TeX_( " /yyBEGIN{ACTION}" );@]@; - @[TeX_( " /edef/next{/nx/yylexreturnxchar/n}" );@]@; - @[TeX_( "/fi/next" );@]@; + @[TeX_( " /yybreak{/yylexreturnxchar/n}" );@]@; + @[TeX_( "/yycontinue" );@]@; @ @= @[TeX_( "/ifflsf@@skip@@ws" );@]@; @@ -525,7 +546,7 @@ is treated as an ordinary (empty) action. @ @= @[TeX_( "/ifflsf@@skip@@ws" );@]@; - @[TeX_( " /let/next/yylexnext" );@]@; + @[TeX_( " /yybreak/yylexnext" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /def/flbracelevel{0}" );@]@; @[TeX_( " /flcontinued@@actionfalse" );@]@; @@ -533,16 +554,16 @@ is treated as an ordinary (empty) action. @[TeX_( " /ifflin@@rule" );@]@; @[TeX_( " /fldoing@@rule@@actiontrue" );@]@; @[TeX_( " /flin@@rulefalse" );@]@; - @[TeX_( " /def/next{/yylexreturnxchar/n}" );@]@; + @[TeX_( " /yybreak@@{/yylexreturnxchar/n}" );@]@; @[TeX_( " /else" );@]@; - @[TeX_( " /let/next/yylexnext" );@]@; + @[TeX_( " /yybreak@@/yylexnext" );@]@; @[TeX_( " /fi" );@]@; - @[TeX_( "/fi/next" );@]@; + @[TeX_( "/yycontinue" );@]@; @ @= @[TeX_( "/ifflsf@@skip@@ws" );@]@; @[TeX_( " /flinc@@linenum" );@]@; - @[TeX_( " /let/next/yylexnext" );@]@; + @[TeX_( " /yybreak/yylexnext" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /def/flbracelevel{0}" );@]@; @[TeX_( " /flcontinued@@actionfalse" );@]@; @@ -551,11 +572,11 @@ is treated as an ordinary (empty) action. @[TeX_( " /ifflin@@rule" );@]@; @[TeX_( " /fldoing@@rule@@actiontrue" );@]@; @[TeX_( " /flin@@rulefalse" );@]@; - @[TeX_( " /def/next{/yylexreturnxchar/n}" );@]@; + @[TeX_( " /yybreak@@{/yylexreturnxchar/n}" );@]@; @[TeX_( " /else" );@]@; - @[TeX_( " /let/next/yylexnext" );@]@; + @[TeX_( " /yybreak@@/yylexnext" );@]@; @[TeX_( " /fi" );@]@; - @[TeX_( "/fi/next" );@]@; + @[TeX_( "/yycontinue" );@]@; @ @= @[TeX_( "/def/flsectnum{3}" );@]@; @@ -596,26 +617,26 @@ The braces and the possible trailing whitespace will be dealt with by the typese @ @= @[TeX_( "/iffllex@@compat" );@]@; - @[TeX_( " /def/next{/yyless{1}/flsf@@push/yylexreturnraw(}" );@]@; + @[TeX_( " /yybreak{/yyless{1}/flsf@@push/yylexreturnraw(}" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /ifflposix@@compat" );@]@; - @[TeX_( " /def/next{/yyless{1}/flsf@@push/yylexreturnraw(}" );@]@; + @[TeX_( " /yybreak@@{/yyless{1}/flsf@@push/yylexreturnraw(}" );@]@; @[TeX_( " /else" );@]@; - @[TeX_( " /def/next{/yypushstate{EXTENDED_COMMENT}}" );@]@; + @[TeX_( " /yybreak@@{/yypushstate{EXTENDED_COMMENT}}" );@]@; @[TeX_( " /fi" );@]@; - @[TeX_( "/fi/next" );@]@; + @[TeX_( "/yycontinue" );@]@; @ @= @[TeX_( "/flsf@@push" );@]@; @[TeX_( "/iffllex@@compat" );@]@; - @[TeX_( " /def/next{/yyless{1}}" );@]@; + @[TeX_( " /yybreak{/yyless{1}}" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /ifflposix@@compat" );@]@; - @[TeX_( " /def/next{/yyless{1}}" );@]@; + @[TeX_( " /yybreak@@{/yyless{1}}" );@]@; @[TeX_( " /else" );@]@; - @[TeX_( " /def/next{/yyBEGIN{GROUP_WITH_PARAMS}}" );@]@; + @[TeX_( " /yybreak@@{/yyBEGIN{GROUP_WITH_PARAMS}}" );@]@; @[TeX_( " /fi" );@]@; - @[TeX_( "/fi/next" );@]@; + @[TeX_( "/yycontinue" );@]@; @[TeX_( "/yylexreturnraw(" );@]@; @ @= @@ -708,14 +729,14 @@ The braces and the possible trailing whitespace will be dealt with by the typese @ @= @[TeX_( "/yyBEGIN{SECT2}" );@]@; @[TeX_( "/iffllex@@compat" );@]@; - @[TeX_( " /def/next{/yylexreturn{END_REPEAT_POSIX}}" );@]@; + @[TeX_( " /yybreak{/yylexreturn{END_REPEAT_POSIX}}" );@]@; @[TeX_( "/else" );@]@; @[TeX_( " /ifflposix@@compat" );@]@; - @[TeX_( " /def/next{/yylexreturn{END_REPEAT_POSIX}}" );@]@; + @[TeX_( " /yybreak@@{/yylexreturn{END_REPEAT_POSIX}}" );@]@; @[TeX_( " /else" );@]@; - @[TeX_( " /def/next{/yylexreturn{END_REPEAT_FLEX}}" );@]@; + @[TeX_( " /yybreak@@{/yylexreturn{END_REPEAT_FLEX}}" );@]@; @[TeX_( " /fi" );@]@; - @[TeX_( "/fi/next" );@]@; + @[TeX_( "/yycontinue" );@]@; @ @= @@ -833,3 +854,19 @@ void define_all_states( void ) { #include "fil_states.h" #undef _register_name +@ @= +@G(fs2) +<*>. {@> @[TeX_( "/yyerrterminate" );@] @=} + +@ The drive expects this function to be defined but the bootstrap +lexer has no need for it. We leave it in to appease the compiler. +@= +void define_all_states( void ) { + @@; +} + +@ @= +#define _register_name( name ) @[Define_State( #name, name )@] + /* The \flexsnstyle{INITIAL} state is generated automatically */ +#undef _register_name + diff --git a/support/splint/cweb/splint.w b/support/splint/cweb/splint.w index e50e090c32..4bf32953ff 100644 --- a/support/splint/cweb/splint.w +++ b/support/splint/cweb/splint.w @@ -1,4 +1,4 @@ -% Copyright 2012-2020, Alexander Shibakov +% Copyright 2012-2024, Alexander Shibakov % This file is part of SPLinT % % SPLinT is free software: you can redistribute it and/or modify @@ -13,19 +13,12 @@ % % You should have received a copy of the GNU General Public License % along with SPLinT. If not, see . -% -\newwrite\gindex % index entries generated by the various parsers, \prodstyle{...} commands, etc. -% + \input limbo.sty \input frontmatter.sty \def\optimization{5} \input yy.sty \modenormal -\input noweb.sty - \xreflocaltrue - \readlxrefs % read the reference file if exists before any sections appear - \newwrite\xrefstream % references for noweb like style of sectioning. - \immediate\openout\xrefstream=\jobname.xxr % multi-column output \input dcols.sty \topskip=9pt % this is a purely aesthetic choice, also negating the \raggedbottom @@ -71,9 +64,9 @@ \defreserved{Y}{\.{Y}} \showlastactiontrue +\initauxstream @**Introduction. -\setupfootnotes \splint\footnote{I was tempted to call the package {\tt ParLALRgram} which stands for Parsing {\sc LALR} Grammars or {\tt PinT} for `Parsing in \TeX' but both sounded too generic.} (Simple Parsing and @@ -117,9 +110,9 @@ output is some very rudimentary post- and pre-processing. Our main concern is thus \CWEAVE\ that not only pretty prints the program but also creates an index, cross-references all the sections, etc. Getting \CWEAVE\ to pretty print a language other than -\Cee\ requires some additional attention. A true digital warrior would +\Cee\ requires some additional effort. A true digital warrior would probably try to decipher \CWEAVE's output `in the raw' but, alas, my -WebFu is not that strong. The loophole comes in the form of a rarely +(C)WebFu is not that strong. The loophole comes in the form of a rarely (for a good reason) used \CWEB\ command: the verbatim (\.{@@=...@@>}) output. The material to be output by this construct undergoes minimal processing and is put inside \.{\\vb\{}$\ldots$\.{\}}. All that is @@ -134,9 +127,9 @@ merely a brief overview of the approach. Every \CWEB\ document is split into {\em sections}, each divided into three parts (any one of which can be empty): the \TeX\ part, the middle part, and -the \Cee\ part (which should more appropriately be called the {\em code -part\/}). The code part of each\footnote{With the exception of the nameless \.{@@c} -sections.} section carries a name for cross referencing +the \Cee\ part (which should more appropriately be called the {\em code\/} or +the {\em program\/} part). The \Cee\ part of each\footnote{With the exception of the +nameless \.{@@c} (or \.{@@p}) sections.} section carries a name for cross referencing purposes. The sections themselves are automatically numbered by \CWEAVE\ and their code parts may be referenced from other sections, as well as included in other sections' code parts using \CWEB's cross referencing @@ -151,7 +144,7 @@ The original \CWEB\ macros (from \.{cwebmac.tex}) used the numbers generated by \CWEAVE\ to refer to specific sections. This was true for the table of contents, as well as the index entries. The macros used by \splint\ adopt a different convention, proposed by N.~Ramsey -for his literate programming software, \noweb. In the new system +for his literate programming software \noweb. In the new system (which will be referred to as the \noweb\ style of cross referencing), each section is labelled by the page number where it starts and an alphabetic character that indicates the order of appearance of the @@ -163,10 +156,13 @@ section. The top level (\.{@@**}) sections, introducing major portions of the code have also been given more prominent -appearance and carry a chapter number in addition to the the \noweb\ -style section number (the latter is used for cross references, as the -chapter number gives no indication as to where the said chapter is -located). +appearance. They display the chapter number using a large typeface +and omit the marginal section reference. References to such sections +are typeset as {\it cnnn\/} where {\it nnn\/} represents the chapter +number. While such references obscure the page number, hopefully one keeps +the number of chapters, as well as such references, small. This +modification improves the appearance of the first chapter pages. + \CWEB\ also generates an {\em index\/} of all the identifiers (with some exceptions, such as single letter names) appearing in the @@ -247,7 +243,7 @@ important application. @*1 Parsing and parsers. At an abstract level, a {\em parser@^parser@>\/} is just a routine -that transforms text. Naturally, not every possible tranformation is +that transforms text. Naturally, not every possible transformation is beneficial, so, informally, the value of a parser lies in its ability to expose some {\em meaning\/} in the text. If valid texts are reduced to a small finite set (while each text can be arbitrarily long) one @@ -342,7 +338,7 @@ longer strings. Computing $m$ and $n$ above now reduces to incrementing an appropriate variable upon exiting the corresponding function. More important, -however, is the observation that this parsing algorithm can be +however, is the observation that this parser specification can be extracted from the grammar in a very straightforward fashion. To better illustrate the r\^ole of the grammar in the choice of the parsing algorithm, consider the following syntax for the same @@ -364,10 +360,10 @@ astring: \noindent While the language is unchanged, so the algorithm above still works, the lookahead tokens are not {\em immediately\/} apparent upon looking at the productions. Some preprocessing must take -place before one can decide on the choice of parser states and the -appropriate lookahead tokens. Such algorithms indeed exist and result -in what is known as an {\sc LR} parser for the fragment above -(actually, a simpler {\sc LALR} parser may be built for this +place before one can decide on the choice of the parser states and the +appropriate lookahead tokens. Such parser generating algorithms +indeed exist and will produce what is known as an {\sc LR} parser +for the fragment above (actually, a simpler {\sc LALR} parser may be built for this grammar\footnote{Both of these algorithms will use the parser stack more efficiently, effectively resolving the `call stack depth' issue mentioned earlier.}). One can see that some grammar types may make @@ -411,11 +407,12 @@ non_terminal: @g @ $\ldots$ if the syntax is correct. -In case it is a bit off (note the missing colon after \.{whoops}), the parser will give up and +In case it is a bit off (note the missing colon after \.{whoops} below), the parser will give up and you will see a different result. The code in the fragment below is easily recognizable, and some parts of it (all of \Cee\ code, in fact) are still pretty printed by \CWEAVE. Only the verbatim portion is left -unprocessed. +unprocessed. The layout of the original code is reproduced unchanged, including the braces and production separators (i.e.\ +\.{\yl}) normally removed by the parser for presentation purposes. @= @G whoops @@ -478,7 +475,7 @@ automatically from the \CWEB\ source file by the \CWEAVE\ processing stage. All of these definitions can be overwritten to get the desired output (say, one might want to typeset \.{ID} in a roman font, as `identifier'; all that needs to be done to -make this possible is a macro that says \.{\\prettywordpair\{ID\}\{\{\\rm +make this possible is to provide a macro that says \.{\\prettywordpair\{ID\}\{\{\\rm identifier\}\}} in an appropriate namespace (usually \.{\\hostparternamespace})). The file \.{btokenset.sty} input above contains a number of such definitions. @@ -567,11 +564,11 @@ the file below. @*1 On debugging. This concludes a short introduction to the \bison\ grammar pretty printing using this macro collection. It would be -incomplete, however, without a short reference to debugging\footnote{Here -we are talking about debugging the output produced by \CWEAVE\ when +incomplete, however, without a short reference to debugging\footnote{At +the moment we are discussing debugging the output produced by \CWEAVE\ when the included \bison\ parser is used, {\it not\/} debugging parsers written with the help of this software: the latter topic is covered in more -detail later on}. There is a +detail later on.}. There is a fair amount of debugging information that the macros can output, unfortunately, very little of it is tailored to the {\em use\/} of the macros in the \bison\ parser. Most of it is designed to help build a @@ -653,7 +650,7 @@ identifier determines its association with the appropriate set.}. a collection of parsers, usually derived from a common set of productions, and sharing a common lexer. As the name suggests, the parsers in the collection are tried in order until the input is parsed -successfully or every parser has been tried. This terminology may be the +successfully or every parser has been tried. This terminology may become a source of some confusion, since each parsing algorithm used by \bison\ maintains several stacks. We will always refer to them by naming a specific task the stack is used for (such as the {\em value stack\/} or the @@ -687,7 +684,7 @@ productions. \aterm{term} in a narrow sense, an `element' of a grammar. Instead of a long winded definition, an example, such as \prodstyle{ID} should suffice. Terms are further classified into {\it terminals\/} (tokens) -and {\it nonterminals\/} (which can be intuitively thought of as +and {\it nonterminals\/} (which may be intuitively thought of as composite terms). \aterm{token} in short, an element of a set. Usually encoded as an @@ -734,7 +731,7 @@ some attention, as well. There are a number of excellent programs written to automate this step in much the same fashion as \bison\ automates the generation of parsers. One such tool, \flex, though (in the opinion of this author) slightly lacking in the simplicity and -elegance as compared to \bison, was used to implement the lexer for +elegance when compared to \bison, was used to implement the lexer for this software suite. Lexing in \TeX\ will be discussed in considerable detail later in this manual. @@ -750,7 +747,7 @@ syntax-directed translation} (which requires an appropriate abstraction to represent \bison's actions inside \TeX). We shall begin by discussing the parsing process itself. -@*1 Arrays, stacks and the parser. +@*1 Arrays, stacks, and the parser. Let us briefly examine the programming environment offered by \TeX. Designed for typesetting, \TeX's remarkable language provides a layer of macro processing atop of a set of commands that @@ -826,7 +823,9 @@ implementation). Since stacks pop up and disappear frequently (what else are stacks to do?), list macros are usually used to store them. The optimized parser uses a separate \.{\\count} register to keep track of the top of the stack in the corresponding associative -array. +array\footnote{Which means, unfortunately, that making such fully optimized +parser {\em reentrant\/} would take an extraordinary amount of effort. Hence, +if reentrancy is a requirement, stacks are better kept inside list macros.}. Let us now switch our attention to the code that implements the parser and scanner {\it functions\/}. @@ -1175,8 +1174,10 @@ token and move on but what if this was a control sequence? After all, just as easily as \.{\\string} makes a sequence into characters, \.{\\csname}$\,\ldots\,$\.{\\endcsname} pair will make any sequence of characters into a control sequence so determining the end the character -sequence produced by \.{\\string} may prove impossible. Huh~$\ldots$ - +sequence produced by \.{\\string} may prove impossible. +$$ +\hbox{Huh~$\ldots$} +$$ What we need is a backup mechanism: keeping a copy of the token sequence ahead, one can use \.{\\string} to see whether the next token is a real @@ -1233,7 +1234,7 @@ or even {\it tokener}), discussed in the next section. @*1 Lexing in \TeX. In a typical system that uses a parser to process text, the parsing pass is usually split into several stages: the raw input, the lexical analysis (or simply {\it lexing}), and the parsing -proper. The {\it lexing\/} (also called {\it scanning}, we use these +proper. The {\it lexing\/} pass (also called {\it scanning}, we use these terms interchangeably) clumps various sequences of characters into {\it tokens\/} to facilitate the parsing stage. The reasons for this particular hierarchy are largely pragmatic and are partially historic @@ -1242,7 +1243,7 @@ phases, as well, although it usually isn't). If one recalls a few basic facts from the formal language theory, it becomes obvious that a lexer, that parses {\it regular\/} languages, -can (theoretically) be replaced by an {\sc LALR} parser, that parses {\it +can be (in theory) replaced by an {\sc LALR} parser, that parses {\it context-free\/} ones (or some subset thereof, which is still a super set of all regular languages). A common justification given for creating specialized lexers is efficiency and speed. The @@ -1266,7 +1267,10 @@ matching input is accepted. The only straightforward way to do this with a traditional parser is to parse longer and longer inputs again and again. While this process can be optimized to a certain degree, the fact that a parser has a {\it stack\/} to maintain limits its -ability to back up. +ability to back up\footnote{It should be also mentioned that the fact that +the lexing pass takes place prior to the parser consuming the resulting tokens +allows one to process some grammars that are not context free. See, for example +the {\em parser hack\/} used to process |typedef|s in \Cee.}. As an aside, the mechanism by which \CWEB\ assembles its `scraps' into chunks of recognized code is essentially iterative lexing, @@ -1450,7 +1454,7 @@ altering the grammar mentioned above apply in this case, as well, only at the `lexical analysis level'. At a minimum, the set of tokens matched by the scanner would have to be altered. -A much more satisfying approach involves inserting the hints at the input stage and +A much more satisfying approach, however, involves inserting the hints at the input stage and passing this information to the scanner and the parser as part of the token `values'. The hints themselves can masquerade as characters ignored by the scanner (white space\footnote{Or even the `intercharacter space', to make the @@ -1482,7 +1486,8 @@ This is exactly what the scanner produced by the tools in this package does: along with the main stream of tokens meant for the parser, it produces two\footnote{There would be no difficulty in splitting either of these streams into multiple `substreams' by modifying the stream -extraction macros accordingly.} hidden streams (called the \.{\\yyformat} stream and +extraction macros accordingly.} hidden streams\namedspot{parser.streams} +(called the \.{\\yyformat} stream and the \.{\\yystash} stream) and provides the parser with two strings (currently only strings of digits are used although arbitrary sequences of \TeX\ tokens can be used as pointers) with the promise @@ -1490,10 +1495,13 @@ that {\it all the `hints' between the beginning of the corresponding stream and the point labeled by the current stream pointer appeared among the characters up to and, possibly, including the ones matched as the current token}. The macros to extract the relevant parts of the -streams (\.{\\yyreadfifo} and its cousins) are provided for the +streams (\.{\\consumelistupto} and its cousins) are provided for the convenience of the parser designer. -The \.{\\yystash} stream collects all the typesetting commands inserted by +What the parser does with these pointers and the information they provide, is +up to the parser designer (the parsers for \flex\ and \bison\ syntax +in this package use somewhat different strategies). +The \.{\\yystash} stream currently collects all the typesetting commands inserted by \CWEB\ to be possibly used in displaying the action code in \bison\ productions, for example. Because of this, it may appear in somewhat unexpected places, introducing spaces where the programmer did not @@ -1505,10 +1513,10 @@ The interested reader can consult the input routine macros in \.{yyinput.sty} for the details of the internal representation of the streams. -In the interest of full disclosure, let me point out that this simple +In the interest of full disclosure, it should be pointed out that this simple technique introduces a significant strain on \TeX's computational resources: the lowest level macros, the ones that handle -character input and are thus executed (sometimes multiple times), for +character input and are thus executed (in some cases multiple times), for {\it every\/} character in the input stream are rather complicated and therefore, slow. Whenever the use of such streams is not desired a simpler input routine can be written to speed up the process (see @@ -1517,9 +1525,13 @@ input routine can be written to speed up the process (see Finally, while probably not directly related to the present discussion, this approach has one more interesting feature: after the parser is finished, the parser output and the streams exist -`statically', fully available for any last minute preprocessing or for +`statically', fully available for any last minute postprocessing or for debugging purposes, if necessary\footnote{One may think of the parser output -as an {\it executable abstract syntax tree (AST)}.}. Under most circumstances, the parser +as an {\it executable abstract syntax tree\/} (\AST\ or \EAST\ if one +likes cute abbreviations, or even e\AST\ for an extra touch of modernity). +This parser feature is used to implement the facility that allows easy referencing of +productions in the section that implements the action code for one. See \.{yyunion.sty} +and the source of this file (\.{splint.w}) for details.}. Under most circumstances, the parser output is `executed' and the macros in the output are the ones reading the various streams using the pointers supplied at the parsing stage (at least, this is the case for all the parsers supplied with the @@ -1532,7 +1544,9 @@ how the tables produced by \bison\ get converted into \TeX\ {\it macros\/} that drive the parser in {\it \TeX}. The tables that drive the \bison\ input parsers -are collected in \.{\{b,d,f,g,n\}yytab.tex} and \.{small\_tab.tex}. Each +are collected in \.{\{b,d,f,g,n\}yytab.tex}, \.{small\_tab.tex} and other similarly named +files\footnote{Incidentally, one of the names above is not used anymore. See the \.{cweb} +directory after a successful build to find out which. Aren't footnotes great?!}. Each one of these files contains the tables that implement a specific parser used during different stages of processing. Their exact function is well explained @@ -1584,30 +1598,34 @@ it after \.{\\classexpand} (such sequences are usually prepared by the \bison\ from your grammar). You can give a case a readable label (say, \.{brackets}) and enclose -this label in \.{\\raw}$\ldots$\.{\\raw}. A word of caution: an `\.{a}' -inside of \.{\\raw}$\ldots$\.{\\raw} (which is most likely an -\.{a}$_{11}$ unless you played with the category codes before loading the -\.{\\switchon} macros) and the one outside it are two different +this label in \.{\\raw}$\ldots$\.{\\raw}. A word of caution: an +`\.{a}' inside of \.{\\raw}$\ldots$\.{\\raw} (which is most likely an +\.{a}$_{11}$ unless you played with the category codes before loading +the \.{\\switchon} macros) and the one outside it are two different characters, as one is no longer a letter (category 11) in the eyes of \TeX\ whereas the other one still is. For this reason one should not -use characters other than letters in h\.{\{}is\.{,}er\.{\}} state -{\em names}: the way a state picks an action does not distinguish between, +use characters other than letters in h\.{\{}is\.{,}er\.{\}} state {\em +names\/} if such characters can form tokens by themselves: +the way a state picks an action does not distinguish between, say, a `\.{(}' in `\.{(letter)}' and a stand alone `\.{(}' and may pick an action that you did not intend\footnote{One way to mitigate this is by putting such named states at the end of the switch, {\em -after\/} the actions labelled by the standalone characters.}. -This applies even if `\.{(}' -is not among the characters explicitly inserted in the state macro: if -an action for a given character is not found in the state macro, the -\.{\\switchon} macro will insert a current \.{\\default} action -instead, which most often you would want to be \.{\\yylex} or -\.{\\yyinput} (i.e.\ skip this token). If a single `\.{(}' or `\.{)}' matches -the braced group that follows `\.{(letter)}' chaos may ensue (most -likely \TeX\ will keep reading past the \.{\\end} or \.{\\yyeof} that -should have terminated the input). Make the names of character -categories as unique as possible: the \.{\\switchon} is simply a -string matching mechanism, with the added differentiation between -characters of different categories. +after\/} the actions labelled by the standalone characters. There is nothing +special about non-letter characters, of course. To continue the \.{letter} +example, placing a state named \.{let} {\em after\/} the \.{letter} one +will make it essentially invisible to the switch macros for the reasons +explained before this footnote.}. This applies even if `\.{(}' is not among +the characters explicitly +inserted in the state macro: if an action for a given character is not +found in the state macro, the \.{\\switchon} macro will insert a +current \.{\\default} action instead, which most often you would want +to be \.{\\yylex} or \.{\\yyinput} (i.e.\ skip this token). If a +single `\.{(}' or `\.{)}' matches the braced group that follows +`\.{(letter)}' chaos may ensue (most likely \TeX\ will keep reading +past the \.{\\end} or \.{\\yyeof} that should have terminated the +input). Make the names of character categories as unique as possible: +the \.{\\switchon} is simply a string matching mechanism, with the +added differentiation between characters of different categories. Finally, the construct \.{\\statecomment}{\it anything\/}\.{\\statecomment} allows you to insert comments in the @@ -1620,15 +1638,14 @@ makes the debugging information difficult to decipher). The debugging mode for the lexer implemented with these macros is activated by \.{\\tracedfatrue}. -The functionality of the \.{\\switchon} (as well as the \.{\\switchonwithtype}, which -is capable of some rudimentary type checking) macros (for `historical' -reasons, one can also use \.{\\action} as a synonym for the latter) has been -implemented in a number of other macro packages (see \cite[Fi] that -discusses the well-known and widely used \.{\\CASE} and \.{\\FIND} -macros). The macros in this collection have the additional property -that the only assignments that persist after the \.{\\switchon} -completes are the ones performed by the user code inside the selected -case. +The functionality of the \.{\\switchon} (as well as the +\.{\\switchonwithtype}, which is capable of some rudimentary type +checking) macros has been implemented in a number of other macro +packages (see \cite[Fi] that discusses the well-known and widely used +\.{\\CASE} and \.{\\FIND} macros). The macros in this collection have +the additional property that the only assignments that persist after +the \.{\\switchon} completes are the ones performed by the user code +inside the selected case. This last property of the switch macros is implemented using another mechanism that is part of this macro suite: the `subroutine-like' @@ -1662,7 +1679,10 @@ be able to write parsers of arbitrary sophistication: value of the $n$-th term of the rule's right hand side, $n>0$. The left hand side of a production is accessed through \.{\\yyval}. A convenient shortcut is \.{\\yy0\{{\rm \TeX\space material}\}} which -will expand (as in \.{\\edef}) the `\TeX\ material' inside the braces. Thus, a simple way +will expand (as in \.{\\edef}) the `\TeX\ material' inside the braces and store the result +in \.{\\yyval} (note that this only works if a sequence of \.{0}s, possibly followed or preceeded +by spaces are the only tokens between \.{\\yy} and the opening braces; see the discussion of +\.{\\bb} macros below for a description of what happens in other cases). Thus, a simple way to concatenate the values of the first two production terms is \.{\\yy0\{\\the\\yy(1)\\the\\yy(2)\}}. The included \bison\ parser can also be used to provide support for `symbolic names', @@ -1673,8 +1693,9 @@ however. There is also a \.{\\bb$\,n$} macro, that has no analogue in the `real' \bison\ parsers, and provides access to the term -values in the `natural order' (e.g.~\.{\\bb1} is the last term read). Its -intended use is with the `inline' rules (see the main parser for +values in the `natural order' (e.g.~\.{\\bb1} is the last term in the part of +the production preceeding the action). Its intended use is with the `inline' +rules (see the main parser for such examples). As of version \.{3.0} \bison\ no longer outputs |yyrhs| and |yyprhs|, which makes it impossible to produce the |yyrthree| array necessary for processing such rules in the `left to right' @@ -1682,13 +1703,41 @@ order. One might also note that the new notation is better suited for the inline rules since the value that is pushed on the stack is that of \.{\\bb0}, i.e.~the term implicitly inserted by \bison. Be aware that there are no \.{\\bb[$\cdot$]} or \.{\\bb($\cdot$)} versions of -these macros, for obvious reasons. A less obvious feature of this +these macros, for obvious reasons\footnote{The obvious reason is the mechanism +used by \.{\\yy[$\cdot$]} and \.{\\yy($\cdot$)} to make them expandable. +These macros are basically references to the appropriate token registers. Since +the \.{\\bb} macros were designed for the environment where \.{\\yylen} is unknown, +establishing such references before the action is executed is not possible. A +less obvious reason is the author's lazy approach.}. A less obvious feature of this macro is its `nonexpandable' nature. This means they cannot be used -inside \.{\\edef}. Thus, the most common use pattern is -\.{\\bb$\,n$\{\\toks$\,m$\}} with a subsequent expansion of -\.{\\toks$\,m$}. Making these macros expandable is certainly possible +inside \.{\\edef} (just like its \.{\\yy$\,n$} counterpart, it makes several +assignments which will not be executed by \.{\\edef}). +Thus, the most common use pattern is \.{\\bb$\,n$\{\\toks$\,m$\}} (where $n>0$) +with a subsequent expansion of \.{\\toks$\,m$}\footnote{Similar to how \.{\\yy$\,n$} macros +work, whenever $n>0$, this pattern simply puts the contents of the braced group +that follows in front of a (braced) single expansion of the appropriate +value on the stack. If, as in the example above, the contents of the +braced group are \.{\\toks$\,m$}, this effectively stores the value of the braced group in +the token register. In the case $n=0$ the meaning is different: +the stack value {\em corresponding to the implicit term\/} becomes the expanded (by \.{\\edef}) +contents of the braced group following \.{\\bb$\,n$}.}. +Making these macros expandable is certainly possible but does not seem crucial for the intended limited use pattern. +Finally, the scripts included with \splint\ include a postprocessor +(see the appropriate~\.{Makefile} for further details) that allows the +use of the `native' \bison\ term references (i.e.\ of the form +\.{\char`\$}$\ldots$) to access the value stack\footnote{Incidentally, +\bison\ itself uses a preprocessor (\.{M4}) to turn its term references +into valid \Cee.}. Utilizing the postprocessor allows any syntax for +term references used by \bison\ to be used inside \.{TeX}$\ldots$ \Cee\ macros. +In this case a typical +idiom is \.{\\the\char`\$[term\_name]} to get the value of +\prodstyle{term_name}. While storing a new value for the term (i.e.\ +modifying the value stack) is also possible, it is not very +straightforward and thus not recommended. This applies to all forms of +term references discussed above. + Naturally, a parser writer may need a number of other data abstractions to complete the task. Since these are highly dependent on the nature of the processing the parser is supposed to provide, we @@ -1703,7 +1752,8 @@ most importantly, to create `reentrant' parsers that can, e.g.\ call {\it themselves\/} recursively. @*1 `Optimization'. -\namedspot{optimization}By default, the generated parser and scanner keep all of their tables +\namedspot{optimization}By default, the generated parser and scanner +keep all of their tables in separate token registers. Each stack is kept in a single macro (this description is further complicated by the support for parser {\it namespaces\/} that exists even for unoptimized parsers but this @@ -1806,7 +1856,8 @@ appropriate terms in a production. If mathematics pays your bills, use \let\hostparsernamespace\mainnamespace % to typeset examples in the text % properly -@**Index. This section is, perhaps, the most valuable product of +@**Index. \global\let\secrangedisplay\empty% do not show the current section range anymore +This section is, perhaps, the most valuable product of \CWEB's labors. It lists references to definitions (set in {\it italic}) as well as uses for each \Cee\ identifier used in the source. Special facilities have been added to extend the indexing to @@ -1845,7 +1896,7 @@ appeared on the left hand side of a production. A production: }% \beginmprod left_hand_side: - term.1 term.2 term.3 \{\stashed{|TeX_("/do/something/yy(1)");|}\} + term.1 term.2 term.3 \{\stashed{|TeX_("/do/something/with/yy(1)");|}\} \endmprod inside the \TeX\ part of a \CWEB\ section will generate several index entries, as well, including the entries for any @@ -1865,20 +1916,18 @@ available, thus avoiding referencing the same token twice). \TeX\ control sequences are listed following the index of all \bison\ and \flex\ entries. The different sections of the index are separated by a {\it dinkus\/} -(\dinkus). Since it is nearly impossible to determine at what point a +(\dinkus)@^dinkus (\dinkus)@>. Since it is nearly impossible to determine at what point a \TeX\ macro is defined (and most of them are defined outside of the \CWEB\ sources), only their uses are listed (to be more precise, {\it every\/} appearance of a macro is assumed to be its use). In a few cases, a `graphic' representation for a control sequence appears in the index (for -example, {\let\writetexidxentry\writetextxtidxentry -\def\texnspace{texline}\def\texispace{index}\inlineTeXx{/getfirst}} represents +example, \texref{/getfirst} represents {\let\writetexidxentry\writetextxtidxentry \def\texnspace{other}\def\texispace{other}\inlineTeXx{/getfirst}$\!$}). The index entries are ordered alphabetically. The latter may not be entirely obvious in the cases when the `graphical representation' of the corresponding token manifests a significant -departure from its string version (such as -{\let\writetexidxentry\writetextxtidxentry|TeX_("/yy(1)");|} +departure from its string version (such as \texref{/yy(1)} instead of {\def\texnspace{other}\def\texispace{other}% \let\writetexidxentry\writetextxtidxentry |TeX_("/yy(1)");|$\!$}). Incidentally, for the examples on this page @@ -1886,11 +1935,8 @@ instead of {\def\texnspace{other}\def\texispace{other}% the `graphic' as well as `text' versions of the control sequence are indexed. It is instructive to verify that their location in the index corresponds to the `spelling' of their visual representation (thus, -{\let\writetexidxentry\writetextxtidxentry -\def\texnspace{texline}\def\texispace{index}\inlineTeXx{/getfirst}} -appears under `p'). One should also be aware that the indexing of some terms has -been suppressed, since they appear too often. -\unsetfootnotes % this way the footnote stream is not affected by the extra index pages +\texref{/getfirst} appears under `p'). One should also be aware that +the indexing of some terms has been suppressed, since they appear too often. % TODO: explain the visibility system. Note the anomalous order of \prodstyle{term.1} % vs.~\prodstyle{term0} due to the dot in \.{term.1}, which is otherwise invisible. Underscore the % importance of following a consistent naming scheme, including the `stringized' versions @@ -1899,15 +1945,5 @@ been suppressed, since they appear too often. @q the lack of control over the generation of \CWEB's index; the correct order @> @q of index entries depends on the placement of this inclusion @> @i alphas.hx - -\closeout\gindex -\termindexfalse % do not attach indexing entries to the terms in the index, or the section list -\def\next{\expandafter\eatone\string} -\edef\unindexable{{\next\the}{\next\nx}{\next\yy}{\next\yylexnext}{\next\else}{\next\fi}{\next\yyBEGIN}{\next\next}} -\input gindex.sty -%\indexverbosetrue -\let\inx\inxmod -\let\fin\finmod -\lxrefseparator % start generating section lists -%\displaytokenrawtrue % so that the `nonstringified' version of the token is displayed as well -\def\topofcontents{\null\vskip-3\baselineskip\centerline{C{\sc ONTENTS} (\sc\uppercase\expandafter{\title})}\medskip} +\makeunindexablex{{\csstring\the}{\csstring\nx}{\csstring\yy}{\csstring\yylexnext}% + {\csstring\else}{\csstring\fi}{\csstring\yyBEGIN}{\csstring\next}} diff --git a/support/splint/cweb/ssffo.w b/support/splint/cweb/ssffo.w deleted file mode 100644 index 315bffc798..0000000000 --- a/support/splint/cweb/ssffo.w +++ /dev/null @@ -1,123 +0,0 @@ -@q Copyright 2012-2020, Alexander Shibakov@> -@q This file is part of SPLinT@> - -@q SPLinT is free software: you can redistribute it and/or modify@> -@q it under the terms of the GNU General Public License as published by@> -@q the Free Software Foundation, either version 3 of the License, or@> -@q (at your option) any later version.@> - -@q SPLinT is distributed in the hope that it will be useful,@> -@q but WITHOUT ANY WARRANTY; without even the implied warranty of@> -@q MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the@> -@q GNU General Public License for more details.@> - -@q You should have received a copy of the GNU General Public License@> -@q along with SPLinT. If not, see .@> -\input limbo.sty -\def\optimization{5} -\input yy.sty -\modenormal -\let\oldN\N -\let\N\textN -\let\M\textM -% uncomment the next line to leave the typesetting of tokens in its raw state. -%\def\hostparsernamespace{[unreacheable]} -\let\hostparsernamespace\mainnamespace -\input btokenset.sty - -@** A simple scanner for \flex\ options. -This is a `bare-bones' scanner for a subset of the `extended' \bison\ -grammar that parses some of the `extensions', namely, the -\flex\ state declarations. It does not use the state mechanism -itself, and is supposed to be used with the bootstrapping parser, even -though this is not strictly necessary. It parses state declarations as -long as they are separated into their own \CWEB\ sections and extracts -the {\it names\/} of the states. The \flex\ scanner output `driver' -does the rest after including the produced header file. - -If reusing the existing scanner for \bison\ were not a priority a -proper way to design a scanner like this is to make it a subset of the -existing scanner code. This way portions of the program would be made -more reusable and the overall design made more consistent. -@s TeX_ TeX -@(ssffo.ll@>= -@G - @> @ @= -%{@> @ @=%} - @> @ @= -%% - @> @ @= -%% -@g - -@ A couple of handy abbreviations to get started. Note that the -definition of a letter is more restrictive in this case since we only -need to grab the states of an existing \bison\ lexer. For a -bootstrapping scanner like this it is beneficial to fail early while -scanning something that is not in its attention domain: it results in -faster bootstrapping and lower chance of accidentally parsing -something that should not have been. Making the syntax and the grammar -more restrictive helps to acheive this, as well as makes the overall -design simpler. -@= -@G(fs1) -letter [_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ] -id {letter}({letter}|[-0-9])* -@g - -@ @= - -#include -#include - - void define_all_states( void ){} - -@ A standard combination of options to match the \TeX\ code that -drives the scanner. -@= -@G -%option bison-bridge -%option noyywrap nounput noinput reentrant -%option noyy_top_state -%option debug -%option stack -%option outfile="ssffo.c" -@g - -@ There are not that many regular expressions to list, since the range -of tokens recognized by this routine is not very wide. -@= - @@; - @@; - -@ White space skipping. -@= -@G(fs2) -[ \f\n\t\v] {@> @[TeX_( "/yylexnext" );@]@=} -@g - -@ The rest of it are either identifiers or \.{\%}-options. The typesetting of -the appropriate \bison\ tokens below was arranged by inputting \.{btokenset.sty} and -relying on the pretty-printing macros for {\it \TeX} to do their job. -@= -@G(fs2) -{id} {@> @ @=} -"%x" {@> @[TeX_( "/yylexreturnptr{FLEX_STATE_X}" );@] @=} -"%s" {@> @[TeX_( "/yylexreturnptr{FLEX_STATE_S}" );@] @=} -. {@> @ @=} -@g - -@ @= - @[TeX_( "/iftracebadchars" );@]@; - @[TeX_( " /yycomplain{invalid character(s): /the/yytext}" );@]@; - @[TeX_( "/fi" );@]@; - @[TeX_( "/yylexreturn{$undefined}" );@]@; - -@ The lexer returns standard \.{\\yyunion} types. -@= - @[TeX_( "/edef/next{/yylval{{/the/yytextpure}{/the/yytext}" );@]@; - @[TeX_( " {/the/yyfmark}{/the/yysmark}}}/next" );@]@; - @[TeX_( "/yylexreturn{ID}" );@]@; - -@** Index. -\def\TeXx{\TeX\ material} \ No newline at end of file diff --git a/support/splint/doc/ldman.pdf b/support/splint/doc/ldman.pdf index d1d798816a..9e53467d24 100644 Binary files a/support/splint/doc/ldman.pdf and b/support/splint/doc/ldman.pdf differ diff --git a/support/splint/doc/splint.pdf b/support/splint/doc/splint.pdf index 76600ea682..9f031110ac 100644 Binary files a/support/splint/doc/splint.pdf and b/support/splint/doc/splint.pdf differ diff --git a/support/splint/examples/count/count.sty b/support/splint/examples/count/count.sty index d9fed05f94..d697096141 100644 --- a/support/splint/examples/count/count.sty +++ b/support/splint/examples/count/count.sty @@ -1,4 +1,4 @@ -% Copyright 2012-2020, Alexander Shibakov +% Copyright 2012-2022, Alexander Shibakov % This file is part of SPLinT % % SPLinT is free software: you can redistribute it and/or modify diff --git a/support/splint/examples/expression/Makefile b/support/splint/examples/expression/Makefile index 6f306939b6..741e94664c 100644 --- a/support/splint/examples/expression/Makefile +++ b/support/splint/examples/expression/Makefile @@ -1,4 +1,4 @@ -# Copyright 2012-2020, Alexander Shibakov +# Copyright 2012-2022, Alexander Shibakov # This file is part of SPLinT # # SPLinT is free software: you can redistribute it and/or modify @@ -54,7 +54,7 @@ test.tex ${PARSER}.yy ${LEXER}.ll: expression.x expression.tex: expression.x @${CWEAVE} $< -expression.pdf: expression.tex ${SPLINT_XPTABLES} ${SPLINT_XLTABLES} ${SPLINT_ROOT}cweb/bo.tok ${SPLINT_ROOT}cweb/fo.tok etoks.sty +expression.pdf: expression.tex ${SPLINT_XTABLES} etoks.sty @${PDFTEX} $< test: test.tex ptab.tex ltab.tex diff --git a/support/splint/examples/expression/etoks.sty b/support/splint/examples/expression/etoks.sty index 706ad35818..6df6c0d3be 100644 --- a/support/splint/examples/expression/etoks.sty +++ b/support/splint/examples/expression/etoks.sty @@ -1,4 +1,4 @@ -% Copyright 2012-2020, Alexander Shibakov +% Copyright 2012-2022, Alexander Shibakov % This file is part of SPLinT % % SPLinT is free software: you can redistribute it and/or modify diff --git a/support/splint/examples/expression/expression.sty b/support/splint/examples/expression/expression.sty index ac0d8ba7e5..8fe0970159 100644 --- a/support/splint/examples/expression/expression.sty +++ b/support/splint/examples/expression/expression.sty @@ -1,4 +1,4 @@ -% Copyright 2012-2020, Alexander Shibakov +% Copyright 2012-2024, Alexander Shibakov % This file is part of SPLinT % % SPLinT is free software: you can redistribute it and/or modify diff --git a/support/splint/examples/expression/expression.w b/support/splint/examples/expression/expression.w index 9e96ea44d0..1f6a2f6b61 100644 --- a/support/splint/examples/expression/expression.w +++ b/support/splint/examples/expression/expression.w @@ -1,4 +1,4 @@ -@q Copyright 2012-2020, Alexander Shibakov@> +@q Copyright 2012-2024, Alexander Shibakov@> @q This file is part of SPLinT@> @q SPLinT is free software: you can redistribute it and/or modify@> @@ -16,9 +16,12 @@ \input limbo.sty \def\optimization{5} \input yy.sty +\input dcols.sty \modenormal +\initauxstream -@** Parser file. This is an example parser for expressions. It takes +@** Parser file. +This is an example parser for expressions. It takes advantage of some of the features of \splint\ generated parsers, although anything that takes more than a straightforward setup is omitted. @@ -140,8 +143,6 @@ as they have to be inserted in a place that is aware of the internal definitions definitions are used. @<\.{expression} parser \Cee\ postamble@>= -#define YYPRINT(file, type, value) @[yyprint (file, type, value)@] - static void yyprint (FILE *file, int type, YYSTYPE value){} @ Union of types. Empty as well. @@ -175,7 +176,7 @@ int [0-9]+ void define_all_states( void ){} @ @= -@G +@G(fs1) %option bison-bridge %option noyywrap nounput noinput reentrant %option noyy_top_state @@ -206,13 +207,14 @@ int [0-9]+ @[TeX_( "/iftracebadchars" );@]@; @[TeX_( " /yycomplain{invalid character(s): /the/yytext}" );@]@; @[TeX_( "/fi" );@]@; - @[TeX_( "/yylexreturn{$undefined}" );@]@; + @[TeX_( "/yyerrterminate" );@]@; @*Test file. The test file includes a handy list of debugging options that can be activated to see the inner workings of the parser and scanner routines. @(test.txx@>= @G +\chardef\other=12 % needed for some macros to work \input expression.sty \iffalse @@ -240,7 +242,7 @@ scanner routines. \bye @g -@**Index. -\immediate\closeout\exampletable +@**Index.\global\let\secrangedisplay\empty% do not show the current section range anymore +\global\topskip=9pt \def\Tex{\TeX\ output} \def\TeXx{\TeX\ output} diff --git a/support/splint/examples/ld/Makefile b/support/splint/examples/ld/Makefile index 24bf4a7a9f..8d876e55c9 100644 --- a/support/splint/examples/ld/Makefile +++ b/support/splint/examples/ld/Makefile @@ -1,4 +1,4 @@ -# Copyright 2012-2020, Alexander Shibakov +# Copyright 2012-2024, Alexander Shibakov # This file is part of SPLinT # # SPLinT is free software: you can redistribute it and/or modify @@ -22,10 +22,11 @@ PARSER = ldp LEXER = ldl MANUAL = ldman -LD_CORE_PREREQS = ${SPLINT_XTEXSTYLES} ${SPLINT_XPTABLES} ${SPLINT_XLTABLES} ${SPLINT_ROOT}cweb/bo.tok ${SPLINT_ROOT}cweb/fo.tok -LD_DOC_PREREQS = %.tex %.sty ${PARSER}.tok ldunion.sty ldtexlex.sty ldint.sty ldfrontmatter.sty ${LD_CORE_PREREQS} -LD_DOC_PREREQS += ptab.tex ltab.tex ld_small_tab.tex ld_small_dfa.tex ltokenset.sty lstokenset.sty -LD_DOC_PREREQS_XREF = ${LD_DOC_PREREQS} %.scn %.idx +LD_CORE_PREREQS = ${SPLINT_XTEXSTYLES} ${SPLINT_XTABLES} +LD_DOC_PREREQS_STATIC = ldunion.sty ldtexlex.sty ldint.sty ltokenset.sty lstokenset.sty +LD_DOC_PREREQS_GEN = ldptab.tex ldltab.tex ld_small_tab.tex ld_small_dfa.tex ${PARSER}.tok ldsetup.sty +LD_DOC_PREREQS_XREF = ${LD_CORE_PREREQS} %.sty ${LD_DOC_PREREQS_STATIC} %.tex ${LD_DOC_PREREQS_GEN} %.scn %.idx +LD_DOC_PREREQS_XREF += ldfrontmatter.sty include ../../makefile.inc include ${SPLINT_ROOT}makefile.loc @@ -35,13 +36,13 @@ include ${SPLINT_ROOT}makefile.loc ptabout: ${SPLINT_ROOT}cweb/mkeparser.c ${PARSER}.c ${CC} ${BISON_STATE} -DPARSER_FILE=\"../examples/ld/$(lastword $^)\" -DYYPARSE_PARAMETERS= -o $@ $< -ptab.tex: ptabout +ldptab.tex: ptabout $< --optimize-actions --optimize-tables $@ ltabout: ${SPLINT_ROOT}cweb/mkscanner.c ldl_states.h ${LEXER}.c ${CC} -DLEXER_FILE=\"../examples/ld/$(lastword $^)\" -o $@ $< -ltab.tex: ltabout +ldltab.tex: ltabout $< --optimize-actions --optimize-tables $@ ${LEXER}.c: ${LEXER}.l @@ -53,7 +54,8 @@ ${PARSER}.yy : ldgram.x ${LEXER}.ll: ldlex.x @${CTANGLE} $< -${MANUAL}.stx: ${MANUAL}.x ldgram.x ldlex.x ldlexo.x ldgramo.x ldnp.x +${MANUAL}.stx \ +ldsetup.stx: ${MANUAL}.x ldgram.x ldlex.x ldlexo.x ldgramo.x ldnp.x ldexample_l.hx ldexample_t.hx alphas.hx @${CTANGLE} $< # term name parser for ld grammar @@ -101,11 +103,13 @@ ldexample_%.hx: ldexample.hw alphas.hx: ${MISCCW} --alpha-list --alpha-length=1 $@ -${MANUAL}.tex: ${MANUAL}.x ldgram.x ldlex.x ldlexo.x ldgramo.x ldnp.x ldexample_l.hx ldexample_b.hx alphas.hx +${MANUAL}.tex: ${MANUAL}.x ldgram.x ldlex.x ldlexo.x ldgramo.x ldnp.x ldexample_l.hx ldexample_t.hx alphas.hx + @echo "Preparing the ${MANUAL}.tex file ..." -${CWEAVE} $< -${MANUAL}.sty: ${MANUAL}.stx - ${UNLINE} $< $@ +${MANUAL}.sty \ +ldsetup.sty:%.sty: %.stx + ${UNLINE} $< $@ ${MANUAL}.gdx: %.gdx: ${LD_DOC_PREREQS_XREF} ${PARSER}.tok @echo "Making the bison and TeX indices ..." @@ -116,11 +120,8 @@ ${MANUAL}.gdx: %.gdx: ${LD_DOC_PREREQS_XREF} ${PARSER}.tok ${MANUAL}.gdy: %.gdy: %.gdx ${BINDX} --fine $^ $@ -${MANUAL}.xxr: %.xxr: %.tex - ${PDFTEX} $*.tex - -${MANUAL}.pdf: %.pdf: ${LD_DOC_PREREQS_XREF} %.gdy %.xxr - ${PDFTEX} $< && touch $*.gdy && touch $*.pdf +${MANUAL}.pdf: %.pdf: ${LD_DOC_PREREQS_XREF} %.gdy %.aux + ${PDFTEX} $*.tex && touch $*.gdy && touch $*.pdf ${PARSER}.tok: ldgram.tex ${MANUAL}.sty ${LD_CORE_PREREQS} ${TEX} ${MODEBOOTSTRAP} \\input $< @@ -130,15 +131,25 @@ ldl_states.h: ldlex.tex ${MANUAL}.sty ${LD_CORE_PREREQS} ldgram.tex ldlex.tex: \ %.tex: %.x - -${CWEAVE} -x $< + @echo "Building ldgram.tex and ldlex.tex." + -${CWEAVE} -x $*.x docs: ${MANUAL}.pdf +install: docs + @cp ${LD_DOC_PREREQS_STATIC} ${SPLINT_INSTALL_DIR}/tex/ + @cp ${LD_DOC_PREREQS_GEN} ${SPLINT_INSTALL_DIR}/cweb/ + +uninstall: + @rm -f $(patsubst %, ${SPLINT_INSTALL_DIR}/tex/%, ${LD_DOC_PREREQS_STATIC}) + @rm -f $(patsubst %, ${SPLINT_INSTALL_DIR}/cweb/%, ${LD_DOC_PREREQS_GEN}) + mostlyclean: clean_temp -rm -f ptabout ltabout ldsmalll_out ldsmallp_out ldnump_out ldnuml_out ${MANUAL}.c clean: clean_core - -rm -f ptabout ltabout ldsmalll_out ldsmallp_out ldnump_out ldnuml_out *.stx ldman.sty + -rm -f ptabout ltabout ldsmalll_out ldsmallp_out ldnump_out ldnuml_out *.stx \ + ldman.sty ldsetup.sty distclean: clean cd ${SPLINT_ROOT} && ${MAKE} clean diff --git a/support/splint/examples/ld/ldexample.hw b/support/splint/examples/ld/ldexample.hw index a5cab97d2a..d9cb732624 100644 --- a/support/splint/examples/ld/ldexample.hw +++ b/support/splint/examples/ld/ldexample.hw @@ -4,7 +4,7 @@ MEMORY { @> @ @= RAM (xrw) : ORIGIN = 0x20000000, LENGTH = 20K - FLASH (rx) : ORIGIN = 0x8000000, LENGTH = 128K + FLASH (rx!w) : ORIGIN = 0x8000000, LENGTH = 128K ASH (rx) : ORIGIN = 8001000, LENGTH = 128K @> @ @= CLASH (rx) : ORIGIN = 700000, LENGTH = 128K @@ -27,6 +27,7 @@ ENTRY(_entry); SECTIONS { @> @ @= + . = ORIGIN(FLASH); .isr_vector ALIGN(8) (NOLOAD): AT(.) ALIGN(.) ALIGN_WITH_INPUT SUBALIGN(8) SPECIAL { . = ALIGN(4); @@ -73,5 +74,18 @@ SECTIONS _ebss = . ; } >RAM @> @ @= + . = ALIGN(0x0001ABCD); + _ffbegin = .; + OVERLAY : NOCROSSREFS AT ( _ffabs ) { + .free_func0 + { + *(.free_func0) + . = ALIGN(4); + } + .free_func1 + { + *(.free_func1) + } + } >RAM } diff --git a/support/splint/examples/ld/ldgram.w b/support/splint/examples/ld/ldgram.w index 5e7ff73a03..3671ee52ce 100644 --- a/support/splint/examples/ld/ldgram.w +++ b/support/splint/examples/ld/ldgram.w @@ -1,4 +1,4 @@ -@q Copyright 2012-2020 Alexander Shibakov@> +@q Copyright 2012-2022 Alexander Shibakov@> @q Copyright 2002-2014 Free Software Foundation, Inc.@> @q This file is part of SPLinT@> @@ -18,10 +18,12 @@ @** The parser. \ifbootstrapmode \def\tokendeffile{ldp.tok}% - \input ldman.sty + \input ldman.sty + \def\bstrapparser{dyytab.tex}% only the full or preamble parser would know how to + % parse grammar sections that mix \prodstyle{\%token} + % declarations with other \bison\ syntax + \def\bstraptokens{bo.tok}% token equivalences for the full lexer \modebootstrap - \input dcols.sty - \setupfootnotes \def\MRI{} \def\ld{} \fi @@ -76,8 +78,6 @@ is supplied by the \TeX\ macros in \.{ldman.sty}. @ @= @ @<\ld\ parser \Cee\ postamble@>= -#define YYPRINT(file, type, value) yyprint (file, type, value) - static void yyprint (FILE *file, int type, YYSTYPE value){} @ @<\ld\ parser productions@>= @<\GNU\ \ld\ script rules@>@; @@ -129,13 +129,13 @@ by the \ld\ parser are put in a single list. %left OROR ANDAND '|' '^' '&' EQ NE '<' '>' LE GE LSHIFT RSHIFT '+' '-' '*' '/' '%' '(' @g -@*1 Grammar rules, an overview. +@*1 Grammar rules, an overview. The first natural step in transforming an existing parser into a `parser stack' for pretty printing is to understand the `anatomy' of the grammar. Not every grammar is suitable for such a transformation and in almost every case, some modifications are needed. The parser and lexer implementation for \ld\ is not terrible although it does -have some idiosynchasies that could have been eliminated by a careful +have some idiosynchrasies that could have been eliminated by a careful grammar redesign. Instead of invasive rewriting of significant portions of the grammar, the approach taken here merely omits some rules and partitions the grammar into several subsets, each of which @@ -143,7 +143,7 @@ is supposed to handle a well defined logical section of an \ld\ script file. One example of a trick used by the \ld\ parser that is not appropriate for a -pretty printing grammar implements a way of handling the choice of the +pretty printing grammar is the way the original parser handles the choice of the format of an input file. After a command line option that selects the input format has been read (or the format has been determined using some other method), the first token output by the lexer branches the @@ -219,12 +219,14 @@ defsym_expr: @ {\it Syntax within an \MRI\ script file}\footnote{As explained at the beginning of this chapter, the text in {\it italics\/} was taken from -the original comments by \ld\ parser and lexer programmers.}. The parser for typesetting +the original comments by the \ld\ parser and lexer programmers.}. The parser for typesetting is only intended to process \GNU\ \ld\ scripts and does not concern itself with any additional compatibility modes. For this reason, all support for \MRI\ style scripts has been omitted. One use for the section below is a small demonstration of the formatting tools that change the output of the \bison\ parser. +%\checktabletrue +%\tracingliststrue @<\MRI\ style script rules@>= @G @t}\vb{\inline\flatten}{@> @@ -315,6 +317,8 @@ casesymlist: @ {\it Parsed as expressions so that commas separate entries.} The core of the parser consists of productions describing \GNU\ \ld\ linker scripts. The first rule is common to both \MRI\ and \GNU\ formats. +\checktablefalse +\tracinglistsfalse @<\GNU\ \ld\ script rules@>= @G extern_name_list: @@ -435,7 +439,7 @@ sections: sec_or_group_p1: sec_or_group_p1 section {@>@@=} - | sec_or_group_p1 statement_anywhere {@>@@=} + | sec_or_group_p1 statement_anywhere {@>@@=} | {@>@[TeX_( "/yy0{}" );@]@=} ; @@ -451,10 +455,20 @@ statement_anywhere: @[TeX_( "/yy0{/nx/ldinsertcweb/the/yy(1){sect}{/nx/ldsections{/the/yy(3)/nx/ldsectionstash/the/yy(4)}}}" );@] @ @= - @[TeX_( "/getsecond{/yy(2)}/to/tokse/getthird{/yy(2)}/to/toksf" );@]@; - @[TeX_( "/getfourth{/yy(2)}/to/toksg/getfifth{/yy(2)}/to/toksh" );@]@; - @[TeXb( "/yytoksempty{/yy(1)}{/yy0{/nx/ldsectionstash{/the/tokse}{/the/toksf}/the/toksh}}" );@]@; - @[TeXfo( " {/yy0{/the/yy(1)/nx/ldsectionseparator{/the/tokse}{/the/toksf}/the/toksh}}" );@]@; + @[TeX_( "/yytoksempty{/yy(2)}{/yy0{/the/yy(1)}}{" );@]@; + @[TeX_( " /getsecond{/yy(2)}/to/tokse/getthird{/yy(2)}/to/toksf" );@]@; + @[TeX_( " /getfourth{/yy(2)}/to/toksg/getfifth{/yy(2)}/to/toksh" );@]@; + @[TeXb( " /yytoksempty{/yy(1)}{/yy0{/nx/ldsectionstash{/the/tokse}{/the/toksf}/the/toksh}}" );@]@; + @[TeXa( " {/yy0{/the/yy(1)/nx/ldsectionseparator{/the/tokse}{/the/toksf}/the/toksh}}" );@]@; + @[TeXfo( "}" );@]@; + +@ @= + @[TeX_( "/yytoksempty{/yy(2)}{/yy0{/the/yy(1)}}{" );@]@; + @[TeX_( " /getsecond{/yy(2)}/to/tokse/getthird{/yy(2)}/to/toksf" );@]@; + @[TeX_( " /getfourth{/yy(2)}/to/toksg/getfifth{/yy(2)}/to/toksh" );@]@; + @[TeXb( " /yytoksempty{/yy(1)}{/yy0{/nx/ldsectionstash{/the/tokse}{/the/toksf}/nx/ldfreestmt{/the/toksh}}}" );@]@; + @[TeXa( " {/yy0{/the/yy(1)/nx/ldsectionseparator{/the/tokse}{/the/toksf}/nx/ldfreestmt{/the/toksh}}}" );@]@; + @[TeXfo( "}" );@]@; @ @= @[TeX_( "/yy0{/nx/ldinsertcweb/the/yy(1){stmt}{/nx/ldstatement{/nx/ldentry{/nx/ldregexp{/the/yy(3)}}}}}" );@] @@ -631,14 +645,14 @@ length: | SHORT {} | BYTE {} ; - +@t}\vb{\resetf\inline}{@> fill_exp: mustbe_exp {@>@@=} ; - +@t}\vb{\flatten}{@> fill_opt: - '=' fill_exp {@>@[TeX_( "/yy0{/noexpand/ldfill{/the/yy(2)}}" );@]@=} - | {@>@[TeX_( "/yy0{}" );@]@=} + {@>@[TeX_( "/yy0{}" );@]@=} + | '=' fill_exp {@>@[TeX_( "/yy0{/noexpand/ldfill{/the/yy(2)}}" );@]@=} ; @t}\vb{\resetf}{@> @@ -710,9 +724,7 @@ memory_spec_list: memory_spec: NAME {} - attributes_opt ':' - origin_spec -@t}\vb{\breakline}{@> + attributes_opt ':' origin_spec opt_comma length_spec {@>@@=} | INCLUDE filename {@>@@=} memory_spec_list_opt END {@>@@=} @@ -759,8 +771,8 @@ attributes_list: ; attributes_string: - NAME {@>@[TeX_( "/yy0{/noexpand/ldattributes{/the/yy(1)}}" );@]@=} - | '!' NAME {@>@[TeX_( "/yy0{/noexpand/ldattributesneg{/the/yy(2)}}" );@]@=} + NAME {@>@[TeX_( "/yy0{/noexpand/ldattrstring/the/yy(1)}" );@]@=} + | '!' NAME {@>@[TeX_( "/yy0{/noexpand/ldattrstringneg/the/yy(2)}" );@]@=} ; startup: @@ -812,7 +824,7 @@ expressions out of simpler chunks and basic building blocks tied together by algebraic operations. @= @G -exp : +exp: '-' exp %prec UNARY {@>@[TeX_( "/yy0{{-/the/yy(2)}}" );@]@=} | '(' exp ')' {@>@[TeX_( "/yy0{(/the/yy(2))}" );@]@=} | NEXT '(' exp ')' %prec UNARY {@>@[TeX_( "/yy0{/hbox{/nx/ssf next}(/the/yy(3))}" );@]@=} @@ -844,28 +856,28 @@ exp : @= @G exp : - DEFINED '(' NAME ')' {} - | INT {} + DEFINED '(' NAME ')' {@>@[TeX_( "/def/ldfuncname{defined}" );@]@@=} + | INT {@>@@=} | SIZEOF_HEADERS {} - | ALIGNOF '(' NAME ')' {} - | SIZEOF '(' NAME ')' {} - | ADDR '(' NAME ')' {} - | LOADADDR '(' NAME ')' {} - | CONSTANT '(' NAME ')' {} - | ABSOLUTE '(' exp ')' {} + | ALIGNOF '(' NAME ')' {@>@[TeX_( "/def/ldfuncname{alignof}" );@]@@=} + | SIZEOF '(' NAME ')' {@>@[TeX_( "/def/ldfuncname{sizeof}" );@]@@=} + | ADDR '(' NAME ')' {@>@[TeX_( "/def/ldfuncname{addr}" );@]@@=} + | LOADADDR '(' NAME ')' {@>@[TeX_( "/def/ldfuncname{loadaddr}" );@]@@=} + | CONSTANT '(' NAME ')' {@>@[TeX_( "/def/ldfuncname{constant}" );@]@@=} + | ABSOLUTE '(' exp ')' {@>@[TeX_( "/yy0{/nx/mathop{/hbox{/nx/ssf absolute}}(/the/yy(3))}" );@]@=} | ALIGN_K '(' exp ')' {@>@[TeX_( "/yy0{/nx/mathop{/hbox{/nx/ssf align}}(/the/yy(3))}" );@]@=} | ALIGN_K '(' exp ',' exp ')' {} | DATA_SEGMENT_ALIGN '(' exp ',' exp ')' {} | DATA_SEGMENT_RELRO_END '(' exp ',' exp ')' {} | DATA_SEGMENT_END '(' exp ')' {} | SEGMENT_START '(' NAME ',' exp ')' {} - | BLOCK '(' exp ')' {} + | BLOCK '(' exp ')' {@>@[TeX_( "/yy0{/nx/mathop{/hbox{/nx/ssf block}}(/the/yy(3))}" );@]@=} | NAME {@>@[TeX_( "/yy0{/nx/ldregexp{/the/yy(1)}}" );@]@=} | MAX_K '(' exp ',' exp ')' {} | MIN_K '(' exp ',' exp ')' {} | ASSERT_K '(' exp ',' NAME ')' {} - | ORIGIN '(' NAME ')' {} - | LENGTH '(' NAME ')' {} + | ORIGIN '(' NAME ')' {@>@[TeX_( "/def/ldfuncname{origin}" );@]@@=} + | LENGTH '(' NAME ')' {@>@[TeX_( "/def/ldfuncname{length}" );@]@@=} | LOG2CEIL '(' exp ')' {} ; @g @@ -875,6 +887,9 @@ exp : @[TeXb( "/yy0{/hbox{/nx/ttl do }/xi(/the/yy(1))/hbox{ /nx/ttl where }" );@]@; @[TeXfo( " {/let/nx/{/nx/bigbracedel/nx/xi(x)=/nx/cases{/the/yy(5)& if /inmath{x=0}/cr/the/yy(3)& if /inmath{x/nx/not=0}}}}" );@]@; +@ @= +@[TeX_( "/yy0{/nx/mathop{/hbox{/nx/ssf /ldfuncname}}(/nx/ldregexp{/the/yy(3))}}" );@] + @ @= @G memspec_at_opt: @@ -966,6 +981,10 @@ section: @[TeXfo( " {{/the/yy(15)}{/the/yy(16)}{/the/yy(17)}{/the/yy(18)}}}}" );@]@; /*memory specifiers */ @ @= + @[TeXb( "/getfirst{/yy(1)}/to/toksa/getsecond{/yy(1)}/to/toksb" );@]@; + @[TeXf( "/yy0{/nx/ldinsertcweb{/the/toksa}{/the/toksb}{osect}{/nx/ldoverlay{/the/yy(3)}{/the/yy(4)}{/the/yy(5)}{/the/yy(6)}" );@]@; + @[TeXf( " {/the/yy(10)}" );@]@;/* sections */ + @[TeXfo( " {{/the/yy(13)}{/the/yy(14)}{/the/yy(15)}{/the/yy(16)}}}}" );@]@; /*memory specifiers, etc.*/ @ @= @G @@ -999,8 +1018,8 @@ opt_exp_with_type: ; opt_exp_without_type: - exp ':' {} - | ':' {} + exp ':' {@>@[TeX_( "/yy0{/the/yy(1)}" );@]@=} + | ':' {@>@[TeX_( "/yy0{}" );@]@=} ; opt_nocrossrefs: @@ -1019,12 +1038,12 @@ phdr_opt: ; overlay_section: - + {@>@[TeX_( "/yy0{}" );@]@=} | overlay_section NAME {@>@[TeX_( "/ldlex@@script" );@]@=} '{' statement_list_opt '}' {@>@[TeX_( "/ldlex@@popstate/ldlex@@expression" );@]@=} phdr_opt fill_opt {@>@[TeX_( "/ldlex@@popstate" );@]@=} - opt_comma + opt_comma {@>@@=} ; @g @@ -1032,6 +1051,15 @@ overlay_section: @[TeXb( "/yytoksempty{/yy(1)}{/yy0{{/the/yy(3)}}}" );@]@; @[TeXao( "{/yy0{/the/yy(1)/noexpand/ldor{/the/yy(3)}}}" );@]@; +@ @= + @[TeXb( "/getthird{/yy(2)}/to/toksa/getfourth{/yy(2)}/to/toksb" );@]@;/* \prodstylens{name}{\ldnamespace} pointers */ + @[TeXf( "/getfifth{/yy(5)}/to/toksc" );@]@;/* \prodstylens{statement\_list\_opt}{\ldnamespace} contents */ + @[TeXf( "/yytoksempty{/yy(1)}{" );@]@; + @[TeXf( " /yy0{/nx/ldoverlaysection{/the/yy(2)}{/the/toksc}{/the/yy(8)}{/the/yy(9)}}" );@]@; + @[TeXf( "}{" );@]@; + @[TeXf( " /yy0{/the/yy(1)/nx/ldoverlaysection{/the/yy(2)}{/the/toksc}{/the/yy(8)}{/the/yy(9)}}" );@]@; + @[TeXfo( "}" );@]@; + @ @= @G phdrs: diff --git a/support/splint/examples/ld/ldgramo.w b/support/splint/examples/ld/ldgramo.w index 46d46f9a1f..a036c858de 100644 --- a/support/splint/examples/ld/ldgramo.w +++ b/support/splint/examples/ld/ldgramo.w @@ -1,4 +1,4 @@ -@q Copyright 2020 Alexander Shibakov@> +@q Copyright 2012-2022 Alexander Shibakov@> @q Copyright 2002-2015 Free Software Foundation, Inc.@> @q This file is part of SPLinT@> @@ -492,17 +492,20 @@ statement_anywhere: ENTRY '(' NAME ')' { lang_add_entry ($3, FALSE); } | assignment end - | ASSERT_K {@>@[ldlex_expression ();@>@=} '(' exp ',' NAME ')' + | ASSERT_K {@>@[ldlex_expression ();@]@=} '(' exp ',' NAME ')' { @O ldlex_popstate (); -@o lang_add_assignment (exp_assert ($4, $6)); +@o } ; @g +@q using a @@[, @@> pair instead of @@[, @@] may lead to some strange spacing artefacts @> +@q due to the lack of \6; it is instructive to see its effects after replacing the @@] with @@> @> +@q in the line containing ASSERT_K @> @ \tracebadcharstrue The {\setrulecontext{wildcardname}\prodstyle{'*'}} and \prodstyle{'?'} cases are there because the lexer returns them as separate tokens rather than as \prodstyle{NAME}. diff --git a/support/splint/examples/ld/ldint.sty b/support/splint/examples/ld/ldint.sty index 83f3068dc5..a96003a53d 100644 --- a/support/splint/examples/ld/ldint.sty +++ b/support/splint/examples/ld/ldint.sty @@ -1,4 +1,4 @@ -% Copyright 2012-2020, Alexander Shibakov +% Copyright 2012-2022, Alexander Shibakov % This file is part of SPLinT % % SPLinT is free software: you can redistribute it and/or modify @@ -203,9 +203,12 @@ } \def\displayinteger#1#2#3#4#5#6#7#8{% - {\def\ldintsep{$\,$}\hbox{\rm#7#8\rlap{${}_{#1}$}$\yystringempty{#2}{}{\lddisplayintsuffix{#2}}$}}% + {\def\ldintsep{$\,$}\hbox{\ldintfont#7#8\ldrlap{${}_{#1}$}$\yystringempty{#2}{}{\lddisplayintsuffix{#2}}$}}% } +\let\ldrlap\rlap +\let\ldintfont\rm + \def\lddisplayintsuffix#1{% \expandafter\ifx\csname ldspecialsuffixdisplay#1\endcsname\relax \,\hbox{\tt#1}% @@ -216,7 +219,7 @@ \def\ldspecialsuffixdisplayK{{}\cdot2^{10}} -\def\ldspecialsuffixdisplayK{\,\hbox{\rm Kb}} +%\def\ldspecialsuffixdisplayK{\,\hbox{\rm Kb}} \def\displayintegerws#1#2#3#4#5#6#7{% {\def\ldintsep{$\,$}\hbox{\rm#6#7\rlap{${}_{\yystringempty{#1}{}{\csname ldradix#1\endcsname}}$}}}% diff --git a/support/splint/examples/ld/ldlex.w b/support/splint/examples/ld/ldlex.w index 2312fd1027..0add0b0294 100644 --- a/support/splint/examples/ld/ldlex.w +++ b/support/splint/examples/ld/ldlex.w @@ -1,4 +1,4 @@ -@q Copyright 2012-2020 Alexander Shibakov@> +@q Copyright 2012-2022 Alexander Shibakov@> @q Copyright 2002-2014 Free Software Foundation, Inc.@> @q This file is part of SPLinT@> @@ -17,10 +17,10 @@ @** The lexer. \ifbootstrapmode - \input ldman.sty - \modebootstrap - \input dcols.sty - \setupfootnotes + \input limbo.sty + \input yystype.sty + \input grabstates.sty + \immediate\openout\stlist=ldl_states.h \def\MRI{} \def\ld{} \fi @@ -37,7 +37,7 @@ the \bison\ parser which is part of this distribution. %{@> @<\ld\ lexer \Cee\ preamble@> @=%} @> @<\ld\ lexer options@> @= %% - @> @<\ld\ token regular expressions@> @= + @> @ @= %% @O void define_all_states( void ) { @@ -47,7 +47,7 @@ void define_all_states( void ) { @g @ @<\ld\ lexer options@>= -@G +@G(fs1) %option bison-bridge %option noyywrap nounput noinput reentrant %option noyy_top_state @@ -57,10 +57,10 @@ void define_all_states( void ) { @g @ @<\ld\ lexer \Cee\ preamble@>= -#include -#include -@ @= +@ The file \.{ldl\_states.h} below contains the names of all the start +conditions@^start conditions@> (or states) collected by the bootstrap parser. +@= #define _register_name( name ) @[Define_State( #name, name )@] #include "ldl_states.h" #undef _register_name @@ -94,7 +94,7 @@ same section simplifies the job of the \locallink{bootstrapstates}bootstrap parser\endlink, as well. \ifbootstrapmode\immediate\openout\stlist=ldl_states.h\fi @<\ld\ lexer states@>= -@G +@G(fs1) %s SCRIPT %s EXPRESSION %s BOTH @@ -117,8 +117,9 @@ function. The typesetting parser uses the \.{\\ldcomment} macro for the same purpose. For the curious, here is a \flex\ style regular expression defining \Cee\ comments\footnote{Taken from W.~McKeeman's site at -\url{http://www.cs.dartmouth.edu/~mckeeman/cs118/assignments/comment.html} -and adapted to \flex\ syntax.}: +\url{http://www.cs.dartmouth.edu/~mckeeman/cs118/assignments/comment.html} and +adapted to \flex\ syntax. Here is the same regular expression pretty printed by +\splint: \flexrestyle{"/*"("/"`[\^*/]`"*"+[\^*/])*"*"+"/"}}: $$ \hbox{\.{"/*" ("/"\yl[\^*/]\yl"*"+[\^*/])* "*"+ "/"}} $$ @@ -193,6 +194,15 @@ possible, however, if \.{\\yylextail} is not used inside actions (in the case of an `optimized' lexer the restriction is even weaker, namely, \.{\\yylextail} merely has to be absent in the portion of the action following \.{\\ldcomment}). + +Another remark might be in order. It would seem more appropriate to +employ \TeX's native grouping mechanism to avoid the side effects +casued by the assignments performed by the macros (such as +\.{\\let\\oldyyreturn\\yyreturn}). While this is possible with some +careful macro writing, a na\:\i ve grouping attempt would interfere +with the assignments performed by \.{\\yymatch} +(e.g.~\.{\\yyresetstreams}). Avoiding assignments like these is still +possible although the effort required is bordering on excessive. @= @G(t) \def\ldcomment#1\yylextail{% @@ -221,14 +231,24 @@ We would like to simulate the file inclusion by inserting the appropriate end of file marker for the lexer (a double \.{\\yyeof}). After the relevant production completes, the marker has to be cleaned up from the input stream (the lexer is designed to -leave it intact). The macros below are designed to handle this assignment. +leave it intact to be able to read the end of file multiple times +while looking for the longest match). + +The macro below is designed to handle this task. The idea is to replace +the double \.{\\yyeof} at the beginning of the input with an appropriate +lexer action. The \.{\\yyreadinput} handles the input buffer and inserts the +tail portion of the current \flex\ action in front of it. @= @G(t) \def\ldcleanyyeof#1\yylextail{% - \let\oldyyinput\yyinput - \def\yyinput\yyeof\yyeof{\let\yyinput\oldyyinput#1\yylextail}% - \yymatch + \yyreadinput{\ldcl@@anyyeof{#1\yylextail}}{\romannumeral0\yyr@@@@dinput}% +} + +\def\ldcl@@anyyeof#1#2#3{% + #3\ldcl@@anyye@@f{#1}#2% } + +\def\ldcl@@anyye@@f#1#2\yyeof\yyeof{#1} @g @*1 Regular expressions. @@ -237,204 +257,166 @@ describe the {\it tokens\/} of the appropriate language. The variey of tokens recognized by \ld\ is quite extensive and is described in the sections that follow. -Variable names and algebraic operations come first. -@<\ld\ token regular expressions@>= +Variable names, constants, and algebraic operations come first. +@= @G(fs2) -"/*" {@> @[TeX_( "/ldcomment/yylexnext" );@]@=} -"-" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"+" {@> @[TeX_( "/yylexreturnchar" );@]@=} -{FILENAMECHAR1}{SYMBOLCHARN}* {@> @[TeX_( "/yylexreturnsym{NAME}" );@]@=} -"=" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"$"([0-9A-Fa-f])+ {@> @ @=} -([0-9A-Fa-f])+(H|h|X|x|B|b|O|o|D|d) {@> @@=} -((("$"|0[xX])([0-9A-Fa-f])+)|(([0-9])+))(M|K|m|k)? { - @> @@=} -"]" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"[" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"<<=" {@> @[TeX_( "/yylexreturnptr{LSHIFTEQ}" );@]@=} -">>=" {@> @[TeX_( "/yylexreturnptr{RSHIFTEQ}" );@]@=} -"||" {@> @[TeX_( "/yylexreturnptr{OROR}" );@]@=} -"==" {@> @[TeX_( "/yylexreturnptr{EQ}" );@]@=} -"!=" {@> @[TeX_( "/yylexreturnptr{NE}" );@]@=} -">=" {@> @[TeX_( "/yylexreturnptr{GE}" );@]@=} -"<=" {@> @[TeX_( "/yylexreturnptr{LE}" );@]@=} -"<<" {@> @[TeX_( "/yylexreturnptr{LSHIFT}" );@]@=} -">>" {@> @[TeX_( "/yylexreturnptr{RSHIFT}" );@]@=} -"+=" {@> @[TeX_( "/yylexreturnptr{PLUSEQ}" );@]@=} -"-=" {@> @[TeX_( "/yylexreturnptr{MINUSEQ}" );@]@=} -"*=" {@> @[TeX_( "/yylexreturnptr{MULTEQ}" );@]@=} -"/=" {@> @[TeX_( "/yylexreturnptr{DIVEQ}" );@]@=} -"&=" {@> @[TeX_( "/yylexreturnptr{ANDEQ}" );@]@=} -"|=" {@> @[TeX_( "/yylexreturnptr{OREQ}" );@]@=} -"&&" {@> @[TeX_( "/yylexreturnptr{ANDAND}" );@]@=} -">" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"," {@> @[TeX_( "/yylexreturnchar" );@]@=} -"&" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"|" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"~" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"!" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"?" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"*" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"+" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"-" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"/" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"%" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"<" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"=" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"}" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"{" {@> @[TeX_( "/yylexreturnchar" );@]@=} -")" {@> @[TeX_( "/yylexreturnchar" );@]@=} -"(" {@> @[TeX_( "/yylexreturnchar" );@]@=} -":" {@> @[TeX_( "/yylexreturnchar" );@]@=} -";" {@> @[TeX_( "/yylexreturnchar" );@]@=} +{ + "/*" {@> @[TeX_( "/ldcomment/yylexnext" );@]@=} +} + +{ + "-" {@> @[TeX_( "/yylexreturnchar" );@]@=} + "+" {@> @[TeX_( "/yylexreturnchar" );@]@=} + {FILENAMECHAR1}{SYMBOLCHARN}* {@> @[TeX_( "/yylexreturnsym{NAME}" );@]@=} + "=" {@> @[TeX_( "/yylexreturnchar" );@]@=} +} + +{ + "$"([0-9A-Fa-f])+ {@> @ @=} + ([0-9A-Fa-f])+(H|h|X|x|B|b|O|o|D|d) {@> @@=} +} + +{ + ((("$"|0[xX])([0-9A-Fa-f])+)|(([0-9])+))(M|K|m|k)? {@> @@=} +} + +{ + "<<=" {@> @[TeX_( "/yylexreturnptr{LSHIFTEQ}" );@]@=} + ">>=" {@> @[TeX_( "/yylexreturnptr{RSHIFTEQ}" );@]@=} + "||" {@> @[TeX_( "/yylexreturnptr{OROR}" );@]@=} + "==" {@> @[TeX_( "/yylexreturnptr{EQ}" );@]@=} + "!=" {@> @[TeX_( "/yylexreturnptr{NE}" );@]@=} + ">=" {@> @[TeX_( "/yylexreturnptr{GE}" );@]@=} + "<=" {@> @[TeX_( "/yylexreturnptr{LE}" );@]@=} + "<<" {@> @[TeX_( "/yylexreturnptr{LSHIFT}" );@]@=} + ">>" {@> @[TeX_( "/yylexreturnptr{RSHIFT}" );@]@=} + "+=" {@> @[TeX_( "/yylexreturnptr{PLUSEQ}" );@]@=} + "-=" {@> @[TeX_( "/yylexreturnptr{MINUSEQ}" );@]@=} + "*=" {@> @[TeX_( "/yylexreturnptr{MULTEQ}" );@]@=} + "/=" {@> @[TeX_( "/yylexreturnptr{DIVEQ}" );@]@=} + "&=" {@> @[TeX_( "/yylexreturnptr{ANDEQ}" );@]@=} + "|=" {@> @[TeX_( "/yylexreturnptr{OREQ}" );@]@=} + "&&" {@> @[TeX_( "/yylexreturnptr{ANDAND}" );@]@=} + [&|~!?*+\-/%=<>{}()\[\]:;,] {@> @[TeX_( "/yylexreturnchar" );@]@=} +} @g @ The bulk of tokens produced by the lexer are the keywords used inside script files. File name syntax is listed as well, along with -miscellanea such as whitespace and version symbols. -@<\ld\ token regular expressions@>= +the miscellanea like whitespace and version symbols. +@= @G(fs2) -"MEMORY" {@> @[TeX_( "/yylexreturnptr{MEMORY}" );@]@=} -"REGION_ALIAS" {@> @[TeX_( "/yylexreturnptr{REGION_ALIAS}" );@]@=} -"LD_FEATURE" {@> @[TeX_( "/yylexreturnptr{LD_FEATURE}" );@]@=} -"ORIGIN" {@> @[TeX_( "/yylexreturnptr{ORIGIN}" );@]@=} -"VERSION" {@> @[TeX_( "/yylexreturnptr{VERSIONK}" );@]@=} -"BLOCK" {@> @[TeX_( "/yylexreturnptr{BLOCK}" );@]@=} -"BIND" {@> @[TeX_( "/yylexreturnptr{BIND}" );@]@=} -"LENGTH" {@> @[TeX_( "/yylexreturnptr{LENGTH}" );@]@=} -"ALIGN" {@> @[TeX_( "/yylexreturnptr{ALIGN_K}" );@]@=} -"DATA_SEGMENT_ALIGN" {@> @[TeX_( "/yylexreturnptr{DATA_SEGMENT_ALIGN}" );@]@=} -"DATA_SEGMENT_RELRO_END" {@> @[TeX_( "/yylexreturnptr{DATA_SEGMENT_RELRO_END}" );@]@=} -"DATA_SEGMENT_END" {@> @[TeX_( "/yylexreturnptr{DATA_SEGMENT_END}" );@]@=} -"ADDR" {@> @[TeX_( "/yylexreturnptr{ADDR}" );@]@=} -"LOADADDR" {@> @[TeX_( "/yylexreturnptr{LOADADDR}" );@]@=} -"ALIGNOF" {@> @[TeX_( "/yylexreturnptr{ALIGNOF}" );@]@=} -"MAX" {@> @[TeX_( "/yylexreturnptr{MAX_K}" );@]@=} -"MIN" {@> @[TeX_( "/yylexreturnptr{MIN_K}" );@]@=} -"LOG2CEIL" {@> @[TeX_( "/yylexreturnptr{LOG2CEIL}" );@]@=} -"ASSERT" {@> @[TeX_( "/yylexreturnptr{ASSERT_K}" );@]@=} -"ENTRY" {@> @[TeX_( "/yylexreturnptr{ENTRY}" );@]@=} -"EXTERN" {@> @[TeX_( "/yylexreturnptr{EXTERN}" );@]@=} -"NEXT" {@> @[TeX_( "/yylexreturnptr{NEXT}" );@]@=} -"sizeof_headers" {@> @[TeX_( "/yylexreturnptr{SIZEOF_HEADERS}" );@]@=} -"SIZEOF_HEADERS" {@> @[TeX_( "/yylexreturnptr{SIZEOF_HEADERS}" );@]@=} -"SEGMENT_START" {@> @[TeX_( "/yylexreturnptr{SEGMENT_START}" );@]@=} -"MAP" {@> @[TeX_( "/yylexreturnptr{MAP}" );@]@=} -"SIZEOF" {@> @[TeX_( "/yylexreturnptr{SIZEOF}" );@]@=} -"TARGET" {@> @[TeX_( "/yylexreturnptr{TARGET_K}" );@]@=} -"SEARCH_DIR" {@> @[TeX_( "/yylexreturnptr{SEARCH_DIR}" );@]@=} -"OUTPUT" {@> @[TeX_( "/yylexreturnptr{OUTPUT}" );@]@=} -"INPUT" {@> @[TeX_( "/yylexreturnptr{INPUT}" );@]@=} -"GROUP" {@> @[TeX_( "/yylexreturnptr{GROUP}" );@]@=} -"AS_NEEDED" {@> @[TeX_( "/yylexreturnptr{AS_NEEDED}" );@]@=} -"DEFINED" {@> @[TeX_( "/yylexreturnptr{DEFINED}" );@]@=} -"CREATE_OBJECT_SYMBOLS" {@> @[TeX_( "/yylexreturnptr{CREATE_OBJECT_SYMBOLS}" );@]@=} -"CONSTRUCTORS" {@> @[TeX_( "/yylexreturnptr{CONSTRUCTORS}" );@]@=} -"FORCE_COMMON_ALLOCATION" {@> @[TeX_( "/yylexreturnptr{FORCE_COMMON_ALLOCATION}" );@]@=} -"INHIBIT_COMMON_ALLOCATION" {@> @[TeX_( "/yylexreturnptr{INHIBIT_COMMON_ALLOCATION}" );@]@=} -"SECTIONS" {@> @[TeX_( "/yylexreturnptr{SECTIONS}" );@]@=} -"INSERT" {@> @[TeX_( "/yylexreturnptr{INSERT_K}" );@]@=} -"AFTER" {@> @[TeX_( "/yylexreturnptr{AFTER}" );@]@=} -"BEFORE" {@> @[TeX_( "/yylexreturnptr{BEFORE}" );@]@=} -"FILL" {@> @[TeX_( "/yylexreturnptr{FILL}" );@]@=} -"STARTUP" {@> @[TeX_( "/yylexreturnptr{STARTUP}" );@]@=} -"OUTPUT_FORMAT" {@> @[TeX_( "/yylexreturnptr{OUTPUT_FORMAT}" );@]@=} -"OUTPUT_ARCH" {@> @[TeX_( "/yylexreturnptr{OUTPUT_ARCH}" );@]@=} -"HLL" {@> @[TeX_( "/yylexreturnptr{HLL}" );@]@=} -"SYSLIB" {@> @[TeX_( "/yylexreturnptr{SYSLIB}" );@]@=} -"FLOAT" {@> @[TeX_( "/yylexreturnptr{FLOAT}" );@]@=} -"QUAD" {@> @[TeX_( "/yylexreturnptr{QUAD}" );@]@=} -"SQUAD" {@> @[TeX_( "/yylexreturnptr{SQUAD}" );@]@=} -"LONG" {@> @[TeX_( "/yylexreturnptr{LONG}" );@]@=} -"SHORT" {@> @[TeX_( "/yylexreturnptr{SHORT}" );@]@=} -"BYTE" {@> @[TeX_( "/yylexreturnptr{BYTE}" );@]@=} -"NOFLOAT" {@> @[TeX_( "/yylexreturnptr{NOFLOAT}" );@]@=} -"NOCROSSREFS" {@> @[TeX_( "/yylexreturnptr{NOCROSSREFS}" );@]@=} -"OVERLAY" {@> @[TeX_( "/yylexreturnptr{OVERLAY}" );@]@=} -"SORT_BY_NAME" {@> @[TeX_( "/yylexreturnptr{SORT_BY_NAME}" );@]@=} -"SORT_BY_ALIGNMENT" {@> @[TeX_( "/yylexreturnptr{SORT_BY_ALIGNMENT}" );@]@=} -"SORT" {@> @[TeX_( "/yylexreturnptr{SORT_BY_NAME}" );@]@=} -"SORT_BY_INIT_PRIORITY" {@> @[TeX_( "/yylexreturnptr{SORT_BY_INIT_PRIORITY}" );@]@=} -"SORT_NONE" {@> @[TeX_( "/yylexreturnptr{SORT_NONE}" );@]@=} -"NOLOAD" {@> @[TeX_( "/yylexreturnptr{NOLOAD}" );@]@=} -"DSECT" {@> @[TeX_( "/yylexreturnptr{DSECT}" );@]@=} -"COPY" {@> @[TeX_( "/yylexreturnptr{COPY}" );@]@=} -"INFO" {@> @[TeX_( "/yylexreturnptr{INFO}" );@]@=} -"OVERLAY" {@> @[TeX_( "/yylexreturnptr{OVERLAY}" );@]@=} -"ONLY_IF_RO" {@> @[TeX_( "/yylexreturnptr{ONLY_IF_RO}" );@]@=} -"ONLY_IF_RW" {@> @[TeX_( "/yylexreturnptr{ONLY_IF_RW}" );@]@=} -"SPECIAL" {@> @[TeX_( "/yylexreturnptr{SPECIAL}" );@]@=} -"o" {@> @[TeX_( "/yylexreturnptr{ORIGIN}" );@]@=} -"org" {@> @[TeX_( "/yylexreturnptr{ORIGIN}" );@]@=} -"l" {@> @[TeX_( "/yylexreturnptr{LENGTH}" );@]@=} -"len" {@> @[TeX_( "/yylexreturnptr{LENGTH}" );@]@=} -"INPUT_SECTION_FLAGS" {@> @[TeX_( "/yylexreturnptr{INPUT_SECTION_FLAGS}" );@]@=} -"INCLUDE" {@> @[TeX_( "/yylexreturnptr{INCLUDE}" );@]@=} -"PHDRS" {@> @[TeX_( "/yylexreturnptr{PHDRS}" );@]@=} -"AT" {@> @[TeX_( "/yylexreturnptr{AT}" );@]@=} -"ALIGN_WITH_INPUT" {@> @[TeX_( "/yylexreturnptr{ALIGN_WITH_INPUT}" );@]@=} -"SUBALIGN" {@> @[TeX_( "/yylexreturnptr{SUBALIGN}" );@]@=} -"HIDDEN" {@> @[TeX_( "/yylexreturnptr{HIDDEN}" );@]@=} -"PROVIDE" {@> @[TeX_( "/yylexreturnptr{PROVIDE}" );@]@=} -"PROVIDE_HIDDEN" {@> @[TeX_( "/yylexreturnptr{PROVIDE_HIDDEN}" );@]@=} -"KEEP" {@> @[TeX_( "/yylexreturnptr{KEEP}" );@]@=} -"EXCLUDE_FILE" {@> @[TeX_( "/yylexreturnptr{EXCLUDE_FILE}" );@]@=} -"CONSTANT" {@> @[TeX_( "/yylexreturnptr{CONSTANT}" );@]@=} -"#".*\n? {@> @[TeX_( "/yylexnext" );@]@=} -"\n" {@> @[TeX_( "/yylexreturnptr{NEWLINE}" );@]@=} -"*".* {@> @[TeX_( "/yylexnext" );@]@=} -";".* {@> @[TeX_( "/yylexnext" );@]@=} -"END" {@> @[TeX_( "/yylexreturnptr{ENDWORD}" );@]@=} -"ALIGNMOD" {@> @[TeX_( "/yylexreturnptr{ALIGNMOD}" );@]@=} -"ALIGN" {@> @[TeX_( "/yylexreturnptr{ALIGN_K}" );@]@=} -"CHIP" {@> @[TeX_( "/yylexreturnptr{CHIP}" );@]@=} -"BASE" {@> @[TeX_( "/yylexreturnptr{BASE}" );@]@=} -"ALIAS" {@> @[TeX_( "/yylexreturnptr{ALIAS}" );@]@=} -"TRUNCATE" {@> @[TeX_( "/yylexreturnptr{TRUNCATE}" );@]@=} -"LOAD" {@> @[TeX_( "/yylexreturnptr{LOAD}" );@]@=} -"PUBLIC" {@> @[TeX_( "/yylexreturnptr{PUBLIC}" );@]@=} -"ORDER" {@> @[TeX_( "/yylexreturnptr{ORDER}" );@]@=} -"NAME" {@> @[TeX_( "/yylexreturnptr{NAMEWORD}" );@]@=} -"FORMAT" {@> @[TeX_( "/yylexreturnptr{FORMAT}" );@]@=} -"CASE" {@> @[TeX_( "/yylexreturnptr{CASE}" );@]@=} -"START" {@> @[TeX_( "/yylexreturnptr{START}" );@]@=} -"LIST".* {@> @[TeX_( "/yylexreturnptr{LIST}" );@]@=} -"SECT" {@> @[TeX_( "/yylexreturnptr{SECT}" );@]@=} -"ABSOLUTE" {@> @[TeX_( "/yylexreturnptr{ABSOLUTE}" );@]@=} -"end" {@> @[TeX_( "/yylexreturnptr{ENDWORD}" );@]@=} -"alignmod" {@> @[TeX_( "/yylexreturnptr{ALIGNMOD}" );@]@=} -"align" {@> @[TeX_( "/yylexreturnptr{ALIGN_K}" );@]@=} -"chip" {@> @[TeX_( "/yylexreturnptr{CHIP}" );@]@=} -"base" {@> @[TeX_( "/yylexreturnptr{BASE}" );@]@=} -"alias" {@> @[TeX_( "/yylexreturnptr{ALIAS}" );@]@=} -"truncate" {@> @[TeX_( "/yylexreturnptr{TRUNCATE}" );@]@=} -"load" {@> @[TeX_( "/yylexreturnptr{LOAD}" );@]@=} -"public" {@> @[TeX_( "/yylexreturnptr{PUBLIC}" );@]@=} -"order" {@> @[TeX_( "/yylexreturnptr{ORDER}" );@]@=} -"name" {@> @[TeX_( "/yylexreturnptr{NAMEWORD}" );@]@=} -"format" {@> @[TeX_( "/yylexreturnptr{FORMAT}" );@]@=} -"case" {@> @[TeX_( "/yylexreturnptr{CASE}" );@]@=} -"extern" {@> @[TeX_( "/yylexreturnptr{EXTERN}" );@]@=} -"start" {@> @[TeX_( "/yylexreturnptr{START}" );@]@=} -"list".* {@> @[TeX_( "/yylexreturnptr{LIST}" );@]@=} -"sect" {@> @[TeX_( "/yylexreturnptr{SECT}" );@]@=} -"absolute" {@> @[TeX_( "/yylexreturnptr{ABSOLUTE}" );@]@=} -{FILENAMECHAR1}{NOCFILENAMECHAR}* {@> @[TeX_( "/yylexreturnsym{NAME}" );@]@=} -{FILENAMECHAR1}{FILENAMECHAR}* {@> @[TeX_( "/yylexreturnsym{NAME}" );@]@=} -"-l"{FILENAMECHAR}+ {@> @[TeX_( "/yylexreturnsym{NAME}" );@]@=} -{FILENAMECHAR1}{NOCFILENAMECHAR}* {@> @[TeX_( "/yylexreturnsym{NAME}" );@]@=} -"-l"{NOCFILENAMECHAR}+ {@> @[TeX_( "/yylexreturnsym{NAME}" );@]@=} +{ + "MEMORY" {@> @[TeX_( "/yylexreturnptr{MEMORY}" );@]@=} + "REGION_ALIAS" {@> @[TeX_( "/yylexreturnptr{REGION_ALIAS}" );@]@=} + "LD_FEATURE" {@> @[TeX_( "/yylexreturnptr{LD_FEATURE}" );@]@=} + "VERSION" {@> @[TeX_( "/yylexreturnptr{VERSIONK}" );@]@=} + "TARGET" {@> @[TeX_( "/yylexreturnptr{TARGET_K}" );@]@=} + "SEARCH_DIR" {@> @[TeX_( "/yylexreturnptr{SEARCH_DIR}" );@]@=} + "OUTPUT" {@> @[TeX_( "/yylexreturnptr{OUTPUT}" );@]@=} + "INPUT" {@> @[TeX_( "/yylexreturnptr{INPUT}" );@]@=} + "ENTRY" {@> @[TeX_( "/yylexreturnptr{ENTRY}" );@]@=} + "MAP" {@> @[TeX_( "/yylexreturnptr{MAP}" );@]@=} + "CREATE_OBJECT_SYMBOLS" {@> @[TeX_( "/yylexreturnptr{CREATE_OBJECT_SYMBOLS}" );@]@=} + "CONSTRUCTORS" {@> @[TeX_( "/yylexreturnptr{CONSTRUCTORS}" );@]@=} + "FORCE_COMMON_ALLOCATION" {@> @[TeX_( "/yylexreturnptr{FORCE_COMMON_ALLOCATION}" );@]@=} + "INHIBIT_COMMON_ALLOCATION" {@> @[TeX_( "/yylexreturnptr{INHIBIT_COMMON_ALLOCATION}" );@]@=} + "SECTIONS" {@> @[TeX_( "/yylexreturnptr{SECTIONS}" );@]@=} + "INSERT" {@> @[TeX_( "/yylexreturnptr{INSERT_K}" );@]@=} + "AFTER" {@> @[TeX_( "/yylexreturnptr{AFTER}" );@]@=} + "BEFORE" {@> @[TeX_( "/yylexreturnptr{BEFORE}" );@]@=} + "FILL" {@> @[TeX_( "/yylexreturnptr{FILL}" );@]@=} + "STARTUP" {@> @[TeX_( "/yylexreturnptr{STARTUP}" );@]@=} + "OUTPUT_FORMAT" {@> @[TeX_( "/yylexreturnptr{OUTPUT_FORMAT}" );@]@=} + "OUTPUT_ARCH" {@> @[TeX_( "/yylexreturnptr{OUTPUT_ARCH}" );@]@=} + "HLL" {@> @[TeX_( "/yylexreturnptr{HLL}" );@]@=} + "SYSLIB" {@> @[TeX_( "/yylexreturnptr{SYSLIB}" );@]@=} + "FLOAT" {@> @[TeX_( "/yylexreturnptr{FLOAT}" );@]@=} + "QUAD" {@> @[TeX_( "/yylexreturnptr{QUAD}" );@]@=} + "SQUAD" {@> @[TeX_( "/yylexreturnptr{SQUAD}" );@]@=} + "LONG" {@> @[TeX_( "/yylexreturnptr{LONG}" );@]@=} + "SHORT" {@> @[TeX_( "/yylexreturnptr{SHORT}" );@]@=} + "BYTE" {@> @[TeX_( "/yylexreturnptr{BYTE}" );@]@=} + "NOFLOAT" {@> @[TeX_( "/yylexreturnptr{NOFLOAT}" );@]@=} + "OVERLAY" {@> @[TeX_( "/yylexreturnptr{OVERLAY}" );@]@=} + "SORT_BY_NAME" {@> @[TeX_( "/yylexreturnptr{SORT_BY_NAME}" );@]@=} + "SORT_BY_ALIGNMENT" {@> @[TeX_( "/yylexreturnptr{SORT_BY_ALIGNMENT}" );@]@=} + "SORT" {@> @[TeX_( "/yylexreturnptr{SORT_BY_NAME}" );@]@=} + "SORT_BY_INIT_PRIORITY" {@> @[TeX_( "/yylexreturnptr{SORT_BY_INIT_PRIORITY}" );@]@=} + "SORT_NONE" {@> @[TeX_( "/yylexreturnptr{SORT_NONE}" );@]@=} + "EXTERN" {@> @[TeX_( "/yylexreturnptr{EXTERN}" );@]@=} + "o"|"org" {@> @[TeX_( "/yylexreturnptr{ORIGIN}" );@]@=} + "l"|"len" {@> @[TeX_( "/yylexreturnptr{LENGTH}" );@]@=} + "PHDRS" {@> @[TeX_( "/yylexreturnptr{PHDRS}" );@]@=} +} + +{ + "BLOCK" {@> @[TeX_( "/yylexreturnptr{BLOCK}" );@]@=} + "BIND" {@> @[TeX_( "/yylexreturnptr{BIND}" );@]@=} + "LENGTH" {@> @[TeX_( "/yylexreturnptr{LENGTH}" );@]@=} + "ORIGIN" {@> @[TeX_( "/yylexreturnptr{ORIGIN}" );@]@=} + "ALIGN" {@> @[TeX_( "/yylexreturnptr{ALIGN_K}" );@]@=} + "DATA_SEGMENT_ALIGN" {@> @[TeX_( "/yylexreturnptr{DATA_SEGMENT_ALIGN}" );@]@=} + "DATA_SEGMENT_RELRO_END" {@> @[TeX_( "/yylexreturnptr{DATA_SEGMENT_RELRO_END}" );@]@=} + "DATA_SEGMENT_END" {@> @[TeX_( "/yylexreturnptr{DATA_SEGMENT_END}" );@]@=} + "ADDR" {@> @[TeX_( "/yylexreturnptr{ADDR}" );@]@=} + "LOADADDR" {@> @[TeX_( "/yylexreturnptr{LOADADDR}" );@]@=} + "ALIGNOF" {@> @[TeX_( "/yylexreturnptr{ALIGNOF}" );@]@=} + "ASSERT" {@> @[TeX_( "/yylexreturnptr{ASSERT_K}" );@]@=} + "NEXT" {@> @[TeX_( "/yylexreturnptr{NEXT}" );@]@=} + "sizeof_headers" {@> @[TeX_( "/yylexreturnptr{SIZEOF_HEADERS}" );@]@=} + "SIZEOF_HEADERS" {@> @[TeX_( "/yylexreturnptr{SIZEOF_HEADERS}" );@]@=} + "SEGMENT_START" {@> @[TeX_( "/yylexreturnptr{SEGMENT_START}" );@]@=} + "SIZEOF" {@> @[TeX_( "/yylexreturnptr{SIZEOF}" );@]@=} + "GROUP" {@> @[TeX_( "/yylexreturnptr{GROUP}" );@]@=} + "AS_NEEDED" {@> @[TeX_( "/yylexreturnptr{AS_NEEDED}" );@]@=} + "DEFINED" {@> @[TeX_( "/yylexreturnptr{DEFINED}" );@]@=} + "NOCROSSREFS" {@> @[TeX_( "/yylexreturnptr{NOCROSSREFS}" );@]@=} + "NOLOAD" {@> @[TeX_( "/yylexreturnptr{NOLOAD}" );@]@=} + "DSECT" {@> @[TeX_( "/yylexreturnptr{DSECT}" );@]@=} + "COPY" {@> @[TeX_( "/yylexreturnptr{COPY}" );@]@=} + "INFO" {@> @[TeX_( "/yylexreturnptr{INFO}" );@]@=} + "OVERLAY" {@> @[TeX_( "/yylexreturnptr{OVERLAY}" );@]@=} + "ONLY_IF_RO" {@> @[TeX_( "/yylexreturnptr{ONLY_IF_RO}" );@]@=} + "ONLY_IF_RW" {@> @[TeX_( "/yylexreturnptr{ONLY_IF_RW}" );@]@=} + "SPECIAL" {@> @[TeX_( "/yylexreturnptr{SPECIAL}" );@]@=} + "INPUT_SECTION_FLAGS" {@> @[TeX_( "/yylexreturnptr{INPUT_SECTION_FLAGS}" );@]@=} + "INCLUDE" {@> @[TeX_( "/yylexreturnptr{INCLUDE}" );@]@=} + "AT" {@> @[TeX_( "/yylexreturnptr{AT}" );@]@=} + "ALIGN_WITH_INPUT" {@> @[TeX_( "/yylexreturnptr{ALIGN_WITH_INPUT}" );@]@=} + "SUBALIGN" {@> @[TeX_( "/yylexreturnptr{SUBALIGN}" );@]@=} + "HIDDEN" {@> @[TeX_( "/yylexreturnptr{HIDDEN}" );@]@=} + "PROVIDE" {@> @[TeX_( "/yylexreturnptr{PROVIDE}" );@]@=} + "PROVIDE_HIDDEN" {@> @[TeX_( "/yylexreturnptr{PROVIDE_HIDDEN}" );@]@=} + "KEEP" {@> @[TeX_( "/yylexreturnptr{KEEP}" );@]@=} + "EXCLUDE_FILE" {@> @[TeX_( "/yylexreturnptr{EXCLUDE_FILE}" );@]@=} + "CONSTANT" {@> @[TeX_( "/yylexreturnptr{CONSTANT}" );@]@=} + "\n" {@> @[TeX_( "/yylexnext" );@]@=} +} + +{ + "MAX" {@> @[TeX_( "/yylexreturnptr{MAX_K}" );@]@=} + "MIN" {@> @[TeX_( "/yylexreturnptr{MIN_K}" );@]@=} + "LOG2CEIL" {@> @[TeX_( "/yylexreturnptr{LOG2CEIL}" );@]@=} +} + +{ + "ABSOLUTE"|"absolute" {@> @[TeX_( "/yylexreturnptr{ABSOLUTE}" );@]@=} + [ \t\r]+ {@> @[TeX_( "/yylexnext" );@]@=} +} + +{ + {FILENAMECHAR1}{FILENAMECHAR}* {@> @[TeX_( "/yylexreturnsym{NAME}" );@]@=} + "-l"{FILENAMECHAR}+ {@> @[TeX_( "/yylexreturnsym{NAME}" );@]@=} +} + +{ + {FILENAMECHAR1}{NOCFILENAMECHAR}* {@> @[TeX_( "/yylexreturnsym{NAME}" );@]@=} + "-l"{NOCFILENAMECHAR}+ {@> @[TeX_( "/yylexreturnsym{NAME}" );@]@=} +} +