~ubuntu-branches/ubuntu/raring/latexmk/raring-proposed : revision 1

1

2

3

4

LATEXMK(1L) LATEXMK(1L)

5

6

7

NAME

8

latexmk - generate LaTeX document

9

10

SYNOPSIS

11

latexmk [options] [file ...]

12

13

DESCRIPTION

14

LatexMk completely automates the process of compiling a

15

LaTeX document. Essentially, it is a highly specialized

16

relative of the general make utility. Given the source

17

files for a document, latexmk issues the appropriate

18

sequence of commands to generate a .dvi, .ps, .pdf and/or

19

hardcopy version of the document. It can also be set to

20

run continuously with a previewer; in that case the latex

21

program, etc, are rerun whenever one of the source files

22

is modified.

23

24

Latexmk will normally determine which are the source files

25

by examining the log file. It has an option to parse the

26

TeX file instead --- see later. When latexmk is run, it

27

will examine the timestamps on the source files. If any

28

of the source files have been changed since the last docu-

29

ment generation, latexmk will run the various LaTeX pro-

30

cessing programs as necessary. In particular, it will

31

repeat the run of LaTeX (or pdflatex) often enough to

32

resolve all cross references; depending on the macro pack-

33

ages used. With some macro packages and document styles

34

four, or even more, runs may be needed. If necessary,

35

latexmk will also run bibtex and/or makeindex.

36

37

[If the option -it to scan the LaTeX file is used, the

38

main LaTeX file and all input and included files (recur-

39

sively) are scanned for LaTeX commands for inputting and

40

including other TeX files and figure files. Then on sub-

41

sequent runs, latexmk with the -it switch reads the depen-

42

dency information from this file. If the dependencies of

43

the document are changed (e.g., by adding or removing an

44

\input command), an additional pass of latexmk -i or

45

latexmk -I will update the dependency file.]

46

47

Latexmk has two different previewing options. In the sim-

48

ple -pv option, a dvi, postscript or pdf previewer is

49

automatically run after generating the dvi, postscript or

50

pdf version of the document. The type of viewer is

51

selected automatically depending on the -ps, -pdf or

52

-pdfps options. The kind of file to be viewed can also

53

be explicitly selected by using the -view option

54

(-view=ps, etc).

55

56

The second previewing option is the powerful -pvc option

57

(mnemonic: "preview continuously"). Particularly when a

58

document is reaching the final stages of editing, it is

59

often useful to have a previewer open continuously and

60

have it update its display whenever changes are made to

61

62

63

64

16 May 2004 1

65

66

67

68

69

70

LATEXMK(1L) LATEXMK(1L)

71

72

73

the source file(s), and this is done by the -pvc option.

74

With this option, latexmk runs a previewer for the docu-

75

ment, and then latexmk repeatedly monitors the source

76

files of the document to see if any changes have been made

77

since the last dependent file was produced. When changes

78

are detected, latexmk runs the appropriate LaTeX commands

79

to regenerate the .dvi, .ps and/or .pdf files (depending

80

on the which of the -ps, -pdf and -pdfps options was

81

specified). A good previewer (like gv) will then automat-

82

ically update its display. Thus the user can simply edit

83

a file and, when the changes are written to disk, latexmk

84

completely automates the cycle of updating the .dvi (and

85

possibly the .ps and .pdf) file, and refreshing the pre-

86

viewer's display. It's not quite WYSIWYG, but usefully

87

close.

88

89

For other previewers, the user will have to manually make

90

the previewer update its display, which can be (xdvi and

91

gsview) as forcing a redraw of its display.

92

93

Latexmk has the ability to print a banner in gray diago-

94

nally across each page when making the postscript file.

95

It can also, if needed, call an external program to do

96

other postprocessing on the generated files.

97

98

Latexmk is highly configurable, both from the command line

99

and in configuration files, so that it can accommodate a

100

wide variety of user needs and system configurations.

101

102

LATEXMK OPTIONS AND ARGUMENTS

103

(All options can be introduced by single or double "-"

104

characters, e.g., "latexmk -help" or "latexmk --help".)

105

106

file One or more files can be specified. If no files

107

are specified, latexmk will, by default, run on all

108

files in the current working directory with a

109

".tex" extension. This behavior can be changed:

110

see the sections concerning the @default_files

111

variables.

112

113

If a file is specified without an extension, then

114

the ".tex" extension is automatically added, just

115

as LaTeX does. (e.g. If you specify:

116

117

latexmk foo

118

119

then latexmk will operate on the file "foo.tex".

120

121

-bm <message>

122

A banner message to print diagonally across each

123

page when converting the dvi file to postscript.

124

The message must be a single argument on the com-

125

mand line so be careful with quoting spaces and

126

such.

127

128

129

130

16 May 2004 2

131

132

133

134

135

136

LATEXMK(1L) LATEXMK(1L)

137

138

139

Note that if the -bm option is specified, the -ps

140

option is assumed and the postscript file is always

141

generated, even if it is newer than the dvi file.

142

143

-bi <intensity>

144

How dark to print the banner message. A decimal

145

number between 0 and 1. 0 is black and 1 is white,

146

default is 0.95 which is OK unless your toner car-

147

tridge is getting low.

148

149

-bs <scale>

150

A decimal number that specifies how large the ban-

151

ner message will be printed. Experimentation is

152

necessary to get the right scale for your message,

153

as a rule of thumb the scale should be about equal

154

to 1100 divided by the number of characters in the

155

message. Default is 220.0 which is just right for

156

5 character messages.

157

158

-commands

159

List the commands used by latexmk for processing

160

files, and then exit.

161

162

-c Clean up (remove) all regenerateable files gener-

163

ated by latex and bibtex except dvi, postscript and

164

pdf.

165

166

-C Clean up (remove) all regenerateable files gener-

167

ated by latex and bibtex including aux, dep, dvi,

168

postscript and pdf.

169

170

-c1 Clean up (remove) all regenerateable files gener-

171

ated by latex and bibtex except aux and dep.

172

173

-d Set draft mode. This prints the banner message

174

"DRAFT" across your page when converting the dvi

175

file to postscript. Size and intensity can be mod-

176

ified with the -bs and -bi options. The -bm option

177

will override this option as this is really just a

178

short way of specifying:

179

180

latexmk -bm DRAFT

181

182

Note that if the -d option is specified, the -ps

183

option is assumed and the postscript file is always

184

generated, even if it is newer than the dvi file.

185

186

-dF Dvi file filtering. The argument to this option is

187

a filter which will generate a filtered dvi file

188

with the extension ".dviF". All extra processing

189

(e.g. conversion to postscript, preview, printing)

190

will then be performed on this filtered dvi file.

191

192

Example usage: To use dviselect to select only the

193

194

195

196

16 May 2004 3

197

198

199

200

201

202

LATEXMK(1L) LATEXMK(1L)

203

204

205

even pages of the dvi file:

206

207

latexmk -dF 'dviselect even' foo.tex

208

209

-dvi Generate dvi version of document.

210

211

-dvi- Turn off generation of dvi version of document.

212

(This may get overridden, if some other file is

213

made (a .ps file) that is generated from the dvi

214

file, or if no generated file at all is requested.)

215

216

-diagnostics

217

Whenever a log file is parsed to determine the

218

input and included files, print a list of these

219

files.

220

221

-f Force latexmk to continue document processing

222

despite errors. Normally, when latexmk detects

223

that latex has found an error which will not be

224

resolved by further processing, the program termi-

225

nates.

226

227

-f- Turn off the forced processing-past-errors such as

228

is set by the -f option. This could be used to

229

override a setting in a configuration file.

230

231

-F Force latexmk to include files that don't exist

232

when generating dependency files. A warning is

233

produced instead of an error message and the pro-

234

gram terminating. If the file name is not an abso-

235

lute path, it is assumed to be relative to the cur-

236

rent working directory. (Note: This option is only

237

relevant if you are using the -it to obtain the

238

dependency information from the tex files. The

239

default is to obtain this information from the log

240

file and it that case the -F option has no effect.)

241

242

-F- Turn off -F.

243

244

-g Force latexmk to process document, disregarding the

245

timestamps of the source files. This option is

246

useful, for example, if you change some options and

247

wish to reprocess the files.

248

249

-g- Turn off -g.

250

251

-h, -help

252

Print help information.

253

254

-i Generate new dependency file if root file is newer

255

than dependency file or dependency file does not

256

exist. The dependency information is taken from

257

the log file or the source file, depending on the

258

setting made by the -il and -it switches.

259

260

261

262

16 May 2004 4

263

264

265

266

267

268

LATEXMK(1L) LATEXMK(1L)

269

270

271

-i- Turn off -i.

272

273

-il Extract dependency information from log file. This

274

is normally the best method, so it is the default.

275

However, some packages do not put information on

276

files read in the log file, and then it may be bet-

277

ter to tell latexmk to get the information from the

278

TeX file(s) --- see the switch -it. (Default)

279

280

-it Extract dependency information by scanning the

281

source TeX file(s), rather than the log file. This

282

is the method used by earlier versions of latexmk.

283

It relies on parsing TeX files, which can be con-

284

fused by definitions of new commands, etc. Nor-

285

mally it is better to tell latexmk to scan the log

286

file --- see the switch -il.

287

288

-I Always generate new dependency file, even if newer

289

dependency file exists. The dependency information

290

is taken from the log file or the source file,

291

depending on the setting made by the -il and -it

292

switches.

293

294

-I- Turn off -I.

295

296

-l Run in landscape mode, using the landscape mode for

297

the previewers and the dvi to postscript convert-

298

ers.

299

300

-l- Turn off -l.

301

302

-p Print out the file. By default, this is done using

303

lpr after generating the postscript version. But

304

you can use the -print=... option to print the dvi

305

or pdf files instead, and you can configure this in

306

a start up file (by setting the $print_type vari-

307

able.

308

309

Under MS-Windows you must have configured the print

310

commands used by latexmk.

311

312

This option is incompatible with the -pv and -pvc

313

options, so it turns them off.

314

315

-pdf Generate pdf version of document using pdflatex.

316

317

-pdfdvi

318

Generate pdf version of document from the dvi file,

319

by default using dvipdf.

320

321

-pdfps Generate pdf version of document from the ps file,

322

by default using ps2pdf.

323

324

-pdf- Turn off generation of pdf version of document.

325

326

327

328

16 May 2004 5

329

330

331

332

333

334

LATEXMK(1L) LATEXMK(1L)

335

336

337

(This can be used to override a setting in a con-

338

figuration file. It may get overridden if some

339

other option requires the generation of a pdf

340

file.)

341

342

-print=dvi, -print=ps, -print=pdf

343

Define which kind of file is printed. This option

344

also ensures that the requisite file is made, and

345

turns on printing.

346

347

-ps Generate postscript version of document.

348

349

-ps- Turn off generation of postscript version of docu-

350

ment. This can be used to override a setting in a

351

configuration file. (It may get overridden by some

352

other option that requires a postscript file, for

353

example a request for printing.)

354

355

-pF Postscript file filtering. The argument to this

356

option is a filter which will generate a filtered

357

postscript file with the extension ".psF". All

358

extra processing (e.g. preview, printing) will then

359

be performed on this filtered postscript file.

360

361

Example usage: Use psnup to print two pages on the

362

one page:

363

364

latexmk -ps -pF 'psnup -2' foo.tex

365

366

or

367

368

latexmk -ps -pF "psnup -2" foo.tex

369

370

Whether to use single or double quotes round the

371

"psnup -2" will depend on your command interpreter,

372

in particular on the operating system.

373

374

-pv Run file previewer. If the -view option is used,

375

this will select the kind of file to be previewed

376

(dvi, ps or pdf). Otherwise the viewer views the

377

"highest" kind of file selected, by the -dvi, -ps,

378

-pdf, -pdfps options, in the order dvi, ps, pdf

379

(low to high). If no file type has been selected,

380

the dvi previewer will be used. This option is

381

incompatible with the -p and -pvc options, so it

382

turns them off.

383

384

-pv- Turn off -pv.

385

386

-pvc Run a file previewer and continually update the

387

.dvi, .ps, and/or .pdf files whenever changes are

388

made to source files (see the Description above).

389

Which of these files is generated and which is

390

viewed is governed by the other options, and is the

391

392

393

394

16 May 2004 6

395

396

397

398

399

400

LATEXMK(1L) LATEXMK(1L)

401

402

403

same as for the -pv option. This option also turns

404

on the -f option, since it is normally desirable in

405

preview-continuous-mode to continue working even if

406

errors are found. The preview-continuous option

407

-pvc can only work with one file. So in this case

408

you will normally only specify one filename on the

409

command line. It is also incompatible with the -p

410

and -pv options, so it turns these options off

411

412

With a good previewer the display will be automati-

413

cally updated. (Under UNIX "gv -watch" does this

414

for postscript files; it would also do it for pdf

415

files except for an apparent bug in gv that causes

416

an error when the newly updated pdf file is read.)

417

Other previewers will need a manual update.

418

419

Important note: the acroread program on MS-Windows

420

locks the pdf file, and prevents new versions being

421

written, so it is a bad idea to use acroread to

422

view pdf files in preview-continuous mode. It is

423

better to use a dvi or ps viewer, as set by one of

424

the -view=dvi and -view=ps options.

425

426

Note that if latexmk dies because it encounters an

427

error, the "forked" previewer will continue to run.

428

Successive invocations with the -pvc option will

429

not fork new previewers, but latexmk will use the

430

existing previewer. (At least this will happen

431

when latexmk is running under an operating system

432

where it knows how to determine whether an existing

433

previewer is running.)

434

435

-pvc- Turn off -pvc.

436

437

-quiet Same as -silent

438

439

-r <rcfile>

440

Read the specified initialization file ("RC file")

441

before processing. Be careful about the ordering:

442

Standard initialization files --- see the section

443

below on "Initialization (RC) files" --- are read

444

first, then the options on the command line in the

445

order they are given. Thus an initialization file

446

specified with the -r option can override both the

447

standard initialization files and previously speci-

448

fied options. But all of these can be overridden

449

by later options. See below for more details about

450

initialization (RC) files.

451

452

-silent

453

Run commands silently, i.e., with options that

454

reduce the amount of diagnostics generated. For

455

example, with the default settings for commands

456

under UNIX, the command "latex

457

458

459

460

16 May 2004 7

461

462

463

464

465

466

LATEXMK(1L) LATEXMK(1L)

467

468

469

-interaction=batchmode" is used for latex.

470

471

Also reduce the number of informational messages

472

that latexmk generates.

473

474

-v, -version

475

Print version number of Latexmk.

476

477

-verbose

478

Opposite of -silent. This is the default setting.

479

480

-view=default, -view=dvi, -view=ps, -view=pdf

481

Set the kind of file used when previewing is

482

requested (e.g., by the -pv or -pvc switches). The

483

default is to view the "highest" kind of requested

484

file (in the order dvi, ps, pdf).

485

486

The preview-continuous option -pvc can only work with one

487

file. So in this case you will normally only specify one

488

filename on the command line.

489

490

Options -p, -pv and -pvc are mutually exclusive. So each

491

of these options turns the others off.

492

493

EXAMPLES

494

% latexmk thesis # run latex enough times to resolve

495

cross-references

496

497

% latexmk -pvc -ps thesis# run latex enough times to resolve

498

cross-references, make a postscript

499

file, start a previewer. Then

500

watch for changes in the source

501

file thesis.tex and any files it

502

uses. After any changes rerun latex

503

the appropriate number of times and

504

remake the postscript file. If latex

505

encounters an error, latexmk will

506

keep running.

507

508

% latexmk -c # remove .aux, .log, .bbl, .blg, .dep,

509

.dvi, .pdf, .ps & .bbl files

510

511

INITIALIZATION (RC) FILES

512

There are four initialization files ("RC files") that

513

latexmk can read at startup:

514

515

1) The system RC file, if it exists.

516

On a UNIX system, latexmk searches for following places

517

for its

518

system RC file, in the following order, and reads the

519

first it finds:

520

"/opt/local/share/latexmk/LatexMk",

521

"/usr/local/share/latexmk/LatexMk",

522

"/usr/local/lib/latexmk/LatexMk".

523

524

525

526

16 May 2004 8

527

528

529

530

531

532

LATEXMK(1L) LATEXMK(1L)

533

534

535

On a MS-WINDOWS system it looks for

536

"C:\latexmk\LatexMk".

537

538

2) The user's RC file in "$HOME/.latexmkrc", where $HOME

539

is the value of the environment variable HOME. On UNIX

540

and clones (including LINUX), this variable is set by the

541

system; on MS-Windows, the user may choose to set it.

542

543

3) The RC file in the current working directory called

544

"latexmkrc".

545

546

4) Any RC file(s) specified on the command line with the

547

-r option.

548

549

Each RC file is a sequence of Perl commands. Usually it

550

will be just a sequence of assignment statements that

551

override the built-in settings of Latexmk. Comment lines

552

are introduced by the "#" character.

553

554

Note that command line options are obeyed in the order in

555

which they are written; thus any RC file specified on the

556

command line with the -r option can override previous

557

options but can be itself overridden by later options on

558

the command line.

559

560

561

RC VARIABLES IN INITIALIZATION FILES

562

Many of the available variables that can be set are shown

563

in the next section. Syntax for the statements in an ini-

564

tialization file is of the form:

565

566

$bibtex = 'bibtex';

567

568

for the setting of a string variable,

569

570

$preview_mode = 1;

571

572

for the setting of a numeric variable, and

573

574

@default_files = ('paper', 'paper1');

575

576

for the setting of an array of strings.

577

578

Some of the variables set the names of the commands that

579

latexmk uses. Here are some tricks to note for these:

580

581

"Detaching" a command: If a command is to be run detached

582

this is indicated by preceding it with "start", as in

583

584

$dvi_previewer = 'start xdvi';

585

586

This will be translated to whatever is appropriate for

587

your operating system. (Note: in some circumstances, latex

588

will always run a command detached. This is the case for

589

590

591

592

16 May 2004 9

593

594

595

596

597

598

LATEXMK(1L) LATEXMK(1L)

599

600

601

a previewer in preview continuous mode, since otherwise

602

previewing continuously makes no sense.)

603

604

Command names containing spaces: Under MS-Windows it is

605

common that the name of a command includes spaces, since

606

software is often installed in a subdirectory of "C:Pro-

607

gram Files". Such command names should be enclosed in

608

double quotes, as in

609

610

$lpr_pdf = '"c:/Program Files/Ghost-

611

gum/gsview/gsview32.exe" /p';

612

613

Using MS-Windows file associations: A useful trick under

614

modern versions of MS-Windows (e.g., WinXP) is to use just

615

the command

616

617

$dvi_previewer = 'start';

618

619

Under recent versions of MS-Windows, this will cause to be

620

run whatever program the system has associated with dvi

621

files. (The same applies for a postscript viewer and a

622

pdf viewer.)

623

624

Not using a certain command: If a command is not to be

625

run, the command name NONE is used, as in

626

627

$lpr = 'NONE lpr';

628

629

630

Options to commands: Setting the name of a command can be

631

used not only for changing the name of the command called,

632

but also to add options to command. Suppose you want

633

latexmk to use latex with source specials enabled. Then

634

you might use the following line in an initialization

635

file:

636

637

$latex = 'latex --src-specials';

638

639

640

Advanced tricks: Normally latexmk assumes certain behavior

641

for commands and in particular it assumes certain kinds

642

and ordering of command line arguments. Sometimes this

643

assumption is wrong. For example you might want to use

644

Distiller to convert postscript files to pdf files. You

645

cannot simply change the name of the ps2pdf conversion

646

program, as in

647

648

$ps2pdf = 'distiller'; #########

649

WRONG

650

651

because the command line arguments will be wrong. In such

652

a situation, your best bet is to write a batch file (under

653

MS-Windows) or a script (under UNIX) that will do the con-

654

version. Then you set

655

656

657

658

16 May 2004 10

659

660

661

662

663

664

LATEXMK(1L) LATEXMK(1L)

665

666

667

$ps2pdf = 'special_script';

668

669

Your script will be invoked by latexmk in its usual way as

670

"Special_script file.ps file.pdf". Your script calls Dis-

671

tiller with Distiller's correct arguments.

672

673

674

LIST OF RC VARIABLES IN INITIALIZATION FILES

675

Default values are indicated in brackets.

676

677

$banner [0]

678

If nonzero, the banner message is printed across

679

each page when converting the dvi file to

680

postscript. Without modifying $banner_message,

681

this is equivalent to specifying the -d option.

682

683

Note that if $banner is nonzero, the

684

$postscript_mode is assumed and the postscript file

685

is always generated, even if it is newer than the

686

dvi file.

687

688

$banner_intensity [0.95]

689

Equivalent to the -bi option, this is a decimal

690

number between 0 and 1 that specifies how dark to

691

print the banner message. 0 is black, 1 is white.

692

The default is just right if your toner cartridge

693

isn't running too low.

694

695

$banner_message ["DRAFT"]

696

The banner message to print across each page when

697

converting the dvi file to postscript. This is

698

equivalent to the -bm option.

699

700

$banner_scale [220.0]

701

A decimal number that specifies how large the ban-

702

ner message will be printed. Experimentation is

703

necessary to get the right scale for your message,

704

as a rule of thumb the scale should be about equal

705

to 1100 divided by the number of characters in the

706

message. The Default is just right for 5 character

707

messages. This is equivalent to the -bs option.

708

709

$bibtex ["bibtex"]

710

The BibTeX processing program.

711

712

$bibtex_silent_switch ["-terse"]

713

Switch(es) for the BibTeX processing program when

714

silent mode is on.

715

716

$cleanup_mode [0]

717

If nonzero, specifies cleanup mode: 1 for full

718

cleanup, 2 for cleanup except for dvi, ps and pdf

719

files, 3 for cleanup except for dep and aux files.

720

This variable is equivalent to specifying one of

721

722

723

724

16 May 2004 11

725

726

727

728

729

730

LATEXMK(1L) LATEXMK(1L)

731

732

733

the -c, -c1, or -C options. There should be no

734

need to set this variable from an RC file.

735

736

$clean_ext [""]

737

Extra extensions of files for latexmk to remove

738

when the -c option is selected.

739

740

$clean_full_ext [""]

741

Extra extensions of files for latexmk to remove

742

when the -C option is selected.

743

744

@cus_dep_list [()]

745

Custom dependency list -- see section on "Custom

746

Dependencies".

747

748

@default_files [('*.tex')]

749

Default list of files to be processed.

750

751

Normally, if no filenames are specified on the com-

752

mand line, latexmk processes all tex files speci-

753

fied in the @default_files variable, which by

754

default is set to all tex files ('*.tex') in the

755

current directory. This is a convenience: just run

756

latexmk and it will process an appropriate set of

757

files. But sometimes you want only some of these

758

files to be processed. In this case you set the

759

(PERL array variable) @default_files in an initial-

760

ization file (e.g., the file "latexmkrc" in the

761

current directory). Then if no files are specified

762

on the command line then the files you specify by

763

setting @default_files are processed.

764

765

Three examples:

766

767

@default_files = ('paper_cur-

768

rent');

769

770

@default_files = ('paper1',

771

'paper2.tex');

772

773

@default_files = ('*.tex',

774

'*.dtx');

775

776

Note that more than file may be given, and that the

777

default extension is '.tex'. Wild cards are

778

allowed.

779

780

$dvi_filter [empty]

781

The dvi file filter to be run on the newly produced

782

dvi file before other processing. Equivalent to

783

specifying the -dF option.

784

785

$dvi_previewer ["start xdvi" under UNIX]

786

The command to invoke a dvi-previewer. [Default is

787

788

789

790

16 May 2004 12

791

792

793

794

795

796

LATEXMK(1L) LATEXMK(1L)

797

798

799

"start" under MS-WINDOWS; under more recent ver-

800

sions of Windows, this will cause to be run what-

801

ever command the system has associated with .dvi

802

files.]

803

804

$dvi_previewer_landscape ["start xdvi"]

805

The command to invoke a dvi-previewer in landscape

806

mode. [Default is "start" under MS-WINDOWS; under

807

more recent versions of Windows, this will cause to

808

be run whatever command the system has associated

809

with .dvi files.]

810

811

$dvipdf ["dvipdf"]

812

Command to convert dvi to pdf file. (WARNING: The

813

default dvipdf script generates pdf files with

814

bitmapped fonts, which don't look good when viewed

815

by acroread. The script should be modified to give

816

dvips the options "-P pdf" to ensure that type 1

817

fonts are used in the pdf file.)

818

819

$dvips ["dvips"]

820

The program to used as a filter to convert a .dvi

821

file to a .ps file. If pdf is going to be gener-

822

ated from pdf, then the value of the

823

$dvips_pdf_switch --- see below --- will be

824

appended.

825

826

$dvips_landscape ["dvips -tlandscape"]

827

The program to used as a filter to convert a .dvi

828

file to a .ps file in landscape mode.

829

830

$dvips_pdf_switch ["-P pdf"]

831

Switch(es) for dvips program when pdf file is to be

832

generated from ps file.

833

834

$dvips_silent_switch ["-q"]

835

Switch(es) for dvips program when silent mode is

836

on.

837

838

$dvi_update_method [2 under UNIX, 1 under MS-Windows]

839

How the dvi viewer updates its display when the dvi

840

file has changed. 0 => update is automatic, 1=>

841

manual update by user, which may only mean a mouse

842

click on the

843

viewer's window or may mean a more serious

844

action. 2 => Send the signal SIGUSR1 (as for xdvi

845

under UNIX), 3 => Viewer cannot do an update,

846

because it locks the file. (As with acroread under

847

MS-Windows.)

848

849

$force_generate_and_save_includes [0]

850

If nonzero, specifies that the dependency file

851

should always be generated. Equivalent to specify-

852

ing the -I option.

853

854

855

856

16 May 2004 13

857

858

859

860

861

862

LATEXMK(1L) LATEXMK(1L)

863

864

865

$force_mode [0]

866

If nonzero, continue processing past minor latex

867

errors including unrecognized cross references.

868

Equivalent to specifying the -f option. Note that

869

specifying the -pvc sets $forec_mode to 1.

870

871

$force_include_mode [0]

872

If nonzero, force latexmk to include files that

873

don't exist when generating dependency files. A

874

warning is produced instead of an error message and

875

the program terminating. If the file name is not

876

an absolute path, it is assumed to be relative to

877

the current working directory. Equivalent to spec-

878

ifying the -F option.

879

880

$generate_and_save_includes [0]

881

If nonzero, generates dependency file if it does

882

not exist or is older than the root file (the base

883

.tex file). Equivalent to specifying the -i

884

option.

885

886

@generated_exts [( 'ind', 'lof', 'lot', 'toc')]

887

This contains a list of extensions for files that

888

are generated (directly or indirectly) during a

889

LaTeX run and that are read in by LaTeX in later

890

runs. When latexmk generates a dependency list

891

from the .log file, it will ignore files with the

892

extensions in @generated_exts, since NORMALLY they

893

are not true source files, and the time stamps of

894

these may mislead latexmk as to whether the real

895

output files are up-to-date.

896

897

The extensions "aux" and "bbl" are always excluded

898

from the dependents, because they get special

899

treatment, so they do not need to be in this list.

900

901

$go_mode [0]

902

If nonzero, process files regardless of timestamps.

903

Equivalent to the -g option.

904

905

$includes_from_log [1]

906

If nonzero, extract dependency information from the

907

log file, rather than the source TeX file(s); this

908

is equivalent to the -il option. If zero, extract

909

dependency information by scanning the source TeX

910

file(s); this is equivalent to the -it option.

911

912

$index_mode [0 and then as determined from the results of

913

a run]

914

If nonzero, run makeindex to produce index of docu-

915

ment. Normally you should not need to set this

916

variable in an RC file, since latexmk determines

917

automatically if makeindex needs to be run.

918

919

920

921

922

16 May 2004 14

923

924

925

926

927

928

LATEXMK(1L) LATEXMK(1L)

929

930

931

$landscape_mode [0]

932

If nonzero, run in landscape mode, using the land-

933

scape mode previewers and dvi to postscript con-

934

verters. Equivalent to the -l option.

935

936

$latex ["latex"]

937

The LaTeX processing program. Note that as with

938

other programs, you can use this variable not just

939

to change the name of the program used, but also

940

specify options to the program. E.g.,

941

942

$latex = 'latex --src-spe-

943

cials';

944

945

$latex_silent_switch ["-interaction=batchmode"]

946

Switch(es) for the LaTeX processing program when

947

silent mode is on. Under MS-Windows, the default

948

value is changed to "-interaction=batchmode -c-

949

style-errors", as used by MikTeX and fpTeX.

950

951

$lpr ["lpr"]

952

[Default is "NONE lpr" under MS-WINDOWS.] The

953

printing program to print postscript files.

954

955

Under MS-Windows (unlike UNIX/LINUX), there is no

956

standard program for printing files. But there are

957

ways you can do it. For example, if you have

958

gsview installed, you can use it with the option

959

'/p':

960

961

$lpr = '"c:/Program Files/Ghost-

962

gum/gsview/gsview32.exe" /p';

963

964

If gsview is installed in a different directory,

965

you will need to make the appropriate change. Note

966

the double quotes around the name: this is neces-

967

sary because one part of the command name ('Program

968

Files') contains a space which would otherwise be

969

misinterpreted.

970

971

972

$lpr_dvi ["NONE lpr_dvi"]

973

The printing program to print dvi files.

974

975

$lpr_pdf ["NONE lpr_pdf"]

976

The printing program to print pdf files.

977

978

Under MS-Windows you could set this to use gsview,

979

if it is installed, e.g.,

980

981

$lpr = '"c:/Program Files/Ghost-

982

gum/gsview/gsview32.exe" /p';

983

984

If gsview is installed in a different directory,

985

986

987

988

16 May 2004 15

989

990

991

992

993

994

LATEXMK(1L) LATEXMK(1L)

995

996

997

you will need to make the appropriate change. Note

998

the double quotes around the name: this is neces-

999

sary because one part of the command name ('Program

1000

Files') contains a space which would otherwise be

1001

misinterpreted.

1002

1003

1004

$makeindex ["makeindex"]

1005

The index processing program.

1006

1007

$pdf_mode [0]

1008

If zero, do NOT generate a pdf version of the docu-

1009

ment. If equal to 1, generate a pdf version of the

1010

document using pdflatex. If equal to 2, generate a

1011

pdf version of the document from the ps file, by

1012

using the command specified by the $ps2pdf vari-

1013

able. If equal to 3, generate a pdf version of the

1014

document from the dvi file, by using the command

1015

specified by the $dvipdf variable. Equivalent to

1016

the -pdf-, -pdf, -pdfdvi, -pdfps options, and is

1017

stored in the dependency file if generated.

1018

1019

$pdflatex ["pdflatex"]

1020

The LaTeX processing program in the version that

1021

makes a pdf file instead of a dvi file.

1022

1023

$pdflatex_silent_switch ["-interaction=batchmode"]

1024

Switch(es) for the LaTeX processing program when

1025

silent mode is on. Under MS-Windows, the default

1026

value is changed to "-interaction=batchmode -c-

1027

style-errors", as used by MikTeX and fpTeX.

1028

1029

$pdf_previewer ["start acroread"]

1030

The command to invoke a pdf-previewer. [Default is

1031

changed to "start" on MS-WINDOWS; under more recent

1032

versions of Windows, this will cause to be run

1033

whatever command the system has associated with

1034

.pdf files.]

1035

1036

Potential problem under MS-Windows: if acroread is

1037

used as the pdf previewer, and it is actually view-

1038

ing a pdf file, the pdf file cannot be updated.

1039

Thus makes acroread a bad choice of previewer if

1040

you use latexmk's previous-continuous mode (option

1041

-pvc) under MS-windows. This problem does not

1042

occur if ghostview, gv or gsview is used to view

1043

pdf files.

1044

1045

$pdf_update_method [1 under UNIX, 3 under MS-Windows]

1046

How the pdf viewer updates its display when the pdf

1047

file has changed. See $dvi_update_method for the

1048

codes. Note that acroread under MS-Windows (but

1049

not UNIX) locks the pdf file, so the default value

1050

is then 3.

1051

1052

1053

1054

16 May 2004 16

1055

1056

1057

1058

1059

1060

LATEXMK(1L) LATEXMK(1L)

1061

1062

1063

$pid_position = [1 under UNIX, -1 under MS-Windows]

1064

Command used to get all the processes currently run

1065

by the user. The -pvc option uses the command

1066

specified by the variable $pscmd to determine if

1067

there is an already running previewer, and to find

1068

the process ID (needed if latexmk needs to signal

1069

the previewer about file changes). The variable

1070

$pid_position is used to specify which word in

1071

lines of the output from $pscmd corresponds to the

1072

process ID. The first word in the line is numbered

1073

0. The default value of 1 (2nd word in line) is

1074

correct for Solaris 2.6 and Linux. Setting the

1075

variable to -1 is used to indicate that $pscmd is

1076

not to be used.

1077

1078

$postscript_mode [0]

1079

If nonzero, generate a postscript version of the

1080

document. Equivalent to the -ps option.

1081

1082

$preview_continuous_mode [0]

1083

If nonzero, run a previewer to view the document,

1084

and continue running latexmk to keep .dvi up-to-

1085

date. Equivalent to the -pvc option. Which pre-

1086

viewer is run depends on the other settings, see

1087

the command line options $-view=.

1088

1089

$preview_mode [0]

1090

If nonzero, run a previewer to preview the docu-

1091

ment. Equivalent to the -pv option. Which pre-

1092

viewer is run depends on the other settings, see

1093

the command line options $-view=.

1094

1095

$printout_mode [0]

1096

If nonzero, print the document using lpr. Equiva-

1097

lent to the -p option. Recommend that this is not

1098

set from an RC file or you could waste lots of

1099

paper.

1100

1101

$print_type = ["ps"]

1102

Type of file to printout: possibilities are "dvi",

1103

"none", "pdf", or "ps".

1104

1105

$pscmd [On UNIX, the default is "ps -f -u $ENV{USER}". On

1106

MS-WINDOWS the default in "NONE pscmd".] Command

1107

used to get all the processes currently run by the

1108

user. This is used by the -pvc option to determine

1109

if there is an already running previewer. The com-

1110

mand line options for this command under the dif-

1111

ferent flavors of UNIX are quite variable. The

1112

command given is suitable for Solaris 2.6 and for

1113

Linux. The variable $pid_position must also be

1114

set: see its description.

1115

1116

1117

1118

1119

1120

16 May 2004 17

1121

1122

1123

1124

1125

1126

LATEXMK(1L) LATEXMK(1L)

1127

1128

1129

$ps2pdf ["ps2pdf"]

1130

Command to convert ps to pdf file.

1131

1132

$ps_filter [empty]

1133

The postscript file filter to be run on the newly

1134

produced postscript file before other processing.

1135

Equivalent to specifying the -pF option.

1136

1137

$ps_previewer ["start gv -watch"]

1138

The command to invoke a ps-previewer. [Default is

1139

"start" on MS-WINDOWS; under more recent versions

1140

of Windows, this will cause to be run whatever com-

1141

mand the system has associated with .ps files.]

1142

1143

Note that gv with the -watch option updates its

1144

display whenever the postscript file changes,

1145

whereas ghostview does not.

1146

1147

$ps_previewer_landscape ["start gv -swap -watch"]

1148

The command to invoke a ps-previewer in landscape

1149

mode. [Default is "start" on MS-WINDOWS; under

1150

more recent versions of Windows, this will cause to

1151

be run whatever command the system has associated

1152

with .ps files.]

1153

1154

$ps_update_method [0 under UNIX, 1 under MS-Windows]

1155

How the postscript viewer updates its display when

1156

the ps file has changed. See $dvi_update_method for

1157

the codes.

1158

1159

$sleep_time [2]

1160

The time to sleep (in seconds) between checking for

1161

source file changes when running the -pvc option.

1162

1163

$texfile_search [""]

1164

This is an obsolete variable, replaced by the

1165

@default_files variable -- see the description of

1166

@default_files for how it works.

1167

1168

For backward compatibility, if you choose to set

1169

it, $texfile_search is a string of space-separated

1170

filenames, and then latexmk replaces @default_files

1171

with the filenames in $texfile_search to which is

1172

added '*.tex'.

1173

1174

$tmpdir ["/tmp" under UNIX, value of environment variable

1175

TEMP under MS-Windows]

1176

Directory to store temporary files that latexmk

1177

generates while running. Currently it only has a

1178

minor use, when making a banner to insert in a

1179

postscript file. There should be no trailing sepa-

1180

rator. It should not be necessary to change this

1181

value except when running under Cygwin.

1182

1183

1184

1185

1186

16 May 2004 18

1187

1188

1189

1190

1191

1192

LATEXMK(1L) LATEXMK(1L)

1193

1194

1195

CUSTOM DEPENDENCIES

1196

In any RC file a set of custom dependencies can be set up

1197

to convert a file with one extension to a file with

1198

another. An example use of this would be to allow latexmk

1199

to convert a .fig file to dependencies are set up by using

1200

the @cus_dep_list array. Each string in the array has

1201

four arguments, separated by a space:

1202

1203

from extension:

1204

The extension of the file we are converting from

1205

(e.g. "fig").

1206

1207

to extension:

1208

The extension of the file we are converting to

1209

(e.g. "eps").

1210

1211

must: If non-zero, the file we are converting from must

1212

exist, if it doesn't exist latexmk will give an

1213

error message and exit unless the -f option is

1214

specified. If must is zero and the file we are

1215

converting from doesn't exist, then no action is

1216

taken.

1217

1218

function:

1219

The name of the subroutine that latexmk should call

1220

to perform the file conversion. The first argument

1221

to the subroutine is the base name of the file to

1222

be converted without any extension. The subrou-

1223

tines are declared in the syntax of perl. The

1224

function should return 0 if it was successful and a

1225

nonzero number if it failed.

1226

1227

Example in an RC file to convert a .fig file to a .eps

1228

file:

1229

1230

@cus_dep_list = (@cus_dep_list, "fig eps 0 fig2eps");

1231

1232

sub fig2eps {

1233

system("fig2dev -Lps $_[0].fig $_[0].eps"); }

1234

1235

The subroutine fig2eps will only be called if the .fig

1236

file was modified more recently then the .eps file, or the

1237

.eps file does not exist.

1238

1239

If the return value of the subroutine is non-zero, then

1240

latexmk will assume an error occurred during the execution

1241

of the subroutine.

1242

1243

1244