Additional LYX Features

Version 2.4.x

by the LYX Team∗

May 13, 2024

∗ Principal
maintainer of this file is Richard Kimberly Heck. If you have com-
ments or error corrections, please send them to the LYX Documentation mailing list,
<[email protected]>.
Contents
1 Introduction 1

2 LYX and LATEX 3

2.1 How LYX Uses LATEX . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Translating LATEX files into LYX . . . . . . . . . . . . . . . . . . . . . 4
2.3 Inserting TEX Code into LYX Documents . . . . . . . . . . . . . . . . 4
2.4 LYX and the LATEX Preamble . . . . . . . . . . . . . . . . . . . . . . 5
2.4.1 About the LATEX Preamble . . . . . . . . . . . . . . . . . . . . 5
2.4.2 Changing the Preamble . . . . . . . . . . . . . . . . . . . . . . 6
2.4.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4.3.1 Example #1: Offsets . . . . . . . . . . . . . . . . . . 6
2.4.3.2 Example #2: Labels . . . . . . . . . . . . . . . . . . 7
2.4.3.3 Example #3: Paragraph Indentation . . . . . . . . . 7
2.4.3.4 Example #4: This Document . . . . . . . . . . . . . 8
2.5 LYX and LATEX Errors . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3 Document classes 13
3.1 Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.1.1 AMS-LATEX (American Mathematical Society) . . . . . . . . . 13
3.1.1.1 What these layouts provide . . . . . . . . . . . . . . 14
3.1.2 Extra font sizes . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.1.3 Hebrew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.1.4 Japanese (Standard Classes) . . . . . . . . . . . . . . . . . . . 17
3.1.5 Japanese (JS Bundle) . . . . . . . . . . . . . . . . . . . . . . . 17
3.1.6 Japanese (BX Bundle) . . . . . . . . . . . . . . . . . . . . . . 17
3.1.7 Japanese (JLReq Class) . . . . . . . . . . . . . . . . . . . . . 18
3.1.8 KOMA-Script . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.1.8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 18
3.1.8.2 KOMA-Script Article, KOMA-Script Report, and KOMA-
Script Book . . . . . . . . . . . . . . . . . . . . . . . 19
3.1.8.3 The new letter class: KOMA-Script Letter (V. 2) . . 22
3.1.8.4 Problems . . . . . . . . . . . . . . . . . . . . . . . . 22
3.1.9 Polish M. W. collection . . . . . . . . . . . . . . . . . . . . . . 23
3.1.10 Tufte Collection . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.2 Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.2.1 Astronomy & Astrophysics . . . . . . . . . . . . . . . . . . . . 24
3.2.1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . 24

iii
Contents

3.2.1.2 Getting started . . . . . . . . . . . . . . . . . . . . . 24

3.2.1.3 The header block . . . . . . . . . . . . . . . . . . . . 25
3.2.1.4 The abstract . . . . . . . . . . . . . . . . . . . . . . 25
3.2.1.5 Supported environments . . . . . . . . . . . . . . . . 26
3.2.1.6 Commands not supported by LYX . . . . . . . . . . 26
3.2.1.7 Figure and Table Floats . . . . . . . . . . . . . . . . 26
3.2.1.8 Referee layout . . . . . . . . . . . . . . . . . . . . . . 27
3.2.1.9 The example paper . . . . . . . . . . . . . . . . . . . 27
3.2.2 AASTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . 27
3.2.2.2 Starting a New Paper . . . . . . . . . . . . . . . . . 28
3.2.2.3 Finishing Your Paper . . . . . . . . . . . . . . . . . . 28
3.2.2.4 Comments On Specific Commands . . . . . . . . . . 29
3.2.2.5 FAQs, Tips, Tricks, and Other Ruminations . . . . . 30
3.2.2.6 Final Caveat . . . . . . . . . . . . . . . . . . . . . . 31
3.2.3 Chess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2.4 Elsevier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2.5 Paper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2.6 RevTEX4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2.6.1 Installation . . . . . . . . . . . . . . . . . . . . . . . 32
3.2.6.2 Preamble Matter . . . . . . . . . . . . . . . . . . . . 33
3.2.6.3 Layouts . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.2.6.4 Important Notes . . . . . . . . . . . . . . . . . . . . 33
3.2.7 Springer Journals . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.3 Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.3.1 Memoir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.3.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 34
3.3.1.2 Basic features and restrictions . . . . . . . . . . . . . 34
3.3.1.3 Extra features . . . . . . . . . . . . . . . . . . . . . . 35
3.3.2 Recipe Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.4 Curricula vitae . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.4.1 Europass (2013) . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.4.2 Europe CV . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.4.3 Modern CV . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.4.4 Simple CV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.5 Letters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.5.1 DIN-Brief . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.5.2 French letter (frletter) . . . . . . . . . . . . . . . . . . . . . . 37
3.5.3 French letter (lettre) . . . . . . . . . . . . . . . . . . . . . . . 37
3.5.4 G-Brief (V. 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.6 Presentations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.6.1 Beamer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.6.2 FoilTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.6.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . 38

iv
 Contents

3.6.2.2 Getting Started . . . . . . . . . . . . . . . . . . . . . 38

3.6.2.3 Supported Environments . . . . . . . . . . . . . . . . 40
3.6.2.4 Building a Set of Foils . . . . . . . . . . . . . . . . . 41
3.6.2.5 Unsupported FoilTEX Goodies . . . . . . . . . . . . . 42
3.6.3 Powerdot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.6.4 Seminar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.6.5 Slides [aka SliTEX] . . . . . . . . . . . . . . . . . . . . . . . 44
3.6.5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . 44
3.6.5.2 Getting Started . . . . . . . . . . . . . . . . . . . . . 44
3.6.5.3 Paragraph Environments . . . . . . . . . . . . . . . . 44
3.6.5.4 Making a Presentation with Slide, Overlay and Note 46
3.6.5.5 The slides Class Template File . . . . . . . . . . . . 48
3.7 Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.7.1 report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.8 Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.8.1 Broadway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.8.1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . 50
3.8.1.2 Special problems . . . . . . . . . . . . . . . . . . . . 50
3.8.1.3 Special features . . . . . . . . . . . . . . . . . . . . . 50
3.8.1.4 Paper size and Margins . . . . . . . . . . . . . . . . 50
3.8.1.5 Environments . . . . . . . . . . . . . . . . . . . . . . 50
3.8.2 Hollywood (Hollywood spec scripts) . . . . . . . . . . . . . . . 51
3.8.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . 51
3.8.2.2 Special problems . . . . . . . . . . . . . . . . . . . . 51
3.8.2.3 Special features . . . . . . . . . . . . . . . . . . . . . 51
3.8.2.4 Paper size and Margins . . . . . . . . . . . . . . . . 51
3.8.2.5 Environments . . . . . . . . . . . . . . . . . . . . . . 52
3.8.2.6 Script jargon . . . . . . . . . . . . . . . . . . . . . . 52

4 Modules 53
4.1 Academic Field Specifics . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.1.1 Chemistry: Hazard and Precautionary Statements . . . . . . . 53
4.1.2 Chemistry: Risk and Safety Statements . . . . . . . . . . . . . 53
4.1.3 Linguistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.2 Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.2.1 Braille . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.3 Annotation & Revision . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.3.1 FiXme Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.3.2 PDF Comments . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.3.3 PDF Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.3.4 Ruby (Furigana) . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.3.5 TODO notes . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.4 Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.4.1 APA Style with Natbib . . . . . . . . . . . . . . . . . . . . . . 54

v
Contents

4.5 Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.5.1 Fancy Colored Boxes . . . . . . . . . . . . . . . . . . . . . . . 55
4.5.2 Graphic boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.5.3 Section Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.5.4 Variable-width Minipages . . . . . . . . . . . . . . . . . . . . 56
4.6 Fixes & Hacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.6.1 Fix Computer Modern Fonts . . . . . . . . . . . . . . . . . . . 56
4.6.2 LATEX Kernel Fixes (Obsolete) . . . . . . . . . . . . . . . . . . 56
4.6.3 Minimalistic Insets . . . . . . . . . . . . . . . . . . . . . . . . 56
4.6.4 Title and Preamble Hacks . . . . . . . . . . . . . . . . . . . . 56
4.7 Floats & captions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4.7.1 Algorithm2e Float . . . . . . . . . . . . . . . . . . . . . . . . 57
4.7.2 Bilingual Captions AKA Multilingual Captions . . . . . . . . 57
4.7.3 Number Figures by Section . . . . . . . . . . . . . . . . . . . 57
4.7.4 Number Tables by Section . . . . . . . . . . . . . . . . . . . . 57
4.8 Foot- and Endnotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4.8.1 Endnotes (Basic) . . . . . . . . . . . . . . . . . . . . . . . . . 57
4.8.2 Endnotes (Extended) . . . . . . . . . . . . . . . . . . . . . . . 57
4.8.3 Footnotes as Endnotes (Basic) . . . . . . . . . . . . . . . . . . 58
4.8.4 Footnotes as Endnotes (Extended) . . . . . . . . . . . . . . . 58
4.9 Leisure, Sports and Music . . . . . . . . . . . . . . . . . . . . . . . . 58
4.9.1 Chess Board . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
4.9.2 Lilypond Music Notation . . . . . . . . . . . . . . . . . . . . . 58
4.10 List enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
4.10.1 Customizable Lists . . . . . . . . . . . . . . . . . . . . . . . . 58
4.10.1.1 Custom Enumerate Lists . . . . . . . . . . . . . . . . 59
4.10.1.2 Numbered Paragraphs in Reports . . . . . . . . . . . 59
4.10.1.3 Resumed Enumeration . . . . . . . . . . . . . . . . . 60
4.10.1.4 List Spacing . . . . . . . . . . . . . . . . . . . . . . . 60
4.10.1.5 Further Customization . . . . . . . . . . . . . . . . . 61
4.10.2 Paragraph Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 61
4.11 Literate Programming . . . . . . . . . . . . . . . . . . . . . . . . . . 62
4.11.1 Noweb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
4.11.2 Rnw (knitr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
4.11.3 Sweave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
4.12 Maths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
4.12.1 AMS Theorems . . . . . . . . . . . . . . . . . . . . . . . . . . 62
4.12.2 AMS Theorems (Extended) . . . . . . . . . . . . . . . . . . . 63
4.12.3 AMS Theorems (Extended, Numbered by Type within Chapters) 63
4.12.4 AMS Theorems (Extended, Numbered by Type) . . . . . . . . 63
4.12.5 AMS Theorems (Numbered by Type within Chapters) . . . . 63
4.12.6 AMS Theorems (Numbered by Type) . . . . . . . . . . . . . . 64
4.12.7 Number Equations by Section . . . . . . . . . . . . . . . . . . 64
4.12.8 Standard Theorems . . . . . . . . . . . . . . . . . . . . . . . . 64

vi
 Contents

4.12.9 Standard Theorems (Nameable) . . . . . . . . . . . . . . . . . 64

4.12.10 Standard Theorems (Numbered by Chapter) . . . . . . . . . . 64
4.12.11 Standard Theorems (Numbered by Section) . . . . . . . . . . 64
4.12.12 Standard Theorems (Numbered by Type within Chapters) . . 65
4.12.13 Standard Theorems (Numbered by Type within Sections) . . . 65
4.12.14 Standard Theorems (Numbered by Type) . . . . . . . . . . . . 65
4.12.15 Standard Theorems (Unnumbered) . . . . . . . . . . . . . . . 65
4.12.16 Subequations . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
4.13 Page Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
4.13.1 Custom Header/Footer Text . . . . . . . . . . . . . . . . . . . 66
4.13.1.1 Fancy Headers and Footers . . . . . . . . . . . . . . 66
4.13.2 Landscape Document Parts . . . . . . . . . . . . . . . . . . . 68
4.13.3 Multiple Columns . . . . . . . . . . . . . . . . . . . . . . . . . 68
4.13.3.1 Basics . . . . . . . . . . . . . . . . . . . . . . . . . . 68
4.13.3.2 Columns inside Columns . . . . . . . . . . . . . . . . 69
4.13.3.3 Advanced Examples . . . . . . . . . . . . . . . . . . 70
4.13.3.4 This is a subsubsection heading as a preface . . . . . 70
4.14 Paragraph Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
4.14.1 Custom Paragraph Shapes . . . . . . . . . . . . . . . . . . . . 74
4.14.1.1 Predefined shapes . . . . . . . . . . . . . . . . . . . 74
4.14.1.2 Custom shapes . . . . . . . . . . . . . . . . . . . . . 78
4.14.2 Hanging Paragraphs . . . . . . . . . . . . . . . . . . . . . . . 79
4.14.3 Initials (Drop Caps) . . . . . . . . . . . . . . . . . . . . . . . 79
4.15 Text Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
4.15.1 Hyphenatable Text Markup (Soul) . . . . . . . . . . . . . . . 80
4.15.2 Logical Markup . . . . . . . . . . . . . . . . . . . . . . . . . . 80

5 Bibliography 81
5.1 Alternative Citation Styles . . . . . . . . . . . . . . . . . . . . . . . . 81
5.2 Subdivided Bibliographies . . . . . . . . . . . . . . . . . . . . . . . . 81
5.3 Multiple Bibliographies . . . . . . . . . . . . . . . . . . . . . . . . . . 82

6 Bullets 85
6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
6.2 How it looks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
6.3 How to use it . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

7 Supplemental Tools 87
7.1 Multipart Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.1.1 General Operation . . . . . . . . . . . . . . . . . . . . . . . . 87
7.1.2 Cross-References Between Files . . . . . . . . . . . . . . . . . 88
7.1.3 Bibliography Lists in all Subdocuments . . . . . . . . . . . . . 88
7.2 LYX Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

vii
Contents

8 LYX and the World Wide Web 91

8.1 Math Output in XHTML . . . . . . . . . . . . . . . . . . . . . . . . . 92
8.2 Bibliography and Citations . . . . . . . . . . . . . . . . . . . . . . . . 93
8.3 Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
8.4 Nomenclature and Glossary . . . . . . . . . . . . . . . . . . . . . . . 95

9 DocBook Output 97

10 The LYX Server 99

10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
10.2 Starting the LYX Server . . . . . . . . . . . . . . . . . . . . . . . . . 99
10.3 Normal communication . . . . . . . . . . . . . . . . . . . . . . . . . . 100
10.3.1 AppleScript (Mac OS X) . . . . . . . . . . . . . . . . . . . . . 100
10.4 Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
10.5 The simple LYX Server Protocol . . . . . . . . . . . . . . . . . . . . . 101
10.6 Reverse DVI/PDF search . . . . . . . . . . . . . . . . . . . . . . . . . 101
10.6.1 Automatic setup . . . . . . . . . . . . . . . . . . . . . . . . . 102
10.6.2 Manual setup . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
10.6.3 Configuring and using specific viewers . . . . . . . . . . . . . 104
10.7 Forward search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

11 LYX Features needing Extra Software 109

11.1 Checking TEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
11.1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
11.1.2 How to use it . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
11.1.3 How to fine tune it . . . . . . . . . . . . . . . . . . . . . . . . 110
11.2 Version Control in LYX . . . . . . . . . . . . . . . . . . . . . . . . . . 113
11.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
11.2.2 RCS commands in LYX . . . . . . . . . . . . . . . . . . . . . . 113
11.2.2.1 Register . . . . . . . . . . . . . . . . . . . . . . . . . 113
11.2.2.2 Check In Changes . . . . . . . . . . . . . . . . . . . 114
11.2.2.3 Check Out For Edit . . . . . . . . . . . . . . . . . . 114
11.2.2.4 Revert To Repository Version . . . . . . . . . . . . . 114
11.2.2.5 Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
11.2.2.6 Undo Last Checkin . . . . . . . . . . . . . . . . . . . 115
11.2.2.7 Show History . . . . . . . . . . . . . . . . . . . . . . 115
11.2.2.8 Revision info . . . . . . . . . . . . . . . . . . . . . . 115
11.2.3 CVS commands in LYX . . . . . . . . . . . . . . . . . . . . . . 115
11.2.3.1 General CVS usage . . . . . . . . . . . . . . . . . . . 115
11.2.3.2 Register . . . . . . . . . . . . . . . . . . . . . . . . . 116
11.2.3.3 Check In Changes . . . . . . . . . . . . . . . . . . . 116
11.2.3.4 Check Out Changes . . . . . . . . . . . . . . . . . . 116
11.2.3.5 Revert To Repository Version . . . . . . . . . . . . . 117
11.2.3.6 Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

viii
 Contents

11.2.3.7 Rename . . . . . . . . . . . . . . . . . . . . . . . . . 117

11.2.3.8 Update of the local directory checkout from repository 117
11.2.3.9 Show History . . . . . . . . . . . . . . . . . . . . . . 118
11.2.3.10 Revision info . . . . . . . . . . . . . . . . . . . . . . 118
11.2.4 SVN commands in LYX . . . . . . . . . . . . . . . . . . . . . . 118
11.2.4.1 Register . . . . . . . . . . . . . . . . . . . . . . . . . 118
11.2.4.2 Check In Changes . . . . . . . . . . . . . . . . . . . 119
11.2.4.3 Check Out For Edit . . . . . . . . . . . . . . . . . . 119
11.2.4.4 Revert To Repository Version . . . . . . . . . . . . . 119
11.2.4.5 Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
11.2.4.6 Rename . . . . . . . . . . . . . . . . . . . . . . . . . 119
11.2.4.7 Update of the local directory checkout from repository1 120
11.2.4.8 Show History . . . . . . . . . . . . . . . . . . . . . . 120
11.2.4.9 File Locking . . . . . . . . . . . . . . . . . . . . . . . 120
11.2.4.10 Automatic Locking Property . . . . . . . . . . . . . 121
11.2.4.11 Revision Information in Documents . . . . . . . . . . 121
11.2.5 SVN and Windows Environment . . . . . . . . . . . . . . . . 122
11.2.5.1 Preparation . . . . . . . . . . . . . . . . . . . . . . . 122
11.2.5.2 Bringing a document under Subversion control . . . . 123
11.2.5.3 SSH tunnel used with SVN under Windows . . . . . 123
11.2.5.4 End-of-Line Conversions . . . . . . . . . . . . . . . . 124
11.2.6 GIT commands in LYX . . . . . . . . . . . . . . . . . . . . . . 124
11.2.6.1 Register . . . . . . . . . . . . . . . . . . . . . . . . . 125
11.2.6.2 Check In Changes . . . . . . . . . . . . . . . . . . . 125
11.2.6.3 Revert To Repository Version . . . . . . . . . . . . . 125
11.2.6.4 Rename . . . . . . . . . . . . . . . . . . . . . . . . . 125
11.2.6.5 Show History . . . . . . . . . . . . . . . . . . . . . . 126
11.2.6.6 Version Info . . . . . . . . . . . . . . . . . . . . . . . 126
11.2.7 Further tuning . . . . . . . . . . . . . . . . . . . . . . . . . . 126
11.2.8 Version control and Document comparison . . . . . . . . . . . 126
11.3 Literate Programming . . . . . . . . . . . . . . . . . . . . . . . . . . 127
11.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
11.3.2 Literate Programming . . . . . . . . . . . . . . . . . . . . . . 127
11.3.2.1 References . . . . . . . . . . . . . . . . . . . . . . . . 127
11.3.3 LYX and Literate Programming with Noweb . . . . . . . . . . 128
11.3.3.1 Generating documents and code (weaving and tangling)128
11.3.3.2 Configuring LYX . . . . . . . . . . . . . . . . . . . . 131
11.3.3.3 Debug extensions . . . . . . . . . . . . . . . . . . . . 132
11.3.3.4 Toolbar extensions . . . . . . . . . . . . . . . . . . . 132
11.3.3.5 Colors customization . . . . . . . . . . . . . . . . . . 133
11.3.4 LYX and knitr/Sweave . . . . . . . . . . . . . . . . . . . . . . 133

1
Note that this command will work only with subversion ≧ 1.5

ix
Contents

Index 135

x
1 Introduction
This manual is essentially Part II of the User’s Guide. The reason for separating the
two documents is simple: the User’s Guide is already quite lengthy, and it contains
information on all of the basic features one needs to know in order to prepare most
documents. However, the LYX Team has worked to make LYX extensible through
various configuration files and external packages. That means that if you want to
support the Fizzwizzle LATEX package, you can create a layout file (or module) for it
without having to alter LYX itself. We’ve already had contributions of several new
features this way, and some of them are documented here. There are also some more
‘advanced’ features, such as how to control the presentation of bibliographies and
how to work with multi-part documents, that are not covered in the User’s Guide
and are discussed here.
This manual also documents some special features, like fax support and version
control, which require additional software to work properly. There is also a chapter
on LYX’s support for HTML. And lastly, there’s a chapter of LATEX tools and tips,
things you can use to spruce up your documents by directly using the powerful
features of LATEX. After all, LYX is only WYSIWYM and will only ever interface to
some, not all, LATEX features.
If you haven’t read the Introduction yet, you are definitely in the wrong manual.
The Introduction is the first place to go, since it describes the notation and format
of all of the manuals. You should also be thoroughly familiar with the User’s Guide
and all of the basic features of LYX before attempting to read this one.
Since many of the topics in this manual depend heavily on LYX’s interaction with
L TEX, this first chapter covers the inner workings of LYX and how to direct LYX to
A

generate exactly the LATEX code you want. It is obviously for more seasoned LYX
users.

1
2 LYX and LATEX
2.1 How LYX Uses LATEX
This chapter is for both TEX-nicians and the LATEX-curious. In it, we’ll explain how
LYX and LATEX work together to produce printable output. This is the only place in
any of the manuals where we assume you know something about LATEX.
At one time, LYX was called a “WYSIWYM frontend to LATEX,” but that’s no
longer true. There are frontends to LATEX out there.1 These are basically text editors
with the ability to run LATEX and mark any errors in the file you’re editing. Although
LYX is an editor, and it does run LATEX, and it also indicates errors in the file, it
also does much, much more. For one thing, you don’t need to know LATEX to use
LYX effectively. And LYX has added its own extensions to LATEX. Try the following
sometime: select Export ▷ LaTeX from the File menu (or View ▷ Source Pane), then
look at the preamble of the resulting .tex file. You’ll notice a variety of new macros
defined specifically by LYX. These macros are defined automatically, according to
the features you use in the document.
There are several commands that automatically invoke LATEX. They are:
• Document ▷ View
• Document ▷ Update
They will only invoke LATEX if the file has changed since the last time LATEX was run.
When LYX runs LATEX on the file you’re editing, it performs these steps:
1. Convert the document to LATEX and save to a file with the extension .tex in
place of .lyx.
2. Run LATEX on the .tex file (maybe several times), and run any other commands
(such as bibtex or makeindex) needed to compile the LATEX file.
3. If there are any errors, show the error log.
If you have run LATEX using View ▷ DVI, LYX then runs a DVI viewer to display the
DVI-file. If you have used View ▷ PostScript, LYX performs further steps:
1. Run dvips to convert the DVI file to PostScript.
2. Run a PostScript viewer, such as ghostview, to display the PostScript file.
LYX does similar things when viewing, or exporting, other formats.
1
Some familar ones are TEXmaker and kile, on Linux, and TEXshop, OSX. There are also the
LATEX modes for vi and emacs, of course.

3
2 LYX and LATEX

2.2 Translating LATEX files into LYX

You can import a LATEX file into LYX by using the File ▷ Import ▷ LaTeX command in
LYX. This will call a program named tex2lyx which will create a file foo.lyx from
the file foo.tex. LYX will then open that file.2
tex2lyx will translate most legal LATEX, but not everything. It will put things it
doesn’t understand into TEX code, so after translating a file with tex2lyx, you can
look for TEX code and hand-edit it until it looks right.
If you don’t know what TEX code is, read the next section.

2.3 Inserting TEX Code into LYX Documents

Anything you can do in LATEX you can do in LYX, for a very simple reason: You
can always insert TEX code into any LYX document. LYX cannot, and will never
be able to, display every possible LATEX construct. If ever you need to insert LATEX
commands into your LYX document, you can use the TEX Code box, which you can
insert into your document with Insert ▷ TeX Code or the keyboard shortcut .
Here’s an example of inserting LATEX commands in a LYX document. The code
looks like this:

\begin{tabular}{ll}
\begin{minipage}{5cm}
This is an example of a minipage environment. You
can put nearly everything in it, even (non-floating)
figures and tables.
\end{minipage}
&
\begin{minipage}{5cm}
\begin{verbatim}
\begin{minipage}{5cm}
This ...
\end{minipage}
\end{verbatim}
\end{minipage}
\end{tabular}

The TEX Code box containing this text is directly after this paragraph. Those of you
reading the manual in LYX will only see the TEX code inset. Those reading a printed
version of the manuals will see the actual results:
2
tex2lyx can also be run from the command line, of course.

4
 2.4 LYX and the LATEX Preamble

This is an example of a
minipage environment. You \begin{minipage}{5cm}
can put nearly everything in This ...
it, even (non-floating) fig- \end{minipage}
ures and tables.
In addition to using TEX code, you can also create a separate file containing some
complex LATEX structure and then use Insert ▷ Child Document to include your file
(you should select the type Input). We recommend that you only do this if you have
a .tex file which you know works already. Otherwise, you’ll have a big job tracking
down LATEX errors.
There are a few last points to emphasize:

• LYX does not check if your LATEX code is correct.

• Beware of reinventing the wheel.

On that last point, LYX does have quite a few features tucked into it, and more are
coming. Be sure to check the manuals to make sure that LYX doesn’t have such-
and-such feature before you decide you have to do it by hand. Moreover, there are
numerous LATEX packages out there to do all sorts of things, from labels to envelopes
to fancy multipage tables. Check out CTAN for details.
If you do need to do some wild and fancy things within your document, be sure to
check out a good LATEX book for assistance. There are a number of them listed in
the bibliography of the User’s Guide.

2.4 LYX and the LATEX Preamble

2.4.1 About the LATEX Preamble
If you already know LATEX, there is no need to explain here what the preamble is
good for. If you don’t, the following will give you some ideas—we recommend again
that you consult a LATEX book for further information. In any case, you should read
the points below, because they explain what you can do and what you don’t need to
do in the LATEX preamble of a LYX document.
The LATEX preamble comes at the very beginning of a document, before the text.
It serves to:

• Declare the document class.

LYX already does this for you. If you’re a seasoned LATEX-nician, and you have
a custom document class you want to use, check out the Customization Manual
for information on how to make LYX interface to it.

• Declare the usage of packages.

LATEX packages provide special commands, which are only available within a
document when the package has been declared in the preamble. In addition

5
2 LYX and LATEX

to providing special commands, the inclusion of a package can change the doc-
ument. For example, the package indentfirst forces all paragraphs to be
indented. There are other packages for labels, envelopes, margins, etc.

• Set counters, variables, lengths and widths.

There are several LATEX counters and variables that must be set globally from
within the preamble in order to have the desired effect. (There are variables
that you can set and reset inside the document, too.) Margins are a good
example of something that must be set in the preamble. Another example is
the label format for lists. You can actually set these just about anywhere, but
it’s best to do it just once, inside the preamble.

• Declare user defined commands (with \newcommand or \renewcommand).

These are abbreviations for LATEX commands which appear very often inside a
document. Although the preamble is a good place to declare such commands,
they can be declared anywhere (before they are used for the first time, of
course). This can be useful if there is a lot of raw LATEX code in your document,
which normally should not be the case.

LYX adds its own set of definitions to the preamble of the .tex file it produces. This
makes LATEX files generated by LYX portable.

2.4.2 Changing the Preamble

The commands which LYX adds to the preamble of a LATEX file are fixed; you can’t
change them without patching LYX itself. You can, however, add your own stuff to the
preamble by selecting LATEX Preamble in the Document ▷ Settings dialog. LYX adds
anything in the Preamble dialog to its own built-in preamble. Before adding your
own declarations in the preamble, you should make sure that LYX doesn’t already
support what you want to do. (Remember what we said about reinventing the wheel?)
Also, make sure your preamble code is correct. LYX doesn’t check it for you. If there
is an error, you’re likely to get an error like “Missing \begin{document}”. If you
see this error, check your preamble.

2.4.3 Examples
Here are some examples of what you can add to a preamble, and what they do.

2.4.3.1 Example #1: Offsets

There are two variables under LATEX that control page position: \hoffset and
\voffset. Their names should be self-explanatory. These variables are useful if you
think for a moment about computer labels. Sometimes, the size of a print medium
and the area of the medium that you can actually print on aren’t the same. This is
where \hoffset and \voffset come in.

6
 2.4 LYX and the LATEX Preamble

The default values for \hoffset and \voffset are both 0 points, i. e. the page
isn’t shifted. Unfortunately, some DVI drivers always seem to shift the page. We
have no idea why, or why the sysadmin hasn’t fixed such behavior. If you’re using
LYX on a system that you don’t personally maintain, and your sysadmin is a doofus,
\hoffset and \voffset can save the day. Suppose your left and top margins are
always 0.5 inches too big. You can add this to the preamble:

\setlength{\hoffset}{-0.5 in}
\setlength{\voffset}{-0.5 in}

and your margins should now be correct.

2.4.3.2 Example #2: Labels

Speaking of labels, suppose you wanted to print out a bunch of address labels. There’s
a rather nice package, available at your nearest CTAN archive, for printing sheets
of labels: labels.sty. Now, your system may not have this package installed by
default. We leave that up to you to check. You’ll also want to read the documentation
for it; we’re not going to do that for you. Since this is an example, however, we’ll
give you an example of how you use this package.
First, make sure you’re using the article document class. Next, you need to put
the following in your preamble:

\usepackage{labels}
\LabelCols=3
\LabelRows=7
\LeftBorder=8mm
\RightBorder=8mm
\TopBorder=9mm
\BottomBorder=2mm

This sets things up for Avery label sheets, stock #5360. You’re now ready to print la-
bels, but you’ll need to insert LATEX code, placing the commands \begin{labels} and
\end{labels} around each label text. This and other special features of labels.sty
are explained in its documentation.
Someday, someone may write a LYX layout file to support this package directly.
Maybe that someone is you.

2.4.3.3 Example #3: Paragraph Indentation

Americans are trained to indent the first line of every paragraph. As with all of their
other weird quirks, most Americans will whine and moan until they can have their
way and indent the first line of all paragraphs. (Yes, we’re joking. (We are?) Yeah,
we are.)

7
2 LYX and LATEX

Of course, this behavior isn’t standard typography. In books, you typically only
indent the first line of a paragraph if it follows another one. The idea behind indenting
the first line of a paragraph is to distinguish neighboring paragraphs from one another.
If there is no previous paragraph—for example, if it follows a figure or is the first
paragraph in a section—then there is no need for indentation.
If you’re a typical American (we’re still joking!), though, you don’t care about such
esoteric things; you want your indentation! Add this to the preamble:

\usepackage{indentfirst}

If your TEX distribution isn’t braindead, you’ll have this package, and all of your
paragraphs will get the indentation the Founding Fathers intended they should have.

2.4.3.4 Example #4: This Document

You can also check out the preamble of this document to get an idea of some of the
advanced things you can do.

2.5 LYX and LATEX Errors

When LYX calls LATEX, it tells LATEX to blithely ignore any errors and keep going. It
then uses the logfile from the LATEX run to do a post-mortem. After analyzing the
logfile, LYX displays a dialog listing the errors. Clicking on any one of them will take
you to the position in your LYX file where the error occurred.3
Some folks also like to look at the log file directly: It is available from Document ▷
LaTeX Log. There are some fairly common error messages and warnings. We’ll cover
those here. You should look at a good LATEX book for a complete listing.

• LaTeX Warning
Anything beginning with these words is a warning message for the purpose of
“debugging” the LATEX code itself. You’ll get messages like this if you added or
changed cross-references or bibliography entries, in which case, LATEX is trying
to tell you that you need to make another run. You can by-and-large ignore
these.

• LaTeX Font Warning

Another warning message, this time about fonts which LATEX couldn’t find.
The rest of the message will often say something about a replacement font that
LATEX used. You can safely ignore these, too.
3
Well, usually. Analyzing the logfile is a tough job, and LYX doesn’t always go to the right line.
There are also cases where LATEX reports the error on one line, but the actual error is earlier.
This is not unlike forgetting a closing brace in a program: You’ll get an error, but only later.

8
 2.5 LYX and LATEX Errors

• Overfull \hbox
LATEX absolutely loves to spew these out. It seems to generate at least one
of these messages for just about any document you write. They are warnings
about lines that were too long and run past the right margin. This happens if
LATEX does not find a reasonable way to break the lines (notoriously often with
typewriter font, since this does not allow for automatic break points). In many
cases, this is unnoticeable in the final output. (It can be just a point or two.)
Sometimes, however, the lines run rather visibly into the margin; something
you will not want to have in your final print.
There are several global ways to try to minimize the overfull lines. Clicking En-
able micro-typographic extensions in Document ▷ Settings ▷ Fonts might already
improve things a lot. Furthermore, LATEX code such as the following in Docu-
ment ▷ Settings ▷ Preamble usually reduces the overfull lines drastically (we use
this in the preamble of this document):
\tolerance 1414
\hbadness 1414
\emergencystretch 1.5em
\hfuzz 0.3pt
In some cases, however, you eventually have to rewrite the text to get the line
breaking right.4
In any case, you should check the respective lines, at least for the final version
of your document. Your eyes will tell you if there’s a problem with something
that’s too wide.5

• Underfull \hbox
Not quite as common as its cousin. This happens again if LATEX does not find
a reasonable break point and consequently generates too loose lines. As with
the overfull lines, you should check if this is a visible problem.

• Overfull \vbox and Underfull \vbox

Warnings about troubles breaking the page. Once again, just look at the output.
Your eyes will tell you where something has gone wrong.

• LaTeX Error: File ‘Xxxx’ not found

The file “Xxxx” isn’t installed on this system. This usually appears because
some package your document needs isn’t installed. If you didn’t touch the
preamble or didn’t use the \usepackage{} command, then one of the packages
LYX tried to load is missing. Use Help ▷ LaTeX Configuration to get a list of
packages that LYX knows about. This file is updated whenever you reconfigure
LYX (using Tools ▷ Reconfigure) and tells you which packages have been detected
4
For more information, see http://www.tex.ac.uk/FAQ-overfull.html
5
You can also enable the ‘draft’ option in Document ▷ Settings, and then LATEX will draw a black
box in the margin of lines that are overfull.

9
2 LYX and LATEX

and what they do.

If you did use the \usepackage{} command and the package in question isn’t
installed, then you’ll need to install it yourself.

• LaTeX Error: Unknown option

Error messages beginning with this are trying to tell you that you specified a
bad or undefined option to a package. Check the package’s documentation.

• Undefined control sequence

If you’ve inserted LATEX code into your document, but made a typo, you’ll get
one of these. You may have forgotten to load a package. In any case, this error
message usually means that you used an undefined command.

There are other error and warning messages. Some are self-explanatory. These are
usually LATEX messages. Others are downright cryptic. These are usually TEX error
messages, and we really have no clue what they mean or how to decipher them.
No-one does.
There’s a general sequence you should follow if you get error messages:

1. Look at the LATEX code you inserted for typos.

2. If there are no typos, check that you used the command(s) correctly.

3. If you get a bunch of error boxes piled up at the very top of the document—
and especially if you see a “Missing \begin{document}” error—it means that
there are errors in the preamble. Start debugging your preamble.

4. If you didn’t add anything to the preamble and didn’t add any LATEX code
to the document, the first suspect is your LATEX distribution itself. Check for
missing packages and install them.

5. Okay, so there are no missing packages. Did you use any of the fine-tuning op-
tions in LYX? Specifically, did you misuse any of them, like trying to manually
insert lots of Non-Breaking Spaces, Linebreaks, or Pagebreaks? Did you
try to kludge something together with these instead of using the appropriate
paragraph environment?

6. All right, you didn’t use any of the fine-tuning options, you played by the rules.
Did you try to pull a fancy maneuver? Did you do something funky inside a
table or an equation, like inserting a graphic into a table cell?

7. Do you have long sections of text where LATEX cannot find a place to break
a line? By default, LATEX is rather strict about how much extra inter-word
spacing it will add in order to break a line. Preferably, you should rework the
paragraph to avoid the problem.

10
 2.5 LYX and LATEX Errors

8. Did you go overboard with the nesting? LYX (currently) doesn’t check to make
sure you’re in the limits for nesting environments. If you nested a bunch of
environments to the 17th level, that’s the problem. (The limit in LATEX is five.)

9. Okay, you didn’t get any error messages, but your output looks awful. If you
have a table or figure that’s too wide or long for the page, you need to:
a) rescale the figure so it fits.
b) trim down the table so it fits.

10. If something else is wrong with the output, and you didn’t try to pull anything
fancy or kludge the fine-tuning options, we’re not sure what’s wrong.

If all this doesn’t help—well, then perhaps you might have found a bug in LYX. . . .

11
3 Document classes
As explained in the User’s Guide, LATEX originally offered four standard document
classes, article, report, book and letter, but individuals and organizations, most no-
tably the American Mathematical Society in the early days, have made many contri-
butions to extending the range of document classes. In this chapter we summarize the
main externally maintained classes, some of which are marked “Unavailable:” in the
pull-down Document class list in the Document ▷ Settings ▷ Document class dialog and
which you will need to install as described in the Installing New Document Classes
chapter of the Customization manual if you want to use them.

3.1 Collections
3.1.1 AMS-LATEX (American Mathematical Society)
The LYX supported document classes American Mathematical Society (AMS) in cate-
gory Articles and American Mathematical Society (AMS) in category Books are main-
tained by the Society; use of their features is described in the Math manual and
on their website http://www.ams.org/publications/authors/tex/amslatex. The
following summary was originally provided by David Johnson and updated by
Richard Kimberly Heck and the LYX Team.

The AMS LATEX layouts are set up to conform to suggested styles for mathematical
papers to be submitted to American Mathematical Society publications. The layouts
are not tailored to a specific journal, but easily can be. You should refer to the AMS
documentation for specific instructions for each journal (usually it will entail only
changing a single line in the TEX output). That documentation is available on the
Web at http://www.ams.org or by ftp at ftp://ftp.ams.org/pub/tex/amslatex/.
These layouts are appropriate, and useful, for any mathematical writing.
There are three basic AMS LATEX layouts:

• amsart: The standard AMS article format; see File ▷ Open Example ▷ Articles ▷
American Mathematical Society (AMS).

• amsbook: the standard AMS book (really, monograph) format; see File ▷ Open
Example ▷ Books ▷ American Mathematical Society (AMS).

• amsproc: the standard AMS proceedings format.

13
3 Document classes

LYX only supports the first two natively; see the Installing New Document Classes
chapter of the Customization manual if you want to use amsproc.
The layouts themselves contain only the minimum necessary to use the AMS
classes. They do not, in particular, contain any of the ‘theorem’ environments used
for setting theorems, lemmas, and the like. These are contained, instead, in the AMS
Theorems module, which is loaded by default when you select one of the AMS classes.
(It can also be used with other classes and can be removed, if you would rather use
something else.) Less commonly used environments are in the AMS Theorems (Ex-
tended) module, which must be loaded manually.
By default, theorems and the like are numbered consecutively throughout the docu-
ment, but this may be modified by loading the module Standard Theorems (Numbered
by Section) or, if you are using book (AMS), the module Standard Theorems (Numbered
by Chapter). These will number the results as n.m, where the first number refers to
the section (or chapter) and the second refers to the total number of results so far in
that section (or chapter). Many environments are also available unnumbered. These
are indicated by an asterisk at the end. If you happen to want only unnumbered
results, the module Standard Theorems (Unnumbered) provides that option.
Note that these modules do not have to be used with the AMS classes. It is per-
fectly possible to use the AMS Theorems module, and the others mentioned, with other
classes, such as Article (Standard Class), Report (Standard Class), KOMA-Script
Book, and so forth.

3.1.1.1 What these layouts provide

There is a long list of included environments provided by these layouts. In AMS-
LATEX, there is, in fact, an opportunity to define an unlimited variety of ‘theorem’
environments. However, the AMS recommends the environments that are available
in LYX.
The following environments—as well as the standard environments, such as sec-
tion, bibliography, title, author, and date—are provided by article (AMS)
and book (AMS):
Address This should be the author’s permanent address.
Current Address This should be the author’s temporary address at the time of sub-
mission, if different from the Address.
Email Author’s e-mail address
URL Author’s Web address, if desired.
Keywords Key words or phrases used to identify specific topics discussed in the
paper.
Subjectclass These refer to the AMS Subject Classifications, published and de-
scribed in Mathematical Reviews. These are also available online at the AMS
cites listed above.

14
 3.1 Collections

Thanks

Dedicatory

Translator
The following environments are provided by both the Standard Theorems and AMS
Theorems modules, in the latter case in both unnumbered and numbered versions.
These same environments are provided only in the starred versions by the Standard
Theorems (Unnumbered) module:
Theorem 1. This is typically used for the statements of major results.
Corollary. This is used for statements which follow fairly directly from previous
statements. Again, these can be major results.
Lemma 2. These are smaller results needed to prove other statements.
Proposition 3. These are less major results which (hopefully) add to the general
theory being discussed.
Conjecture 4. These are statements provided without justification, which the author
does not know how to prove, but which seem to be true (to the author, at least).
Definition. Guess what this is for. The font is different for this environment than
for the previous ones.
Example. Used for examples illustrating proven results.
Problem 5. It’s not really known what this is for. You should figure it out.
Exercise. Write a description for this one.
Remark 6. This environment is also a type of theorem, usually a lesser sort of obser-
vation.
Claim. Often used in the course of giving a proof of a larger result.

Case 1. Generally, these are used to break up long arguments, using specific in-
stances of some condition.

Case 2. The numbering scheme for cases is on its own, not together with other
numbered statements.

Proof. At the end of this environment, a QED symbol (usually a square, but it can
vary with different styles) is placed. If you want to have other environments within
this one—for example, Case environments—and have the QED symbol appear only
after them, then the other environments need to be nested within the proof environ-
ment. See the section Nesting Environments of the User’s Guide for information on
nesting.

15
3 Document classes

Fact 7. Used in a way similar to Proposition, though perhaps lower on the scale.

And these environments are provided by AMS Theorems (Extended):

Criterion. A required condition.

Algorithm. A general procedure to be used.

Axiom. This is a property or statement taken as true within the system being dis-
cussed.

Condition. Sometimes used to state a condition assumed within the present context
of discussion.

Note. Similar to a Remark.

Notation. Used for the explanation of, yes, notation.
Summary 8. Do we really need to tell you?
Conclusion. Sometimes used at the end of a long train of argument.

Assumption. Assumption

Question. Question

There are ten more Maths modules available including several offering options
ordered on (Numbered by Type . . . ).
In addition, the AMS classes automatically provide the AMS LATEX and AMS
fonts packages. They need to be available on your system in order to use these
environments.

3.1.2 Extra font sizes

The “Extra font sizes” collection provides the document classes article (with extra font
sizes), book (with extra font sizes), letter (with extra font sizes) and report (with extra font
sizes) which use the article.cls, book.cls, letter.cls and report.cls document
classes respectively but offer the additional Base Size options 8, 9, 14, 17 and 20 in
the Document ▷ Settings ▷ Fonts dialog.

3.1.3 Hebrew
The document classes Hebrew Article and Hebrew Letter use the article.cls and
letter.cls document classes to facilitate the use of Hebrew in LYX.

16
 3.1 Collections

3.1.4 Japanese (Standard Classes)

LYX included a collection of several bundles that aim to facilitate typesetting Japanese
documents. The bundles have been developed at different times, they thus support
different typesetting engines and features. This collection is the oldest one. It adjusts
the LATEX standard classes to requirements of Japanese typesetting, for horizontal and
vertical writing. The collection includes Japanese Article (Standard Class), Japanese
Article (Standard Class, vertical Writing), Japanese Book (Standard Class), Japanese
Book (Standard Class, vertical Writing), Japanese Report (Japanese Standard Class), and
Japanese Report (Standard Class, vertical Writing), which all work with “classic” en-
gines tailored for Japanese, pLATEX and upLATEX.
For the use with the more modern LuaLATEX typesetting engine, the collection
also includes dedicated classes Japanese Article (Standard Class for LuaTeX), Japanese
Article (Standard Class for LuaTeX, vertical Writing), Japanese Book (Standard Class
for LuaTeX), Japanese Book (Standard Class for LuaTeX, vertical Writing), Japanese
Report (Japanese Standard Class for LuaTeX), and Japanese Report (Japanese Standard
Class for LuaTeX, vertical Writing), provided by the luatexja LATEX package.
Templates for the LuaLATEX classes can be found in File ▷ New From Template in
the respective category (Articles, Books, or Reports).

3.1.5 Japanese (JS Bundle)

This collection includes improved versions of the classes included in Japanese (Stan-
dard Classes) (see 3.1.4). It includes Japanese Article (JS Bundle) and Japanese Book (JS
Bundle). A report class can be obtained by using Japanese Book (JS Bundle) with op-
tion report in Document ▷ Settings ▷ Document Class ▷ Class Options ▷ Custom. All these
classes work with “classic” engines tailored for Japanese, pLATEX and upLATEX.
For the use with the more modern LuaLATEX typesetting engine, the collection also
includes dedicated classes Japanese Article (JS Bundle for LuaTeX), Japanese Book (JS
Bundle for LuaTeX), and Japanese Report (JS Bundle), provided by the luatexja LATEX
package.
Templates for the LuaLATEX classes can be found in File ▷ New From Template in
the respective category (Articles, Books, or Reports).

3.1.6 Japanese (BX Bundle)

This bundle contains the document classes Japanese Article (BX Bundle), Japanese
Book (BX Bundle), and Japanese Report (BX Bundle) which provide alternative doc-
ument classes for Japanese documents. Furthermore, a class Japanese Slides (BX
Bundle) for presentation slides, is included. As opposed to the classes of the Stan-
dard Classes and JS bundles (sec. 3.1.4 and 3.1.5), which support only pLATEX and
upLATEX out of the box (and LuaLATEX only through the extra classes added by the
luatexja LATEX package), the classes of this bundle also support pdfLATEX, XeLATEX

17
3 Document classes

and LuaLATEX directly, with the aid of suitable packages that provide capability of
Japanese typesetting.

3.1.7 Japanese (JLReq Class)

This bundle draws on the jlreq class which faithfully traces the standard of Require-
ments for Japanese Text Layout set by the World Wide Web Consortium (W3C, see
https://www.w3.org/TR/jlreq/?lang=en). It can be used with LuaLATEX as well
as pLATEX and upLATEX.
LyX provides layouts for Japanese Article (JLReq Class), Japanese Book (JLReq Class),
and Japanese Report (JLReq Class) which are all derived from the jlreq LATEX class via
specific class options.
An example article document is available at File ▷ Open Example ▷ Articles ▷ Japanese
Article (JLReq Class). English documentation is available at http://mirrors.ctan.
org/macros/jptex/latex/jlreq/jlreq.pdf.

3.1.8 KOMA-Script
Original by Bernd Rellermeyer; updated by Jürgen Spitzmüller and the
LYX Team

3.1.8.1 Overview
The KOMA-Script collection of document classes is a development of the Script
classes created by Frank Neukam in the early 1990s; it was formally launched with
the addition of a letter class in 1994. Since then, a second letter class has been added.
Frank Neukam’s classes were inspired by the principles of typography and this has
been fully integrated into the design of the KOMA-Script classes.
The LYX document classes KOMA-Script Article, KOMA-Script Report, KOMA-
Script Book, and KOMA-Script Letter correspond to the LATEX document classes
scrartcl.cls, scrreprt.cls, scrbook.cls, and scrlettr.cls, resp. of the Koma-
Script family. They are replacements for the standard document classes article.cls,
report.cls, book.cls and letter.cls, resp., and fit better to European typography
conventions in a number of points.

• The base character sizes when you select a KOMA-Script class are 11pt in
KOMA-Script Article, KOMA-Script Report, and KOMA-Script Book and 12pt
in KOMA-Script Letter.

• Headings, labels of the description environment, and a number of elements of

the KOMA-Script Letter document class are set in a bold sans serif font.1 The
1
There is a big difference between the bold sans serif old cm fonts and new ec fonts, especially in
the appearance of headings. In comparison, the ec bold sans serif fonts look a bit thin. Here the
LATEX package cmsd.sty by Walter Schmidt helps to produce the “usual” appearance when
using the ec fonts.

18
 3.1 Collections

numbering of chapter headings is made in the same way as the numbering of

section headings, that is without the extra line “Chapter. . . ”. In addition, the
appearance of the headings can be modified by using a number of options (in
LYX to be entered in the field Extra Options of the dialog Layout ▷ Document).

• The layout of a KOMA-Script page follows one of two traditional typesetting

conventions based on dividing the page into strips or drawing a circle. The
default is to imagine that a page is divided horizontally and vertically into
strips and allocate strips to the margins leaving the unused strips for the text
area. You can change the sizes of the margins by changing the factor by which
the page is divided into strips; the default for an A4 page is 9 and increasing this
factor will produce increasingly narrower strips and therefore narrower margins.
Whatever the factor, two strips are allocated to the outer and bottom margins
of a two-sided document and one strip to the inner and top margins, leaving
a text area occupying around half the page. Since most two-sided documents
have a binding, this can make the inner margins appear too narrow; so you can
apply a binding correction to the page which is deducted before the size of the
strips is calculated.
The main means in the Koma-Script document classes to design the type
area are the options BCOR and DIV entered in Document ▷ Settings ▷ Document
Class ▷ Class Options ▷ Custom.
In this document, the binding correction is 7.5mm which is added in the form
BCOR7.5mm to Class options ▷ Custom dialog. To change the factor to 11, for
example, add the entry DIV=11 to the comma separated list of entries in the
Custom Class options. If you want the default value of this factor for a page size
other than A4, add the entry DIV=calc.
To use the circle method of calculating the page layout, use DIV=classic in-
stead.

• The LATEX document classes of the Koma-Script family define a number of ad-
ditional commands. Those part of it which makes sense in LYX is implemented
in corresponding paragraph types.

Detailed descriptions of the LATEX document classes of the Koma-Script family can be
found in the Koma-Script documentation scrguide (German) and scrguien (English).

3.1.8.2 KOMA-Script Article, KOMA-Script Report, and KOMA-Script Book

The document classes KOMA-Script Article, KOMA-Script Report, and KOMA-
Script Book are implemented in the layout files scrartcl.layout, scrreprt.layout,
and scrbook.layout, resp. They contain all the paragraph types of the correspond-
ing standard document classes article, report, and book, resp., partly modified, with
the exception of the LYX specific List-type, which is replaced by the new Labeling-type

19
3 Document classes

having the same functionality. Beside the Labeling-Type there is a number of new
paragraph types added. They are not part of letter (koma-script).

• Addpart, Addchap, Addsec: are equivalents to Part*, Chapter* and Section*,

resp., additionally inserting an entry in the table of contents. Addpart and
Addchap are not contained in article (koma-script).

• Addchap*, Addsec*: behave exactly as Addchap and Addsec, resp., additionally

clearing running heads. Addchap* is not contained in article (koma-script).2

• Minisec: generates a heading directly above the following paragraph in the

standard character size without affecting the structure of the document.

• Captionabove and Captionbelow are special captions which respect the different
space settings needed for captions placed above or below an element (if you
follow strict typographic rules, you might want to place table captions always
above the table). You can also use the class option tablecaptionsabove, which
will switch caption to captionabove for tables and captionbelow for figures. You
need at least Koma-Script version 2.8q to use this.

• Dictum: can be used to set a bonmot, e. g. at the beginning of a chapter. If you

use the optional argument (Insert ▷ Dictum Author), you can insert the dictum’s
author there. Dictum and author are separated by a line. You need at least
Koma-Script version 2.8q to use this. Dictum is not contained in article (koma-
script).

The following types, together with the standard types Title, Author, and Date, form
the title area of the document. They must be entered ahead of the first “ordinary”
paragraph.3 When such a type is used more than once, the latter usage overwrites the
former one, that means, for every type only the latest usage is valid. The order of the
different types however has, like Title, Author, and Date, no effect on the appearance
of the produced document.

• Subject: produces a centered paragraph above the ordinary title (Title, Author,
Date) for the subject of the document.

• Publishers: produces a centered paragraph below the ordinary title (Title, Au-
thor, Date) for the publishers’ name.

• Dedication: in report (koma-script) and book (koma-script) produces a centered

paragraph on its own page behind the title page, or in article (koma-script)
produces a centered paragraph below the ordinary title (Title, Author, Date,
Publishers) for a dedication.
2
There is also an \addpart* command in book (koma-script) and in report (koma-script), but since
this is identical to Part*, is has not been implemented in LYX.
3
The corresponding LATEX commands must appear before the \maketitle command.

20
 3.1 Collections

• Titlehead: produces a left aligned paragraph above the ordinary title (Title,
Author, Date, Subject) for a document‘s head.

• Uppertitleback: produces in a double-sided print in report (koma-script) and

book (koma-script) a left-aligned paragraph at the top of the title page‘s back
or has no effect in a single-sided print or in article (koma-script).

• Lowertitleback: produces in a double-sided print in report (koma-script) and

book (koma-script) a left-aligned paragraph at the bottom of the title page‘s
back or has no effect in a single-sided print or in article (koma-script).

• Extratitle: produces a special “dirty” page ahead of the actual document con-
taining a paragraph without special formatting.

KOMA-Script offers a wide range of Custom Class options for the Document ▷ Settings ▷
Document class dialog which you can apply to the whole document, among them

draft=true which produces a PDF with a small black box at the end any line in
which a formatting error occurs; the default setting is false

headings= which may take the values big, normal or small; the first and last adjust
the sizes of the headings to take account of page sizes where the default values
may not be suitable

numbers= which may take the values auto (the default), enddot or noenddot; the
first leaves it up to KOMA-Script to add periods after chapter, section numbers,
etc.; the second forces the addition of periods and third suppresses them

and the math options:

leqno which causes equations to be numbered on the left rather than on the right,
and

fleqn which causes equations to be left justified rather than centered.

It also provides commands to affect the output of the document independently of the
standard LATEX commands and packages; for example, if you want your captions in
bold add
\setkomafont{captionlabel}{\bfseries}
to Document ▷ Settings ▷ LATEX Preamble) and the problem is solved.
If you are writing a book, it is normal to have the preliminary pages numbered in
Roman numerals and the Chapters in this part unnumbered. If you use the Chapter*
environment, your Foreword and Preface will not appear in the Table of Contents; to
make them to appear in the Table of contents, you need to use Chapter environments
and add the TEX code
\frontmatter
at the very start of the book (not in the LATEX Preamble) and

21
3 Document classes

\mainmatter
before the first chapter of the body of the text. Alternatively, you might also use
Chapter* (TOC).
You may also want to have some unnumbered Chapter environments at the end of
the book after the Appendices, if any.4 If you use the Chapter* environment, they
will not appear in the Table of Contents; so add the TEX code
\backmatter
before the first of these headings and use the Chapter environment. These com-
mands will have no effect on the numbering in LYX, only on the PDF output where
the headings will be unnumbered and appear in the Table of Contents.
The layout files for the document classes article (koma-script), report (koma-
script), and book (koma-script) do include the file scrmacros.inc. This is thought
of as a place to define your own types. Copy scrmacros.inc in your personal layout
directory and edit the file!

3.1.8.3 The new letter class: KOMA-Script Letter (V. 2)

by Jürgen Spitzmüller
Koma-Script version 2.8 has introduced a new letter class scrlttr2 which supersedes
the now unsupported scrlettr. It has — on the LATEX side — a completely new
interface and is not compatible with the old class. Therefore, LYX supports both,
though it is recommended you use the new class.
This class covers the same functionality as letter (koma-script), and a few more.
The basic items are Address (receiver’s address, same as Letter in the old layout),
Opening, and Closing. NextAddress will start a new letter (i. e. you can write several
letters per document). New elements are sender’s E-Mail, URL, Fax, Bank and the
possibility to use a Logo (via Insert ▷ Graphics) in the header.
The biggest improvement is, though, that the letter’s layout is configurable to
meet almost any needs. This can be done via the preamble or with a special style file
(Letter Class Option, extension *.lco), that will be read in as a class option.5 Have a
look at the template in File ▷ New from Template ▷ Letters ▷ KOMA-Script Letter (V.2).
A detailed description is to be found in the Koma-Script documentation (scrguide).

3.1.8.4 Problems
Visualizing the Koma-Script document classes in LYX, the LYX internals cause some
problems.
• The chapter number of a Chapter type appears on a line of its own above the
chapter heading instead of appearing in the same line ahead of it. The cause
4
Appendices are normally “numbered” with letters.
5
The KOMA package comes with some default *.lco files. There is, for instance, a DIN.lco file
that follows german typesetting rules, or a KOMAold.lco that provides the default layout of the
old scrlettr class. The latter can be loaded with the class option KOMAold, inserted via the
Layout ▷ Document ▷ Extra Options field.

22
 3.1 Collections

for that is the LYX internal behavior for the labeltype Counter_Chapter in the
layout file.

• The headings of the types Addchap and Addsec are only put in the “true”
LATEX table of contents, but not in the LYX table of contents (Document ▷
Table of Contents).

• The paragraphs in a letter document class appear in a skip separation mode,

not indented. This is the standard behavior, no special LATEX commands are
needed for that. But in the Document ▷ Settings dialog the corresponding radio
button indicates Indent. A Skip value always has the effect that extra LATEX
commands are inserted in the document to produce the gap, which is not what
is wanted in this case.

3.1.9 Polish M. W. collection

by Tomasz Luczak
The LYX document classes Polish Article (MW Bundle), Polish Report (MW Bun-
dle) and Polish Book (MW Bundle) correspond to the LATEX document classes mwart.cls,
mwrep.cls and mwbk.cls, resp. They are replacements for the standard document
classes article.cls, report.cls and book.cls, resp., and fit better to Polish ty-
pography conventions in a number of points.
Basic differences:

• Unnumbered titles (with star, e. g. Section*) are added into table of contents,

• Additional page styles:

uheadings header with separated lines,
myheadings custom header, contents headers via commands: \markright and
\markboth,
myuheadings custom header with separated lines,
outer page number is placed on outer side of page

• Options
rmheadings serif titles — default,
sfheadings sansserif titles,
authortitle on title page first placed is author next title — default,
titleauthor on title page first placed is title next author,
withmarginpar reserve place on page for margins.

23
3 Document classes

3.1.10 Tufte Collection

The document classes Tufte Book and Tufte Handout use the tufte-book.cls and
tufte-handout.cls document classes. Detailed information about these document
classes can be found in File ▷ Open Example ▷ Books ▷ Tufte Book and File ▷ Open Ex-
ample ▷ Handouts ▷ Tufte Handout.

3.2 Articles
See also the document classes in the Collections (section 3.1).

3.2.1 Astronomy & Astrophysics

Original by Peter Sütterlin; updated by the LYX Team

3.2.1.1 Introduction

This section describes how LYX can be used to write articles for submission to the
scientific journal Astronomy & Astrophysics (aa-package) using Version 9.1 of the
document class aa.cls; information about it is available at https://www.aanda.
org/for-authors/latex-issues/texnical-background-information.
A manual comes together with the package and should be consulted before in-
stalling this document class as described in the Installing New Document Classes
section of the Customization manual.
Please note that the publisher of the journal was changed from Springer to EDP
Sciences starting January 1, 2001. That change also involved some slight changes to
the style files, namely the removal of the thesaurus command. If you have an older
version installed, please upgrade. For information about compatibility with the old
(version 4) layout, please refer to the comments in LYXDir/layouts/aapaper.layout.

3.2.1.2 Getting started

It is recommended you start from the template in the menu File ▷ New from Tem-
plate ▷ Articles ▷ Astronomy & Astrophysics. If you are not using the template, note
the following settings:

• Select Astronomy & Astrophysics in the Document ▷ Settings ▷ Document Class

dialog (OK, that one was obvious).

• Don’t change the Headings style in the Page Layout dialog: leave it set to Default.
The whole layout is done by the macros, you shouldn’t change anything.

24
 3.2 Articles

3.2.1.3 The header block

First thing to enter is the header information. It consists of seven entries, of which
one is optional. They are
• Title: [required]
• Subtitle: [optional]
• Author: [required]
• Address: [required]
• Offprints [optional]. Determines to whom correspondence and reprints are to
be sent.
• Mail [optional] Snail mail address for contacts.
• Date: [required]. Suggested format is Received: <date>; Accepted <date>
There is no need to issue the \maketitle command, this is done automatically by
LYX when the header is finished. Although the order of the single header entries
doesn’t matter it is advised to keep the above sequence, just to get the best optics
and meets the layout of the real document.
If you want to place footnotes in the header block, e. g. to state your present address,
just use the standard footnote via the menu Insert ▷ Footnote. LYX will automagically
use the term \thanks{} in that case.
Under Edit ▷ Text Style, you’ll find two insets which are relevant for the titling:
• Institute to mark corresponding author/institute pairs. The institutes are num-
bered sequentially as they appear in the Address field, so you have to put a
marker to each author.
• Email to supply an email address for fast contact.
In addition to these topics, the macros use one additional LATEX commands that has
no counterpart in LYX:
• \and to separate different names for more than one author and institute, re-
spectively.
The appropriate command has to be entered as TEX code in LYX. See the examples
in the template and in File ▷ Open Example ▷ Articles ▷ Astronomy & Astrophysics.

3.2.1.4 The abstract

The abstract should immediately follow the header block. With version 5 the abstract
environment was changed to a command, and there is now a restriction to only one
paragraph. In addition, it should contain an entry with the keywords. This is done
via the paragraph style Keywords. Refer to the example paper.

25
3 Document classes

3.2.1.5 Supported environments

The A&A paper layout supports the following environments for structuring your text:

• Standard • Description

• Section • Caption

• Subsection • Abstract

• Subsubsection • Acknowledgment

• Itemize • Bibliography

• Enumerate • LaTeX

3.2.1.6 Commands not supported by LYX

Some commands are not yet supported by the Astronomy & Astrophysics layout for
LYX. Some have already been mentioned. For the sake of completeness, they are
listed all together here:
• \and

• \authorrunning

• \object{}

• \titlerunning{}
If you want to use any of these commands, you have to enter them yourself. Do not
forget to use Insert ▷ TEX Code!

3.2.1.7 Figure and Table Floats

LYX provides support for the necessary float environments figure, figure*, table and
table*, therefore we won’t tell much about it here. Refer to the User’s Guide. Just
remember that tables should be left-aligned. For that, select the table and change
the alignment in Edit ▷ Paragraph Settings ().
There is only one special thing: the figures with a caption beside the figure. To
create such a figure, you have to do the following:
1. Create a wide figure float: Insert ▷ Float ▷ Figure, then, from within the float, use
the menu Edit ▷ Float Settings and check Span columns in the float dialog.

2. Enter your caption text.

3. Press Return to move the cursor above the caption.

4. Insert your figure

26
 3.2 Articles

5. Position the cursor after the figure and insert a horizontal fill by using the
menu: Insert ▷ Formatting ▷ Horizontal Space to open the space dialog and select
the Horizontal fill option from the Spacing context menu.

6. Switch to LATEX mode: M-c t.

7. Enter \parbox[b]{55mm}{ Do not close the brace!

8. Position the cursor behind the caption text, switch to LATEX mode and insert
the closing brace: M-c t }.

Also, refer to the figures in the file in File ▷ Open Example ▷ Articles ▷ Astronomy &
Astrophysics.

3.2.1.8 Referee layout

For submission, the paper has to be formatted in a special double-spacing layout.
For this purpose, you have to add the option referee to the Custom Class options in
the Document ▷ Settings ▷ Document Class dialog.

3.2.1.9 The example paper

The example in File ▷ Open Example ▷ Articles ▷ Astronomy & Astrophysics was written
with LYX. It is the example paper from the original macro package, aa.dem in the
aa-package, but translated to LYX using the older unstructured abstract type. Use it
for inspiration, and compare the LATEX code in aa.dem with the LYX way of writing.

3.2.2 AASTEX
by Mike Ressler

3.2.2.1 Introduction
AASTEX is a set of macros produced by the American Astronomical Society to facil-
itate electronic manuscript submission to the three journals they publish: the Astro-
physical Journal (including the Letters and Supplement), the Astronomical Journal,
and the Publications of the Astronomical Society of the Pacific. LYX has proven to
be an excellent tool for generating these documents, especially given its equation, ci-
tation, and figure handling capabilities. LYX requires version 5.0 (or higher) of these
macros; preferably 6.0, which is the version described here, or higher. Versions prior
to 5.0 are intended for use with LATEX2.09 and are fundamentally incompatible with
LYX. The AASTEX package may be downloaded from the AASTEX Web site

https://aas.org/aastex/aastex-downloads

27
3 Document classes

A complete user guide is contained in that package and you should familiarize
yourself with it thoroughly before embarking on writing a paper in LYX. LYX will
not reduce the need to figure out all the AASTEX commands, it will only reduce the
drudgery of typing everything in. It is your responsibility to ensure that the final
exported LATEX document conforms completely to the requirements of the journal to
which you are submitting your paper.

3.2.2.2 Starting a New Paper

I strongly suggest that you start with the AASTEX template file. Click on File ▷ New
from Template ▷ Articles ▷ American Astronomical Society. This will show the most
common fields found in a manuscript. Simply overwrite the existing text (including
the brackets, <>) with the correct information. Many of the AASTEX commands and
environments can be implemented directly in LYX, but some cannot. For commands
such as these, the LATEX code must be entered directly and marked as such. Such
commands are referred to as TEX code, or Evil Red Text. I tried to minimize the
amount of TEX code needed in an AASTEX document.

3.2.2.3 Finishing Your Paper

When the paper is finished to your satisfaction and previews/prints correctly, there
are a few “postprocessing” actions which need to be done before you submit it to the
journals.

1. Export your paper as a LATEX file (File ▷ Export ▷ LATEX).

2. Edit the resulting .tex file with your favorite text editor
a) remove the comment lines before the \documentclass command
b) remove the \usepackage...{fontenc} line if it appears (usually just after
\documentclass}; also remove the \secnumdepth line if it appears.
c) remove everything between (and including) the \makeatletter and \makeatother
commands, except for any commands you specifically put into the LATEX
preamble (which should appear immediately after the “User specified LATEX
commands” comment in the .tex file).

3. Run the resulting file through LATEX to make sure it still processes correctly.

4. Reread the journal requirements to make sure your filenames and formats are
correct.

5. Submit it.

28
 3.2 Articles

3.2.2.4 Comments On Specific Commands

I will not describe the detailed usage of the individual AASTEX commands: the
AASTEX User Guide (aasguide.tex) gives a good description of each. Thus it’s
probably easiest for me to go down the list as found in the guide and offer comments
where necessary. So let’s begin . . .

Things that work as expected Because they work as you might expect, I simply list
them and the section they are found in: \documentclass (2.1.1), \begin{document}
(2.2), \title (2.3), \author (2.3), \affil (2.3), \abstract (2.4), \keywords (2.5),
\section (2.7), \subsection (2.7), \subsubsection (2.7), \paragraph (2.7), \facility
(2.10), \begin{displaymath} (2.12), \begin{equation} (2.12), \begin{eqnarray}
(2.12), \begin{mathletters} (2.12), \begin{thebibliography} (2.13.1), \bibitem
(2.13.2), all the cite commands and their variations (2.13.2), the generic graph-
icx figure commands (2.14.1), \begin{table} (2.15.4), \begin{tabular} (2.15.4),
\caption (2.15.4), \label (2.15.4, amongst other places), \tablerefs (2.15.5),
\tablecomments (2.15.5), \url (2.17.4), \end{document} (2.18).
The following style options also work correctly: longabstract (2.4), preprint
(3.2.1), preprint2 (3.2.2), eqsecnum (3.3), flushrt (3.4). Simply put them in the
Options box in Layout ▷ Document.

Things that work, but require more comment The following items work, but
require a little more discussion:
• These items are reserved for use by the journal editors, but you can put them
into the LATEX preamble if you feel compelled to do so: \received, \revised,
\accepted, \ccc, \cpright (all from 2.1.3)

• These items may be placed in the LATEX preamble, and are included as blanks in
the template file: \slugcomment (2.1.4), \shorttitle (2.1.5), \shortauthors
(2.1.5)

• \email (2.3) – can only be used “standalone”, not in the middle of a paragraph.
Use TEX code if you need to embed it.

• \and (2.3) – will have extra {} after it. This should not cause an error.

• \notetoeditor (2.6) – can only be used “standalone”, not in the middle of a

paragraph. Use TEX code if you need to embed it.

• \placetable (2.8) – can’t insert a cross-reference tag, you must type the tag
name by hand

• \placefigure (2.8) – same as for \placetable

• \acknowledgements (2.9) – will have extra {} after it. This should not cause
an error.

29
3 Document classes

• \appendix (2.11) – will have extra {} after it. This should not cause an error.

• \figcaption (2.14.2) – you can insert an optional filename argument by placing

the cursor at the beginning of the text and selecting Insert ▷ Short Title. “Short
Title” inserts an optional argument of the type needed by \figcaption. Hope-
fully it will be renamed someday.

• \objectname (2.17.1) – same as \figcaption for the catalog ID optional pa-

rameter

• \dataset (2.17.1) – same as \figcaption for the catalog ID optional parameter

Things not implemented, use TEX code \eqnum (2.12), \setcounter{equation}

(2.12), Journal name abbreviations (2.13.4), \figurenum (2.14.1), \epsscale (2.14.1),
\plotone (2.14.1), \plottwo (2.14.1), \tablenum (2.15.4), \tableline (2.15.4, in-
sert it as the first element in the lefthand cell after where you want it. Don’t use
any of LYX’s rules in the table), \tablenotemark (2.15.5), \tablenotetext (2.15.5),
much of Misc (2.17, except \objectname, \dataset, \url, and \email; see above),
\singlespace (3.1), \doublespace (3.1), \onecolumn (3.2), \twocolumn (3.2)

Things that cannot be implemented . . . at least in any meaningful sort of way,

so I suggest ignoring them. They are the references environment (2.13.3), and the
deluxetable environment (2.15). If you really, really need to use deluxetable, I suggest
editing it in a separate file with a text editor, then using Insert ▷ Child Document
to include it in your LYX document. See File ▷ Open Example ▷ Articles ▷ American
Astronomical Society for an example of this.

3.2.2.5 FAQs, Tips, Tricks, and Other Ruminations

Getting LYX and AASTEX to cooperate It can be a bit tricky to get LYX to
recognize a new layout and document class. When all else fails, do this:

1. Make certain that LATEX can find AASTEX. Copy sample.tex (and perhaps
table.tex) from the AASTEX distribution into a directory completely unrelated
to LATEX or AASTEX and run LATEX on sample.tex.

2. Make certain that aastex63.layout appears in LYX’s layouts folder

3. Rerun Tools ▷ Reconfigure in LYX, then restart LYX.

4. Open a regular new file, not from a template. Does American Astronomical
Society (AASTeX V. 6.3.1) appear in the class list in Document ▷ Settings?

If you get a warning from an existing AASTEX document about not being able to
find the AASTEX layout or a message about “You should not mix title layouts with
normal ones”, things haven’t been installed correctly.

30
 3.2 Articles

LATEX error processing a table LYX, by default, attempts to center the table
caption/title. This seems to produce a bad interaction in AASTEX so you should
click somewhere in the caption/title, then select Edit ▷ Paragraph Settings, then set
the Alignment to Block. This took care of it for me.

References A couple of things:

1. I have noticed some funny spacing in the reference entries in the text. When
you enter the bibliography item data, make sure their is no space between the
last author and the parenthesis setting off the year; e. g. type Ressler(1992),
not Ressler (1992).

2. Entering the references at all is not obvious. The easiest thing is to start typing
your first reference at the end of the document, then mark it as type References.
That will put a small gray box in front of what you just typed. Click on the
box to fill in the rest of the information. For new references, go to the end of
an existing reference and press return. That will create a new line with its own
box, etc.

Including EPS files Even though AASTEX provides its own figure commands (\plotone,
for example), I much prefer LATEX’s standard figure commands (with the default
graphicx). You can insert the \plotone, etc. commands as TEX code into a Figure
Float box if you desire, but I never have much luck getting the layout right. With
the standard graphics, LYX will insert a \usepackage{graphicx} command into the
LATEX preamble and handle the figures in the standard LATEX 2ε way, interspersing
the figures in the text. I believe ApJ accepts figures exactly this way now; AJ might
still use the “stack everything at the end” technique.

Things I could have done, but didn’t There are a few “pretty” things I could have
implemented, but chose not to. For instance, I saw no point in double-spacing the
text in the LYX window, even though it is double-spaced in the paper manuscript.
Also, I chose not to make separate layouts for the preprint and preprint2 styles. Since
I assume you will spend most of your time in the plain manuscript mode anyway, I
decided not to chew up more disk space with this.

3.2.2.6 Final Caveat

Your mileage may vary. I’ve now had papers published by both ApJ and AJ that
have had 98% of the effort done in LYX; the last 2% was the LATEX post-processing
and a few cleanups. I have had no trouble with the submission process, and I’m sure
the journals were never aware that there might be a difference. So, go forth and
publish!

31
3 Document classes

3.2.3 Chess
The document class Chess uses the standard article document class together with the
package lyxskak to facilitate the description of chess games. See File ▷ Open Example ▷
Articles ▷ Chess where you will find Game 1 and Game 2.

3.2.4 Elsevier
The document class Elsevier provides support for the elsarticle LATEX class for
journals in the Elsevier publishing house. This provides the following additional
environments: Title footnote, Author footnote, Corresponding author, Address, Email
and Keywords.
A template is available in the menu File ▷ New from Template ▷ Articles ▷ Elsevier. It
has been customized with further environments and contains all the information you
may need. However, the documentation is also available from CTAN.

3.2.5 Paper
The document class Paper (Standard Class) provides an alternative to the Article
(Standard Class) document class. It provides similar functionality, but you might
prefer this layout with sans serif sections, headings, and more.

3.2.6 RevTEX4
by Amir Karger

The RevTeX (V. 4) textclass works with the American Physical Sociey’s RevTEX 4.0
(the β release of May, 1999) class.
LYX has a REVTeX (obsolete) textclass, which works with RevTEX 3.1. However,
v3.1 is basically obsolete, as it works with LATEX 2.09. That means that it doesn’t
interact very well with LYX, which requires LATEX 2ε , although it has been kludged to
work. Since RevTEX 4.0 has been designed to work much more cleanly with LATEX 2ε ,
LYX with the Revtex 4TeX (V. 4) textclass should also be pretty easy to use.
These documents are supposed to be used in addition to the RevTEX 4.0 docu-
ments, so we don’t describe any of the special RevTEX macros, and assume you’ll
know what to put in the preamble if necessary.

3.2.6.1 Installation
All you need to do is install RevTEX 4, as described in the package’s README file.
The package can be found at The RevTEX 4 Web Site http://publish.aps.org/
revtex4/. Install it somewhere that LATEX can see it. Test it by trying to LATEX a
short RevTEX 4 document in some random directory (i. e. not the directory where
you installed the class file.) Then, if you reconfigure LYX, it will find the class file
and let you use the RevTEX4 textclass.

32
 3.3 Books

Probably the easiest way to get started is either to import a RevTEX 4 document
using tex2lyx, or to use the Revtex 4 template, found in File ▷ New From Templates ▷
Articles.

3.2.6.2 Preamble Matter

Optional arguments to \documentclass, like “preprint” and “aps”, go in the Ex-
tra Options field in the Document Layout dialog, as usual. Remember that in RevTEX,
at least one optional argument is required!
Other preamble matter, like \draft etc. goes in the LATEX Preamble dialog, also as
usual.

3.2.6.3 Layouts
The layouts basically correspond to the commands in RevTEX4.0. For example, the
Email layout corresponds to \email{}. Note that (at least as of RevTEX 4.0 Beta),
the Address and Affiliation layouts are exactly equivalent, so you shouldn’t need to
use both.6

3.2.6.4 Important Notes

There are a couple of important unique aspects of RevTEX 4 which might cause bugs
that will be even more confusing in LYX.
In RevTEX, the \thanks command goes outside the \author command. The LYX
equivalent is that there is a separate Thanks layout. Do not write footnotes in the
Author layout, or weird things may happen. See the RevTEX 4 documentation for
more details.
Also, the Author Email, Author URL, and Thanks layouts must be placed in between
the Author layout and the corresponding Address (or equivalent Affiliation) layout. If
you put the Thanks after the Address, the LATEX won’t compile.

3.2.7 Springer Journals

All the svj* classes were replaced with a completely new class, sn-jnl.cls. Please find in-
formation at https://www.springernature.com/gp/authors/campaigns/latex-author-support.
Native LYX support is not available yet.

3.3 Books
See also the document classes in the Collections (section 3.1).
6
In case you’re curious, both were included so that tex2lyx would be able to translate both
\address and \affiliation.

33
3 Document classes

3.3.1 Memoir
By Jürgen Spitzmüller

3.3.1.1 Overview
Memoir is a very powerful and constantly evolving class. It has been designed with
regard to fictional and non-fictional literature. Its aim is to let the user have maximum
control over the typesetting of his document. Memoir is based on the standard book
class, but it can also emulate the article class (see below).
Peter Wilson, the developer of Memoir, is known as the author of lots of useful
packages in the LATEX world. Most of them have been merged with Memoir. There-
fore, it is much easier to layout the table of contents, appendices, chapter designs
and such. LYX, though, does not support all of these goodies natively. Some of them
might be added to forthcoming releases7 , lots will probably never be supported, due
to the limitations of LYX’s framework. Of course you can still use all features with
the help of some native LATEX commands (TEX code8 ). In this section, we can only
list those features that are natively supported by LYX. For detailed descriptions (and
for the rest of features) we recommend you have a look at the detailed manual of the
Memoir class9 , which is not only a user guide for the class, but also both a compre-
hensive description on good typesetting and a superb example for good typesetting
itself.

3.3.1.2 Basic features and restrictions

Memoir supports basically all features of the standard book classes. There are, how-
ever, some differences, as follows:
Font sizes: Memoir has a broader range of font sizes: 9, 10, 11, 12, 14, 17

Page style: The fancy page style is not supported, due to a command clash between
Memoir and the fancyhdr package (they both define a command with the same
name, which confuses LATEX). Instead, Memoir comes with a number of its own
page styles (see Document ▷ Settings ▷ Page Style). If you want to use these for
the chapter pages, you have to use the command \chapterstyle in the main
text or in preamble (e. g. \chapterstyle{companion}).

Sectioning: Sectionings (chapter, section, subsection etc.) come with an optional

argument in the standard classes. With this, you can specify an alternative
version of the title for the table of contents and the headers (for instance, if
the title is too long). In LYX, you can do this via Insert ▷ Short Title at the
beginning of a chapter/section. Memoir features a second optional argument
and thus separates the table of contents from the header. You can define three
7
You are invited to send suggestions to [email protected].
8
Cf. section 2.3 for details.
9
Cf. CTAN:/macros/latex/memoir/memman.pdf.

34
 3.3 Books

variants of a title with this: one for the main text, one for the table of contents,
and one for the headers. LYX makes these available in form of specific Short
Title variants in the Insert menu.

TOC/LOT/LOF: In the standard classes (and in many other classes), the table of
contents, the list of figures and the list of table start a new page automatically.
Memoir does not follow this route. You have to insert a page break yourself, if
you want to have one.

Titlepage: For some unknown reason, Memoir uses pagination on the title page (in
the standard classes, title pages are “empty”). If you want an empty title page,
type \aliaspagestyle{title}{empty} in the preamble.

Article: With the class option article (to be inserted in Document ▷ Settings ▷ Class
Settings ▷ Custom Options), you can emulate article style. That is, counters
(footnotes, figures, tables etc.) will not be reset on new chapters, chapters
don’t start a new page (but are—in contrary to “real” article classes—still
allowed), parts, though, use their own page, as in book.

Oldfontcommands: By default, Memoir does not allow the use of the deprecated font
commands, which have been used in the old LATEX version 2.09 (e. g. \rm, \it).
It produces an error and stops LATEX whenever such a command appears. The
class option oldfontcommands reallows the commands and spits out warnings
instead (which does at least not stop LATEX). Since a lot of packages and
particularly BibTEX style files are still using those commands, we have decided
to use this option by default.

3.3.1.3 Extra features

We will only describe the features supported by LYX (which is not much currently).
Please consult the Memoir manual10 for details.

Abstract: You may wonder why an abstract is an extra feature. Well, it is in book
class. Usually books don’t have abstracts. Memoir, however, has. You can use
it wherever and how often you like.

Chapterprecis: You may know this older typesetting style: The contents of a chapter
are summarized below the title and also in the table of contents (e. g. Our hero
arrives in Troia; he loses some friends; he finds others). Chapterprecis does
exactly this. It is therefore only sensible below a chapter.

Epigraph: An epigraph is a smart slogan or motto at the beginning of a chapter. The

epigraph environment provides an elegant way of typesetting such a motto. The
motto itself (text) and its (optional) author (source) are divided by a short line.
The author (source) can be inserted via Insert ▷ Epigraph Source.
10
Cf. CTAN:/macros/latex/memoir/memman.pdf.

35
3 Document classes

Poemtitle: Memoir has lots of possibilities to typeset poetry (up to very complex
figurative poems). LYX can only support a few of them. One is poemtitle, which
is a centered title for poems, which will also be added to the table of contents
(verse is the standard environment for poems. Memoir has some enhanced
versions of verse, but you need to use TEX code, because they have to be
nested inside regular verse environments, which is not possible with LYX).

Poemtitle*: Same as poemtitle, but it adds no entry to the table of contents.

3.3.2 Recipe Book

The document class Recipe Book uses the KOMA-Script Book document class but
adds two environments:

Recipe a numbered section environment at the Subsubsection level which generates

a bold centered heading above a double horizontal rule

Ingredients a Description environment where Ingredients are what are being

described and the environment ends with a horizontal rule.

File ▷ Open Example ▷ Books ▷ Recipe Book illustrates its use.

The class is designed for typesetting one or two recipes per page. The hyperlinked
table of contents (ToC) and page numbers make browsing recipes convenient.

3.4 Curricula vitae

3.4.1 Europass (2013)
The document class Europass (2013) provides the europasscv.cls document class,
an unofficial implementation of the ‘Europass CV’ recommended by the European
Commission in 2013. File ▷ Open Example ▷ Curricula Vitae ▷ Europass (2013) offers
guidance on its use. Its documentation is available from CTAN.

3.4.2 Europe CV
The document class Europe CV provides the europecv.cls document class, an un-
official implementation of the “Europass CV” recommended by the European Com-
mission in 2002. File ▷ Open Example ▷ Curricula Vitae ▷ Europe CV offers guidance on
its use. Its documentation is available from CTAN.

3.4.3 Modern CV
The document class Modern CV provides the moderncv.cls document class. This al-
lows the creation of customizable CVs. File ▷ Open Example ▷ Curricula Vitae ▷ Modern
CV offers guidance on its use. Its documentation is available from CTAN.

36
 3.5 Letters

3.4.4 Simple CV
The document class Simple CV provides the simplecv.cls document class, originally
developed for use with LYX. File ▷ Open Example ▷ Curricula Vitae ▷ Simple CV offers
guidance on its use. Its documentation is available from CTAN

3.5 Letters
See also the KOMA-Script Letter (V. 2) (section 3.1.8.3), the Letter (Standard Class
with Extra Font Sizes) (section 3.1.2) and the Hebrew Letter (section 3.1.3) document
classes .

3.5.1 DIN-Brief
The document class DIN-Brief provides support for the dinbrief.cls LATEX class
for writing letters according to the standards of the German Standards Institute
(Deutsches Institut für Normung, DIN). The file in the menu File ▷ New from Tem-
plate ▷ Letters ▷ DIN-Brief offers guidance on its use. The documentation is available
from CTAN.

3.5.2 French letter (frletter)

The document class French letter (frletter) provides support for the frletter.cls
LATEX class for writing letters according to French conventions. The file in the menu
File ▷ New from Template ▷ Letters ▷ French letter (frletter) offers guidance on its use.

3.5.3 French letter (lettre)

The document class French letter (lettre) provides support for lettre.cls, another
LATEX class for writing letters, but also faxes and envelopes, in French. The file in
the menu File ▷ New from Template ▷ Letters ▷ French letter (lettre) offers guidance on
its use. The documentation is available from CTAN.

3.5.4 G-Brief (V. 2)

The document class G-Brief (V. 2) provides support for the g-brief2.cls LATEX class
for writing letters in German. The file in the menu File ▷ New from Template ▷ Letters ▷
G-Brief (V. 2) offers guidance on its use. The documentation is available from CTAN.

37
3 Document classes

3.6 Presentations
3.6.1 Beamer
The document class Beamer uses the beamer.cls LATEX class for creating presenta-
tions. The file in the menu File ▷ New from Template ▷ Presentations ▷ Beamer or Help ▷
Specific Manuals ▷ Beamer Presentations offers guidance on its use. The documentation
is available from CTAN.

3.6.2 FoilTEX
Original by Allan Rae; updated by the LYX Team

3.6.2.1 Introduction
The document class FoilTEX uses the foils.cls document class to make slides for
overhead projectors. There are two document classes that can do this: the Slides
document class (section 3.6.5) and the FoilTEX slides class. As of 2023 the former
has continued to be maintained whereas FoilTEX has not been maintained since 2008.
This section documents the latter. If your machine doesn’t have the FoilTEX document
class installed, you’ll probably have to use the Slides document class. If you want to
install the foils.cls document class, it is available from CTAN. You should also
read the Installing New Document Classes chapter of the Customization manual.

3.6.2.2 Getting Started

Obviously, to use this document class, you need to select FoilTeX from the Class entry
in the Document Layout dialog. There are some settings in the Document Layout dialog
that you should know about that are specific to this class:

• Don’t change the options Sides and Columns on the Document Layout dialog.
They’re ignored by the foils class.

• The default font size is 20 pt with the other options being 17 pt, 25 pt and 30 pt.

• The default font is sans serif but all math equations are still typeset in the usual
roman font.

• FoilTEX supports A4 and Letter paper sizes as well as a special size for working
with 35 mm slides. It doesn’t support A5, B5, legal or executive paper sizes.

• Don’t bother changing the Float Placement settings because they are ignored
anyway. All floats appear where they are defined in the text.

• The Pagestyle setting behaves a bit differently for this class. FoilTEX provides
extensive footer and header capabilities including a user-defined logo. See sec-
tion 3.6.2.4 for more details. The title page is treated differently to all other

38
 3.6 Presentations

pages in the document and is always unnumbered and always has the logo cen-
tered at the bottom of the page (if one is defined). The possible page style
choices and what they do are as follows:
empty The final output contains no page numbers, or other headers or
footers (except footnotes of course).
plain The final output contains page numbers centered at the bottom
of the page. No other headings or footers (other than footnotes).
foilheadings Page numbers in lower right corner. Additional headers and
footers are also shown. This is also the default.
fancy Gives you access to the fancyheadings package although its use
with FoilTEX is discouraged by the writer of the FoilTEX package
because of some potential page layout clashes.

Extra Options The following options may be used in the extra class options in the
Document ▷ Settings dialog.

35mmSlide This sets up the page layout for 7.33 in by 11 in paper, which is about
the same aspect ratio as a 35 mm slide, making it a bit easier to work
with this medium.

headrule Places a rule across the page below the header on every page except
the title page.

footrule Places a rule across the page above the footer on every page except the
title page.

dvips This is automatically set each time you create a new foils document.
This option tells FoilTEX to use the dvips driver to rotate those pages
that are set as landscape foils.

landscape Simply changes the page dimensions to those of a landscape page but
doesn’t do any rotation. Thus if you use this option you need to use an
external program to rotate each page or feed your paper through your
printer as landscape. Note that this option effectively reverses the roles
of the Foilhead and Rotatefoilhead environments (don’t worry these are
described in the next section).

leqno Equation numbers on the left.

fleqn Flush-left equations.

39
3 Document classes

3.6.2.3 Supported Environments

Most of the environments commonly supported in other classes are also supported
by the FoilTEX class. There are several additional environments provided by FoilTEX
as well as a couple added by LYX. The following environments are shared with other
classes:

• Standard • Quotation

• Itemize • Title

• Enumerate • Author

• Description • Date

• List • Abstract

• LYX-Code • Bibliography

• Verse • Address

• Quote • RightAddress

That is, all the major environments apart from the sectioning environments. Since
foils are essentially self-contained sections, with a title and body, FoilTEX provides
specific commands for starting new foils and these are:

• Foilhead

• Rotatefoilhead

LYX also provides slightly modified versions of these two environments called:

• ShortFoilhead

• ShortRotatefoilhead

and the differences will be explained in the next section.

Since foils are often used in presenting ideas or new theorems and such FoilTEX also
provides a comprehensive box of goodies for presenting them:

• Theorem • Theorem*
• Lemma • Lemma*
• Corollary • Corollary*
• Proposition
• Proposition*
• Definition
• Definition*
• Proof

40
 3.6 Presentations

The starred versions are unnumbered while the unstarred versions are numbered.
There are also two list environments added by LYX and these are:

• TickList

• CrossList

FoilTEX provides some powerful header and footer capabilities that are best set in
the preamble although they may be set at any point in a document. If you want to
change these settings in your document the best place to do so is at the very top of
a foil, i. e. straight after the foilhead.
For this purpose, the following command styles are provided [Martin Vermeer]:

• My Logo • Right Header

• Restriction • Left Header
• Right Footer

There are also a few commands provided by FoilTEX that aren’t directly supported
by LYX but I’ll tell you what they do and how to use them in section 3.6.2.5.

3.6.2.4 Building a Set of Foils

This section will give a simple introduction to using the different environments to
build a set of foils. If you want to see an example set of foils, take a look at File ▷
Open Example ▷ Presentations ▷ Foils.

Give It a Title Page Unlike other classes that provide Title, Author, Date and
Abstract environments, FoilTeX creates the title on a page of its own. If you leave
out the Date environment LATEX will substitute the current date (every time you
regenerate the output).

Start a New Foil As I mentioned earlier, there are four ways of starting a new foil.
For portrait foils you should use Foilhead or ShortFoilhead. The difference between
these two environments is the amount of space between the title of the foil (the
foilhead) and the body of the foil.
Landscape foils are generated using the Rotatefoilhead and ShortRotatefoilhead en-
vironments. Again the only difference is the spacing between foilhead and body.
Both of the short versions have 0.5 inches less separation between the foilhead and
the body.
One problem with the support for landscape foils is the requirement that you have
to use the dvips driver to generate the PostScript output otherwise the foils won’t
be rotated. It is possible to get landscape foils even if you haven’t got the dvips
driver provided you can feed your foils sideways through your printer ;-)

41
3 Document classes

Theorems, Lemmas, Proofs and more You can’t have two of the same type of
these environments directly following each other. If you use a normal paragraph
break, , you will just be extending the previous environment as if you had merged
the two environments together. Rather than that, you need to insert a so-called
separator. Please refer to the section entitled Separate Nestings in the User’s Guide.

Lists You get all the commonly supported list styles found in other classes as well
as two new ones. I’ll only describe the new ones here. If you want to find out more
about the other list environments check out the User’s Guide. If you intend to use
itemized lists you might also want to read about the Itemize Bullet Selection dialog
described above in section 6.
The two new list styles, TickList and CrossList, are designed to make it easier for
you to create lists of do’s and don’ts or right and wrong by providing dedicated
environments that use a tick or a cross as the label of the list. These lists are in fact
dedicated variants of the Itemize environment. They do however require that you
have the psnfss packages installed.

Figures and Tables FoilTEX redefines the floating tables and figures so that they
appear exactly where they are in the text rather than pushing them to the top of
the page or to some user specified location. In fact if you change the float placement
settings they are simply ignored.

Page Headers and Footers My Logo and Restriction are two commands used to
control the left-footer text string. The first is meant to allow you to include a graphic
logo on your foils and defaults to “-Typeset by FoilTEX-”. While the second is meant
to provide a classification for the audience, e. g. Confidential. It is empty by default.
The remaining page corners can be filled by Right Footer (which defaults to page
numbers), Right Header (top right) and Left Header (top left).

3.6.2.5 Unsupported FoilTEX Goodies

All the commands mentioned below need to be set in a LATEX environment or as TEX
within another environment.

Lengths All lengths are adjusted using the \setlength{lengthname}{newlength}

command. Where lengthname should be replaced by the name given to the length
you want to change and newlength is the length value. All lengths should be specified
in units of length such as inches (in), millimeters (mm) or points (pt) or relative to
some document or font-based length such as \textwidth.
It’s possible to change the spacing between a foilhead and the body of the foil by ad-
justing the length specified by \foilheadskip. For example, to make all foilheads 0.5
in closer to their bodies put the following in the preamble: \setlength{\foilheadskip}{-0.5in}
The spacings around floats can be adjusted by setting these lengths:

42
 3.6 Presentations

\abovefloatskip Separation between the text and the top of the float
\abovecaptionskip Separation between the float and the caption
\belowcaptionskip Separation between the caption and the following text
\captionwidth You can make the captions narrower than the surrounding
text by adjusting this length. Best done relative to \textwidth.
There are also several title page related lengths that you may find useful if you have
a long title or several authors:
\abovetitleskip Separation from headers to Title
\titleauthorskip between Title and Author environments
\authorauthorskip between multiple Author lines
\authordateskip between the Author and the Date
\dateabstractskip between the Date and the Abstract
The last length related command affects all the list environments. If you place
\zerolistvertdimens inside a list environment then all the vertical spacing be-
tween the list items is removed. Note that this is a command not a length so it
doesn’t require \setlength like the stuff mentioned above.

Headers and Footers The \LogoOn and \LogoOff commands control whether the
logo in the MyLogo definition appear on a given page. If you put \LogoOff in the
preamble then none of the foils will have the logo on them. If you don’t want the
logo on a particular page place the \LogoOff directly after the foilhead of that page
and the \LogoOn directly after the next foilhead.
If you decide to use the fancy page style setting in the Document Layout dialog
you should probably add \let\headwidth\textwidth to your preamble so headers
and footers on landscape pages are correctly placed when rotated. This is due to
some clashes between the page layouts provided by the fancyheadings package and
the FoilTeX class.

3.6.3 Powerdot
The document class Powerdot uses the powerdot.cls LATEX class for creating pre-
sentations. File ▷ Open Example ▷ Presentations ▷ Powerdot offers guidance on its use.
The documentation is available from CTAN.

3.6.4 Seminar
The document class Seminar uses the seminar.cls document class for creating pre-
sentations. File ▷ Open Example ▷ Presentations ▷ Seminar offers guidance on its use.
The documentation is available from CTAN.

43
3 Document classes

3.6.5 Slides [aka SliTEX]

Original by John Weiss; updated by the LYX Team

3.6.5.1 Introduction
This section describes how to use LYX to make slides for overhead projectors. There
are two document classes that can do this: the Slides document class and the FoilTEX
document class. This section documents the former. If you’re looking for the docu-
mentation for FoilTEX, check out section 3.6.2. As of 2023 Slides has continued to be
maintained whereas FoilTEX has not been maintained since 2008.

3.6.5.2 Getting Started

Obviously, to use this document class, you need to select “Slides” from the class list
in the Document ▷ Settings dialog. There are some other special things you should
know about this class:

• Don’t bother changing the options Sides and Columns. They’re not supported
by the Slides class, anyways.

• The option Page style behaves a bit differently for this class. The possible
choices and what they do are as follows:
plain The final output contains page numbers in the lower right corner.
headings Like plain, but also prints out any time markers you’ve put in. This
is the default.
empty The final output contains no page numbers, time markers, or alignment
markers.

• The Slides class has an extra option: clock. To use it, put “clock” in the extra
class options.
Using this options allows you to add time markers to Notes. See section 3.6.5.4
for more details.

You can also use the template file to automatically set up a document to use the
slides class using File ▷ New from Template ▷ Presentations ▷ Slides to open your new
document. The template file also contains some examples of the special paragraph
environments used by this class. I’ll describe those next.

3.6.5.3 Paragraph Environments

Supported Environments The first thing you’ll notice when you start up a new
Slides document is the font size and type: it’s the equivalent of the size “Largest” in
the Sans Serif font. This is also what’s used in the output. Think of this as a “visual
cue” to remind you that this is a slide. Your final slides will use a larger font; ergo,

44
 3.6 Presentations

you’ll have less space. Of course, the larger default screen font isn’t WYSIWYG,
only a reminder.
The next thing that becomes obvious is the changes to the paragraph environment
pull-down box [at the far-left end of the toolbar]. Most of the paragraph environments
you’re used to seeing are missing. There are also five new ones. That’s because the
Slides class itself only supports certain paragraph environments:

• Standard • Quotation

• Itemize • Quote

• Enumerate • Verse

• Description • Caption

• List • LYX-Code

All of the other standard environments, including the section-heading environ-

ments, aren’t used in the Slides class.
On the other hand, you’ll notice the following new environments:

• Slide • InvisibleText
• Overlay • VisibleText
• Note

These five are kind of quirky, due to a “feature” in LYX. You see, LYX doesn’t
permit you to nest any other paragraph environment into an empty environment.
Now, that’s fine and dandy, but it means that you wouldn’t be able to start a slide
with anything except plain text. To deal with this, I’ve performed a little “LATEX
magic.”

Quirks of the New Environments All five of the new paragraph environments are
somewhat quirky due to inherent limitations in the current version of LYX. As I just
mentioned, LYX forbids environments that begin with another environment. To get
around this, the Slide environment isn’t a paragraph environment as described in the
User’s Guide.
You should consider Slide, Overlay, and Note to be “pseudo-environments.” They
look like a section heading or a “Caption,” but really begin a [and, if necessary, end
the previous] paragraph environment. Likewise, treat InvisibleText and VisibleText as
“pseudo-commands.” These two perform some action.
A common feature of all five environments, Slide, Overlay, Note, InvisibleText and
VisibleText, is a rather long-ish label. The text following this label — ordinarily the
contents of the paragraph environment — is utterly irrelevant for Slide, Overlay, Note,
InvisibleText and VisibleText. LYX completely ignores it. In fact, you can leave these
five environments completely empty.

45
3 Document classes

While you don’t have to put any text after the rather long-ish label, you might
want to. This could be a short description of the contents of the Slide, for example.
In that case, enter your descriptive comment and hit Return as you normally would.

3.6.5.4 Making a Presentation with Slide, Overlay and Note

Using the Slide Environment If you’re expecting this section to teach you how to
actually make a presentation, you’ll be sorely disappointed. Naturally, I’ll describe
all of the ways the Slides class can assist you in preparing the materials for a presen-
tation. Filling in the contents, however, is up to you. [Then again, that is the LYX
philosophy.]
Choosing the Slide environment [in the manner described in section 3.6.5.3] tells
LYX to begin a new slide [duh]. The label for this environment/“pseudo-command”
is an “ASCII line,” in cool blue, followed by the label, “NewSlide:”. Any text or
paragraph environments that follow this one go on the new slide. It’s that simple.
Slides are probably the only time you’ll need to forcibly end pages in LYX (this can
be specified in the Paragraph Layout dialog). In fact, you’ll want to, once you finish
entering the contents of one slide. If you’ve entered more text than can physically
fit on a slide, the extra overflows onto a new slide. I don’t recommend doing this,
however, since the overflow slide won’t have any page number on it. Furthermore, it
may interfere with any Overlay you’ve made to accompany the oversized Slide.
The Overlay and Note environments work the same way as the Slide environ-
ment. They both create an “ASCII line” followed by a label [“NewOverlay:” and
“NewNote:”, respectively]. The color is a stunning magenta instead of blue, and the
“ASCII line” will look different, in style and in length. The label fonts of all three
also differ from one another.
As with a Slide, if the contents of a Note or Overlay exceed the physical size of a
slide or sheet of paper, the extra will overflow onto a new sheet. Again, you should
avoid this. It defeats the whole purpose of Notes and Overlays.

Using Overlay with Slide The idea behind an Overlay is a slide that sits atop
another slide. Perhaps you wish to discuss a figure on the main Slide before displaying
the text associated with it. One way to accomplish this is tape a flap of dark paper
over the part of the Slide you want to display later. This method fails, however, if
you wish to overlap one graph with another, for example. You would then have to
fumble while speaking to align the two separate, overlapping Slides to align the two
graphs. The use of an Overlay environment in both cases makes life much easier.
Each Overlay receives the page number of its “parent” Slide, appended by “-a”.11
Clearly, you want the contents of both the Slide and the Overlay to each fit on a
single physical slide! You should probably consider an Overlay as “part of” a Slide.
Indeed, the LYX slides class provides a visual cue for this: the label at the start of
11
Presumably, mutliple Overlays would have “-a”, “-b”, “-c”, etc. appended to the page number of
the parent Slide.

46
 3.6 Presentations

an Overlay is shorter than that at the start of a Slide. Lastly, when you generate
printable output, you’ll find alignment markers in all four corners of both the Overlay
page and its parent Slide. These will assist you in lining up the two physical slides.
The major problem in overlaying two slides is aligning the contents of the two
transparencies. How much space should you leave for that graph on the second slide?
Worse still, what if you want a graph and a sentence on second slide, but there is
text on the main transparency that goes in between them? You could try and insert
vertical space of the right size. The better way is to use InvisibleText and VisibleText.
As their names imply, InvisibleText and VisibleText are two command-like para-
graph environments that make all subsequent text invisible and visible, respectively.
Note from section 3.6.5.3 that you don’t place anything into these two environments,
however. When you create an InvisibleText, it inserts a centered, sky-blue label into
the page reading “<Invisible Text Follows>”. For paragraphs following this label, the
parts of the Slide [or Overlay; it doesn’t matter which] where they would be contain
instead blank space.
For VisibleText, the corresponding centered label is “<Visible Text Follows>” in
blazing green. Paragraphs following this label behave normally. Note that the be-
ginning of a new Slide, Overlay, or Note automatically shuts off an InvisibleText. It’s
therefore not necessary to use VisibleText at the end of a Slide.
By now, it should be obvious how to create overlay transparencies using the proper
combination of InvisibleText and VisibleText on a Slide and Overlay:
1. Create a Slide, including everything that will appear on it, whether on the main
slide or on the Overlay.

2. Before each figure or paragraph that will appear only on the Overlay, insert an
InvisibleText environment. If necessary, insert a VisibleText environment after
the Overlay-only text.

3. Start an Overlay immediately following the Slide.

4. Copy the contents of this Slide into the Overlay.

5. Within the Overlay, change all of the InvisibleText lines to VisibleText and vice-
versa.
That’s it. You’ve just made an Overlay.
There’s one problem with the way I’ve designed the LYX slides class: you can’t
make text in the middle of a paragraph invisible, nor make text in the middle of an
invisible paragraph visible again. To accomplish this feat, you’ll need to use some
inlined LATEX codes.12
12
The commands of interest are:
• {\invisible ... }
• {\visible ... }
. . . and need to be marked as TEX. The text whose “visibility” you wish to change goes in

47
3 Document classes

Using Note with Slide Like an Overlay, a Note is associated with a “parent” Slide.
Here, too, the LYX slides class provides visual cues. The label for a Note is shorter
than that of a Slide [yet longer than that of an Overlay] and, like the label of an
Overlay is shockingly magenta. Additionally, the printed Note has the page number
of its “parent” Slide, appended by “-1”, “-2”, “-3”, etc. You can have multiple Notes
associated with a single Slide, and, as with Slide and Overlay, you’ll probably want to
break up long Notes so that they fit on a single sheet of paper.
The purpose of a Note is obvious: it contains anything additional you might want
to say about a Slide. It could also be used as a sheet of reminders for a particular Slide.
In the case of the latter, you might want to make use of time markers. Currently,
the LYX slides class has no “native” support for time markers, a SliTEX feature. So,
you’ll have to resort to using the LATEX codes.
To use time markers, you’ll need to specify the extra class option “clock” [see
section 3.6.5.2]. This option turns on timing marks, which will appear in the lower-
left-hand corner of every Note you generate. To set what appears in the time marker,
you use the LATEX commands “\settime{}” and “\addtime{}”. The arguments of
both commands are time measured in seconds. “\settime{}” sets the time marker
to a given time. “\addtime{}” increments the time marker by the specified amount.
Using time markers and Notes in this fashion, you can remind yourself how much
time to spend on a particular Slide.
There’s one last feature to describe. Clearly, you’d like to print out all of your
Slides and Overlays on transparencies while printing all of your Notes on plain paper.
However, a Note must follow the Slide with which it is associated. What’s a person
to do?
Luckily, there are two LATEX commands that allow you to select what to print
out. Both must be placed into the preamble of your document. The command
“\onlyslides{\slides}” will cause the output to contain only the Slides and Over-
lays. Correspondingly, the command “\onlynotes{\notes}” prevents the output
of anything but Notes. I’d advise placing both commands in the preamble and ini-
tially comment both out. You can then preview your entire presentation as you
write. When you’re done writing, you can then uncomment one of the two to
select what you want to print. I like to uncomment “\onlyslides{\slides}” ,
print to a file with “-slides” in its name, comment it back out, then uncomment
“\onlynotes{\notes}” and print to a “*-notes.ps” file. I can then send either file
to a printer, loading transparencies or plain paper as appropriate.
You can also provide other arguments to the “\onlyslides{}” and “\onlynotes{}”
commands. See a good LATEX book for details.

3.6.5.5 The slides Class Template File

I have also provided a template file with the slides class. To use it, begin your
new presentation with File ▷ New from Template ▷ Presentations ▷ Slides. Your new LYX
between the brackets [and after the \invisible or \visible command]. If you don’t know how
to mark text as TEX, see the appropriate section of the User’s Guide.

48
 3.7 Reports

presentation file will contain an example Slide – Overlay – Note triplet. The Slide and
Overlay additionally contain an example of the use of InvisibleText and VisibleText.
Lastly, the preamble will contain:

% Uncomment to print out only slides and overlays

%
%\onlyslides{\slides}

% Uncomment to print out only notes

%
%\onlynotes{\notes}

One final thing: I created this class to support the LATEX 2ε “SliTEX emulation”
class, one of the built-in LATEX 2ε classes. Neither I nor the rest of the LYX Team
endorse or oppose the use of this built-in slide class. It’s here if you want it or
need it. There exist other LATEX 2ε classes for creating presentations, such Foils
(see section 3.6.2) or Seminar (see section 3.6.4). Try them out to see what sort of
alternative they provide.

3.7 Reports
3.7.1 report
Report classes are sort of a hybrid between book and article classes: like book classes,
they provide parts, chapters and sections but does not provide frontmatter, main-
matter, and backmatter; like article classes, they provide abstract paragraph styles
and are one-sided by default. Also, they do not start a new chapter on the right hand
page (even in two-side mode).
All externally maintained report document classes that are officially supported by
LYX are described in the Collections (section 3.1):
• For Japanese Report (Standard Class, vertical Writing) and Japanese Report (Stan-
dard Class), see section 3.1.4.

• For KOMA-Script Report, see section 3.1.8.

• For Report (Standard Class with Extra Font Sizes), see section 3.1.2.

• For Polish Report (MW Bundle), see section 3.1.9.

3.8 Scripts
In the Scripts category, we assemble document classes that help to write drama or
movie scripts. The category is also open for other scripts, such as lecture scripts, for
which no classes are officially supported yet by LYX though.

49
3 Document classes

3.8.1 Broadway
by Garst Reese

3.8.1.1 Introduction
Broadway is for writing plays. The format is more decorative than Hollywood (see
sec. 3.8.2), and much less standardized. This format should be suitable for workshops.

3.8.1.2 Special problems

The same as in Hollywood (see section 3.8.2.2).

3.8.1.3 Special features

Insert the Speaker names as labels then cross-reference the label to insert the name.
The cross-reference dialog will show the current cast of characters.

3.8.1.4 Paper size and Margins

USLetter, left 1.6in, right 0.75in, top 0.5in, bottom 0.75in

3.8.1.5 Environments
The following environments are available. You can use broadway.bind to get the
bind keys shown at the right.
• Standard
You should not have to use this, but it is here for anything that does not fit
otherwise.

• Narrative M-z n
Used to describe stage setting and the action. First use of speaker names in all
CAPs.

• ACT M-z a
Automatically numbered. On screen it will be arabic, but will print as Roman.

• ACT* M-z S at
Subtitle for ACT. It is just centered text.

• SCENE M-z S-S

Not automatically numbered. You supply the number. This is because I
couldn’t figure out how.

• AT_RISE: M-z S-R

A special case of Narrative to describe the setting and action as the curtain
rises.

50
 3.8 Scripts

• Speaker M-z s
The speaker’s (actor’s) title, centered in all CAPS.
• Parenthetical M-z p
Instructions to the speaker. The parentheses are automatically inserted. The (
will appear on screen, but both will be in the printed play. This environment
is only used within Dialogue.
• Dialogue M-z d
What the Speaker says.
• CURTAIN M-z S-C
The curtain comes down.
• Title M-z S-T
• Author M-z S-A
• Right_Address M-z r
Hello there.

3.8.2 Hollywood (Hollywood spec scripts)

by Garst Reese

3.8.2.1 Introduction
Getting the format of a Hollywood script right is a “rite of passage.” It is designed to
make the readers focus on content and to be easy and familiar for the actors to read.
Each page of a script should be one minute of film. Nothing goes in a script that you
cannot see or hear on screen. The courier 12 pt font should be used throughout. No
italics.

3.8.2.2 Special problems

Speakers’ lines should never break in mid-sentence. If a speaker’s lines continue over
a page break, repeat the Speaker title followed by (Cont’d).

3.8.2.3 Special features

Insert the Speaker names as labels then cross-reference the label to insert the name.
The cross-reference dialog will show the current cast of characters. You can use this
to insert the speaker name in narratives also.

3.8.2.4 Paper size and Margins

USLetter, left 1.6in, right 0.75in, top 0.5in, bottom 0.75in

51
3 Document classes

3.8.2.5 Environments
The following environments are available. You can use hollywood.bind to get the
bind keys shown at the right.
• Standard
Used where nothing else works. Try to avoid it.
• FADE_IN: M-z S-I
Usually followed by something like “on Sally waking up.”
• INT: M-z i
Introduces a new INTERIOR camera set-up. Always followed by DAY or
NIGHT, or something similar to define the lighting required. Everthing on
this line in CAPS.
• EXT: M-z e
Introduces a new EXTERIOR camera set-up. Everthing on this line in CAPS.
• Speaker M-z s
The character speaking.
• Parenthetical M-z p
Instructions to the speaker. The () are automatically inserted.
• Dialogue M-z d
What the Speaker says.
• Transition M-z t
Camera movement instruction. e. g. CUT TO:
• FADE OUT: M-z S-I
• Author M-z S-A
• Title M-z S-T
• Right_Address M-z r

3.8.2.6 Script jargon

• (O.S) — off screen
• (V.0) — voice over
• b. g. — background
• C.U. — close-up
• PAN — camera movement
• INSERT — cut to close-up of

52
4 Modules
4.1 Academic Field Specifics
4.1.1 Chemistry: Hazard and Precautionary Statements
This module provides two insets and a paragraph style to typeset numbers and
phrases of chemical hazard and precautionary statements. For a description see File ▷
Open Example ▷ Modules ▷ Hazard and Precautionary Statements and Help ▷ Specific Man-
uals ▷ Hazard and Precautionary Statements.

4.1.2 Chemistry: Risk and Safety Statements

This module provides two insets, R-S number and R-S phrase, accessible via the menu
Insert ▷ Custom Insets and an environment to typeset numbers and phrases of chemical
risk and safety statements.

4.1.3 Linguistics
This module provides specific environments useful for linguistics (numbered exam-
ples, glosses, semantic markup, OT tableau floats, Discourse Representation Struc-
tures, phonetic symbols). You can obtain information about this module in Help ▷
Specific Manuals ▷ Linguistics and File ▷ Open Example ▷ Modules ▷ Linguistics.

4.2 Accessibility
4.2.1 Braille
This module supports the Braille script. It requires the LATEX package braille.sty.
This and its documentation can be obtained from CTAN. See Help ▷ Specific Manuals ▷
Braille and File ▷ Open Example ▷ Modules ▷ Braille.

4.3 Annotation & Revision

4.3.1 FiXme Notes
This module provides “FiXme” (marginal) annotations for document revision pur-
poses. A list of annotations can be produced by using the “List of FIXMEs” in the

53
4 Modules

outline panel. The annotations are customizable via the LaTeX preamble. See the
fixme documentation which can be obtained from CTAN.
Note: by default, the notes are only displayed in “draft” mode (if the option
“draft” has been inserted in Document ▷ Settings ▷ Document Class ▷ Class Options ▷
Custom). To display them always, insert \fxsetup{draft} in Document ▷ Settings ▷
LATEX Preamble.

4.3.2 PDF Comments

This module provides various kinds of annotations for PDF output. See Help ▷
Specific Manuals ▷ PDF comments and File ▷ Open Example ▷ Modules ▷ PDF Comments.

4.3.3 PDF Form

This module provides fields and buttons for PDF forms. See the hyperref docu-
mentation, Help ▷ Specific Manuals ▷ PDF forms and File ▷ Open Example ▷ Modules ▷
PDF Form.

4.3.4 Ruby (Furigana)

This module defines an inset to typeset reading aids (ruby, furigana) to Chinese
characters. It uses the okumakro, luatexja-ruby or ruby package (depending on
the TeX engine) or a fallback definition.

4.3.5 TODO notes

This module provides custom insets to insert TODO items in your document. In order
to generate a “List of TODOs,” the module provides a paragraph style. Inserting
final in Document ▷ Settings ▷ Document Class ▷ Class Options ▷ Custom) suppresses
the output of TODO notes. See the todonotes documentation.

4.4 Bibliography
4.4.1 APA Style with Natbib
This module adds support for using natbib together with apacite (the bibliography
style need not be apacite — it could be apacite, apacitex, or any bibliography
that works with both the natbib and apacite packages.)

54
 4.5 Boxes

4.5 Boxes

4.5.1 Fancy Colored Boxes

This module adds ten custom insets that support colored boxes via the tcolorbox
package. See Help ▷ Specific Manuals ▷ Colored boxes, File ▷ Open Example ▷ Modules ▷
Fancy Color Boxes and the tcolorbox documentation for details.

4.5.2 Graphic boxes

This provides the custom insets Reflectbox, Resizebox, Rotatebox and Scalebox to scale
and rotate its content.
Reflectbox is a simple way of reversing text without any other enhancement:
yawliaR nretseW taerG
(You will need to use Ctrl-R to see any of these examples.)
Resizebox allows you to specify the dimensions of the text or image; permissible
units are em, ex, in, pt, pc, cm, mm, dd, cc, nd, nc, bp, or sp; if you enter ! for
Height it scales by the width factor:
Great Western Railway
Rotatebox allows you to rotate its contents around the reference point of the box.
If you wish to rotate the box around a different origin, place the cursor inside the
box and select Insert ▷ Origin; origin is specified as c, l, r, b, t or meaningful
combinations of these and the counterclockwise rotation angle is expressed in degrees.
For example:
ay
a ilw
R
t ern
s
t We
ea
Gr
You can combine boxes as in:
yawli
aR nrets
eW t
aerG
Scalebox scales its contents; select Insert ▷ V-Factor to add a vertical factor. If the
vertical factor is omitted, the horizontal is used. Adding different horizontal and
vertical values creates distortion as in
Great Western Railway.
A negative horizontal value reverses the text on the horizontal axis, a negative
vertical value on the vertical axis, so that you get
yawliaR nretseW taerG and Great Western Railway.

55
4 Modules

4.5.3 Section Boxes

This module defines Boxes with section header. It is mainly intended for the SciPoster
Document class.

4.5.4 Variable-width Minipages

This module adds a Minipage (Var. Width) inset to Insert ▷ Custom Inset using the
varwidth LaTeX package. The varwidth package provides a variable-width mini-
page, whose resulting width is the width of its contents (if this does not exceed the
specified maximum width). The inset has two optional arguments which can be
added by placing the cursor inside the minipage and entering Insert ▷ Vert. Adjustment
(c|t|b) or Insert ▷ Max. Width (defaults to \linewidth). See File ▷ Open Example ▷
Variable-width Minipages.

4.6 Fixes & Hacks

4.6.1 Fix Computer Modern Fonts
This module uses the fix-cm package to improve the appearance of Computer Modern
fonts and make them available with arbitrary sizes. See the fix-cm documentation.

4.6.2 LATEX Kernel Fixes (Obsolete)

This module loads the LATEX package fixltx2e which contains some bug fixes for LATEX.
If you use this module your typeset document may look different when you process
it, depending on the respective version of fixltx2e.
Note: recent LATEX kernels (as of 2015/01/01) include the functionality of fixltx2e,
so the fixltx2e module is obsolete with newer LATEX distributions.

4.6.3 Minimalistic Insets

This module redefines several insets (Index, Branch, URL) as being Minimalistic.

4.6.4 Title and Preamble Hacks

This module provides two new paragraph styles:

1. In Preamble which puts whatever is entered into it into the preamble. This can
be used, if one wishes, to include preamble code in the body of a LyX document.

2. In Title which that will put its contents into the body of the LaTeX document,
but before \maketitle is issued. This is useful for making branches and notes
in title-related material. (However, if you put these in a Standard layout, this
signals to LyX to output \maketitle, which may then come too early.)

56
 4.7 Floats & captions

4.7 Floats & captions

4.7.1 Algorithm2e Float
This module uses the algorithm2e package for algorithm floats rather than LyX’s
home-brewed algorithm floats. Use the Algorithm paragraph style to enter and indent
the algorithm. See the algorithm2e documentation.

4.7.2 Bilingual Captions AKA Multilingual Captions

This module provides the paragraph style Caption setup with which to typeset bilin-
gual captions. Within this paragraph style Insert ▷ Language allows you to enter the
desired second language using one of the babel names. See File ▷ Open Example ▷
Modules ▷ Multilingual Captions and Help ▷ Specific Manuals ▷ Multilingual Captions fur-
ther information on its use.

4.7.3 Number Figures by Section

This module resets the figure number at section start and prepends the section num-
ber to the figure number, as in “Figure 2.1.” (By default book and report document
classes number by Chapter and article document classes have a single sequence.)

4.7.4 Number Tables by Section

This module resets the table number at section start and prepends the section number
to the table number, as in “Table 2.1.” (By default book and report document classes
number by Chapter and article document classes have a single sequence.)

4.8 Foot- and Endnotes

4.8.1 Endnotes (Basic)
This module adds an endnote inset, in addition to footnotes. This uses the end-
notes package, which has some limitations but works with older LATEX distribu-
tions as well. Use Insert ▷ Custom Inset ▷ Endnote to insert an endnote and Insert ▷
List/Contents/References ▷ Endnotes to insert the endnotes list where you want the
endnotes to appear. See also Help ▷ Embedded Objects, section 4.2 Footnotes.

4.8.2 Endnotes (Extended)

This module adds an endnote inset, in addition to footnotes. This uses the enotez
package which is more powerful and customizable than the endnotes package, but
requires a fairly modern LATEX distribution (with LATEX3). Use Insert ▷ Custom In-
set ▷ Endnote to insert an endnote and Insert ▷ List/Contents/References ▷ Endnotes to

57
4 Modules

insert the endnotes list where you want the endnotes to appear. See also Help ▷
Embedded Objects, section 4.2 Footnotes..

4.8.3 Footnotes as Endnotes (Basic)

This module sets all footnotes as endnotes. This uses the endnotes package, which
has some limitations but works with older LATEX distributions as well. Use Insert ▷
List/Contents/References ▷ Endnotes to insert the endnotes list where you want the
endnotes to appear. See also Help ▷ Embedded Objects, section 4.2 Footnotes.

4.8.4 Footnotes as Endnotes (Extended)

This module sets all footnotes as endnotes. This uses the enotez package which is more
powerful and customizable than then endnotes package, but requires a fairly modern
LATEX distribution (with LATEX3). Use Insert ▷ List/Contents/References ▷ Endnotes to
insert the endnotes list where you want the endnotes to appear. See also Help ▷
Embedded Objects, section 4.2 Footnotes.

4.9 Leisure, Sports and Music

4.9.1 Chess Board
This module provides support for the chessboard package to print chess games. See
File ▷ Open Example ▷ Articles ▷ Chess where you will find Game 1 and Game 2 and the
chessboard documentation.

4.9.2 Lilypond Music Notation

This module provides an inset via Insert ▷ Custom Inset ▷ Lilypond in which to enter
code for the LilyPond music editor. It will then be processed in the output. See
Help ▷ Specific Manuals ▷ Lilypond and File ▷ Open Example ▷ Modules ▷ Lilypond Book.
It cannot be used if the modules Rnw (knitr) or Sweave have been loaded.

4.10 List enhancements

4.10.1 Customizable Lists
This module uses the enumitem package to enable the customization of various list
environments.

58
 4.10 List enhancements

4.10.1.1 Custom Enumerate Lists

The default numbering of numbered lists can be changed by adding an optional
argument (menu Insert ▷ Enumerate Options) to the first item of each level in the list.
There you add the command
label=\roman{enumi}
in TEX Code (shortcut ).
enumi is the first level counter of the enumeration. To change the numbering for
the list sublevels, replace the “i” in the command by the small Roman numeral of
the level (enumi, enumii, enumiii, enumiv).
The command \roman outputs the counter as a small Roman numeral. For capital
Roman numerals replace \roman with \Roman in the command above. For Arabic
numerals use \arabic. To “number” items with capital or small Latin letters use \Alph
or \alph, respectively.
Note: You can only number 26 items with Latin letters, because this numbering is
limited to single letters.
Here is a list with custom numbering:
#A# Level 1
A.1 Level 2
A.2 Level 2
1 Level 3
i) Level 4
For this list these commands were used:
label=\#\Alph{enumi}\#
label=\Alph{enumi}.\arabic{enumii}
label=\bfseries{\arabic{enumiii}}
label=\emph{\roman{enumiv})}
where the command \emph{} makes the label emphasized and \bfseries{} makes
it bold.
Note: When you change the label of a list level, it will be used for all following
lists until you change the definition.

4.10.1.2 Numbered Paragraphs in Reports

4.10.1 Official reports often include numbered paragraphs; you can achieve this with
a variation on the approach outlined in section 6.3. Replace item in each com-
mand with enum.
4.10.2 These numbered paragraphs were generated by inserting the TEX Code
\renewcommand{\labelenumi}{\thesection.\arabic{enumi}}
before the start of the section; \thesection uses the LATEX section counter to
generate the first part of the number.

59
 4 Modules

4.10.3 I have ignored the subsection heading in this example because, with paragraphs
numbered in this way, subsections are less likely to be used.

4.10.1.3 Resumed Enumeration

Enumerations can be resumed after intermediate paragraphs:

1. first

2. second

regular text

3 resumed

To resume an enumeration, use the style Enumerate-Resume.

Note: If there is no previous enumeration to resume, you will get a LATEX error.
Perhaps you might want to resume the list with a different number from the next
one. Or you want to start a new enumeration with a defined number. This is possible
by adding an optional argument to the first list item of a normal enumeration. There,
insert the command
start=number
where number is the number with which you want to resume the list. An example:

1 first item

2 second item

Enumeration starting at a given value:

4 This enumeration starts at 4

4.10.1.4 List Spacing

In some cases you might want less or more vertical space between the items of a list.
For example if the default space is too much in your opinion in this case:

• A bullet list

• with standard spacing

You can decrease the space by adding an optional argument to the first item of the
list. Add there the command nolistsep to get no additional list space like in this
example:
• A bullet list
• without additional
• vertical space

60
 4.10 List enhancements

To add space you can use several other commands provided by the enumitem package.
For more information see the enumitem documentation.
There are also many commands available to change the horizontal spacing and
indentation. Here is an example where the indentation was changed to that of the
paragraphs in the document and the label separation was set to 2 cm so that the
number is in the page margin:

1 An enumeration

2 with negative indentation

4.10.1.5 Further Customization

You can also change the style of description lists. The command
font=definition
changes the description label font, the command
style=definition
sets the list style.
An example where the command
font=\itshape, style=nextline
is used:

Ionizing radiation:
Ionizing radiation consists of particles or electromagnetic waves that are ener-
getic enough to detach electrons from atoms or molecules, therefore ionizing
them.

Reference counting:
In computer science, reference counting is a technique of storing the number
of references, pointers, or handles to a resource such as an object, block of
memory, disk space or other resource.

There are many more commands and features provided by the enumitem package.
For more information see the enumitem documentation.

4.10.2 Paragraph Lists

This module uses the package paralist to provide nine new list environments. Item-
ized and enumerated lists can be typeset within paragraphs, as paragraphs and in
a compact version. Most environments have optional arguments to format the la-
bels. Additionally, the LATEX list environments itemize and enumerate are extended
to use a similar optional argument. For further details see File ▷ Open Example ▷
Modules ▷ Paragraph List (paralist), Help ▷ Specific Manuals ▷ Paralist and the paralist
documentation.

61
4 Modules

4.11 Literate Programming

4.11.1 Noweb
This module allows the use of Noweb as a literate programming tool. The files and
the documentation for Noweb can be obtained from CTAN. Literate programming
is described in section 11.3 and there are three example files: File ▷ Open Example ▷
Modules ▷ Noweb, File ▷ Open Example ▷ Modules ▷ Noweb Listerrors and File ▷ Open Ex-
ample ▷ Modules ▷ Noweb2LYX.

4.11.2 Rnw (knitr)

This module uses the knitr and includernw packages. Theknitr package in R for dy-
namic report generation has to be installed for this module to work: install.packages(“knitr”).
Note:

• it depends on R >= 2.14.1. For more info see http://yihui.name/knitr.

• The package includernw also has to be installed.

• It cannot be used if the modules LilyPond Book or Sweave are loaded.

See Help ▷ Specific Manuals ▷ Knitr, File ▷ Open Example ▷ Modules ▷ Rnw (knitr) and sec-
tion 11.3 for information about literate programming.

4.11.3 Sweave
This module allows the use of the statistical language S/R as a literate programming
tool. It requires the includernw and fancyvrb packages. Both includernw and fancyvrb
are available from CTAN. It cannot be used if the module LilyPond Book has been
loaded. See Help ▷ Specific Manuals ▷ Sweave, File ▷ Open Example ▷ Modules ▷ Sweave
and section 11.3 for information about literate programming.

4.12 Maths
4.12.1 AMS Theorems
This modules defines theorem environments and the proof environment using the
extended AMS machinery. Both numbered and unnumbered types are provided. By
default, the theorems are numbered consecutively throughout the document. This
can be changed by loading one of the AMS Theorems (Numbered by . . . ) modules. It
cannot be used if the modules Standard Theorems or Standard Theorems (Unnumbered)
have been loaded.

62
 4.12 Maths

4.12.2 AMS Theorems (Extended)

This module defines some additional theorem environments for use with the AMS
Theorems package (which must be loaded). It includes Criterion, Algorithm, Axiom,
Condition, Note, Notation, Summary, Conclusion, Fact, Assumption, Case and Question
in both numbered and unnumbered forms.

4.12.3 AMS Theorems (Extended, Numbered by Type within

Chapters)
This module defines some additional theorem environments for use with the AMS
Theorems (Numbered by Type within Chapters) module (which must be loaded). It
includes Criterion, Algorithm, Axiom, Condition, Note, Notation, Summary, Conclusion,
Assumption and Case in both numbered and unnumbered forms.
Unlike the AMS Theorems (Extended) module, the different theorem types provided
here each have a separate counter, restarted with each new chapter (e.g., Criterion
1.1, Criterion 1.2, Axiom 1.1, Assumption 1.1, Criterion 2.1, Criterion 2.2, Axiom
2.1, . . . , as opposed to Criterion 1, Criterion 2, Axiom 3, Assumption 4, . . . ).

4.12.4 AMS Theorems (Extended, Numbered by Type)

This module defines some additional theorem environments for use with the AMS
Theorems (Numbered by Type) package (which must be loaded). It includes Criterion,
Algorithm, Axiom, Condition, Note, Notation, Summary, Conclusion, Assumption and
Case in both numbered and unnumbered forms.
Unlike the AMS Theorems (Extended) module, the different theorem types provided
here each have a separate counter (e.g., Criterion 1, Criterion 2, Axiom 1, Assumption
1, Criterion 3, . . . , as opposed to Criterion 1, Criterion 2, Axiom 3, Assumption 4,
. . . ).

4.12.5 AMS Theorems (Numbered by Type within Chapters)

This module defines theorem environments and the proof environment using the
extended AMS machinery. Both numbered and unnumbered types are provided.
Unlike the AMS Theorems module, the different theorem types provided here each
have a separate counter (e.g., Theorem 1.1, Theorem 1.2, Lemma 1.1, Proposition
1.1, Theorem 1.3, Lemma 1.2, . . . , as opposed to Theorem 1, Theorem 2, Lemma 3,
Proposition 4, . . . ). The numbering restarts for each chapter: Theorem 1.1, Theorem
2.1, . . .
It cannot be used if the modules AMS Theorems, Standard Theorems, Standard
Theorems (Numbered by Type) or Standard Theorems (Unnumbered) have been loaded.

63
4 Modules

4.12.6 AMS Theorems (Numbered by Type)

This module defines theorem environments and the proof environment using the ex-
tended AMS machinery. Both numbered and unnumbered types are provided. Unlike
the AMS Theorems module, the different theorem types provided here each have a
separate counter (e.g., Theorem 1, Theorem 2, Lemma 1, Proposition 1, Theorem
3, Lemma 2, . . . , as opposed to Theorem 1, Theorem 2, Lemma 3, Proposition 4,
. . . ). The numbering’s scope is the whole document. For chapter- and section-wide
numbering, use one of the ‘within Sections’/‘within Chapters’ modules, respectively.
It cannot be used if the modules AMS Theorems, Standard Theorems, Standard
Theorems (Numbered by Type) or Standard Theorems (Unnumbered) have been loaded.

4.12.7 Number Equations by Section

This module resets the equation number at section start and prepends the section
number to the equation number, as in (2.1).

4.12.8 Standard Theorems

This module defines some theorem environments for use with non-AMS classes. By
default, the theorems are numbered consecutively throughout the document. This
can be changed by loading one of the Standard Theorems (Numbered by . . . ) modules.
It cannot be used if the modules AMS Theorems or Standard Theorems (Unnum-
bered) have been loaded.

4.12.9 Standard Theorems (Nameable)

This module facilitates the use of named theorems. The name of the theorem can be
inserted via Insert ▷ Additional Theorem Text.

4.12.10 Standard Theorems (Numbered by Chapter)

This module numbers theorems and the like by chapter (i.e., the counter is reset
at each chapter start). Use this module only with document classes that provide a
chapter environment.
One of the modules AMS Theorems or Standard Theorems must be loaded.
It cannot be used if the module Standard Theorems (Numbered by Section) has been
loaded.

4.12.11 Standard Theorems (Numbered by Section)

This module numbers theorems and the like by section (i.e., the counter is reset at
each section start). One of the modules AMS Theorems or Standard Theorems must
be loaded. It cannot be used if the module Standard Theorems (Numbered by Chapter)
has been loaded.

64
 4.12 Maths

4.12.12 Standard Theorems (Numbered by Type within

Chapters)
This module defines some theorem environments for use with non-AMS classes. Un-
like the AMS Theorems and Standard Theorems modules, the different theorem types
provided here each have a separate counter (e.g., Theorem 1, Theorem 2, Lemma
1, Proposition 1, Theorem 3, Lemma 2, . . . , as opposed to Theorem 1, Theorem 2,
Lemma 3, Proposition 4, . . . ). The numbering is reset at each chapter start.
One of the modules AMS Theorems (Numbered by Type) or Standard Theorems
(Numbered by Type) must be loaded.
It cannot be used if any of the modules AMS Theorems, Standard Theorems, Stan-
dard Theorems (Unnumbered), Standard Theorems (Numbered by Sections) or Standard
Theorems (Numbered by Type within Sections) have been loaded.

4.12.13 Standard Theorems (Numbered by Type within Sections)

This module defines some theorem environments for use with non-AMS classes. Un-
like the AMS Theorems and Standard Theorems modules, the different theorem types
provided here each have a separate counter (e.g., Theorem 1, Theorem 2, Lemma
1, Proposition 1, Theorem 3, Lemma 2, . . . , as opposed to Theorem 1, Theorem 2,
Lemma 3, Proposition 4, . . . ). The numbering is reset at each section start.
One of the modules AMS Theorems (Numbered by Type) or Standard Theorems
(Numbered by Type) must be loaded.
It cannot be used if any of the modules AMS Theorems, Standard Theorems, Stan-
dard Theorems (Unnumbered), Standard Theorems (Numbered by Chapters) or Standard
Theorems (Numbered by Type within Chapters) have been loaded.

4.12.14 Standard Theorems (Numbered by Type)

This module defines some theorem environments for use with non-AMS classes. Un-
like the AMS Theorems and Standard Theorems modules, the different theorem types
provided here each have a separate counter (e.g., Theorem 1, Theorem 2, Lemma
1, Proposition 1, Theorem 3, Lemma 2, . . . , as opposed to Theorem 1, Theorem
2, Lemma 3, Proposition 4, . . . ). The numbering’s scope is the whole document.
For chapter- and section-wide numbering, use one of the “within Chapters”/“within
Sections” modules, respectively.
It cannot be used if any of the modules AMS Theorems, Standard Theorems, Standard
Theorems (Unnumbered) or AMS Theorems (Numbered by Type) have been loaded.

4.12.15 Standard Theorems (Unnumbered)

This module defines only unnumbered theorem environments and the proof environ-
ment, using the extended AMS machinery. It cannot be used if either of the modules
AMS Theorems or Standard Theorems have been loaded.

65
4 Modules

4.12.16 Subequations
This module provides a straightforward way to segregate subequations in LyX. See
Help ▷ Math ▷ Subnumbering.

4.13 Page Layout

4.13.1 Custom Header/Footer Text
This module requires the Page style option in the Document ▷ Settings ▷ Page Layout
dialog to be set to fancy. It adds six environments to document classes which support
the fancyhdr package:

• Left Header

• Center Header

• Right Header

• Left Footer

• Center Footer

• Right Footer

4.13.1.1 Fancy Headers and Footers

The default page layout is rather plain; for an Article (Standard Class) document class,
all you get is a centered page number at the bottom of the page. This document uses
the KOMA-Script Book class; so it appears to be a bit fancier.
Once the Page style in Document ▷ Settings ▷ Page Layout is set to “fancy”, you will
find that the page header is divided into three fields, not surprisingly labeled “left”,
“center”, and “right”. The footer is also divided into these three fields. The LATEX
commands to set these fields in the simplest manner are \lhead, \chead, \rhead,
\lfoot, etc. Suppose you wish to put your name in the upper left hand corner of
each page. Simply insert the following command in the preamble:

\lhead{John Q. DocWriter}

You will now see your name in the upper left. If a field has a default entry that you
would like to get rid of (often the page number appears in the central footer) simply
include a command with a blank argument, e. g.:

\cfoot{}

66
 4.13 Page Layout

There is, however, an easier way to make simple changes. If you load the Document ▷
Settings ▷ Modules ▷ Page Layout ▷ Custom Header/Footer Text module, you will find
you have six new environments corresponding to the six fields described above.
Let’s get really fancy: lets put the section number with the word “Section” (e. g.
Section 3) in the upper left, the page number (e. g. Page 4) in the upper right, your
name in the lower left, and the date in the lower right. Use your newly enabled
environments to add these entries:

Left header: Section \thesection

Center header:
Right header: Page \thepage
Left footer: John Q. DocWriter
Center footer:
Right footer: \today

Make sure you enter the commands \thesection, \thepage and \today as TEX Code
commands. The commands \thesection and \thepage access LATEX’s section and
page counters, and so print out the current section and page numbers. \today simply
prints out today’s date.
The thicknesses of the horizontal rules drawn beneath the header and above the
footer can also be modified. If you don’t want one of the rules, set its thickness to 0.
The header rule has a default thickness of 0.4pt, the footer rule is 0pt. For this you
will need to use TEX Code commands like
\renewcommand{\headrulewidth}{0.4pt} and
\renewcommand{\footrulewidth}{0.4pt} to set the thicknesses.
You can switch the header/footer settings on and off for individual pages using
TEX Code commands like \thispagestyle{empty}, \thispagestyle{plain}, and
\thispagestyle{fancy}. Simply insert them in the text on the page you want
changed and mark them as TEX code. In fact, title pages are marked as plain by
default, while following pages are marked fancy when using the global fancy setting.
If you want a header or footer to be on the outer side of a two sided document,
you need to use something like:

\fancyfoot{}
\fancyfoot[LE,RO]{\thepage}

The first command clears all existing footers avoiding any conflicts with your new
command.
You can enter any of these commands, the simpler ones in any of your new en-
vironments, the more complex ones as TEX Code commands, at any point in your
document and they will take effect on the next page.
As a final example, it is possible to include an image in the header or footer.
Suppose you want to put a company logo in the upper left hand corner. You might
try something like this in Document ▷ Settings ▷ LaTeX Preamble:

67
4 Modules

\lhead{\resizebox{1in}{!}{\includegraphics{logo.png}}}

You may need to preface this with \usepackage{graphics} if you don’t include
graphics elsewhere in your document.
For more information on fancy headers, you can get the fancyhdr documentation
from CTAN.

4.13.2 Landscape Document Parts

This module outputs parts of the document in landscape mode using Insert ▷ Custom
Insets ▷ Landscape or Insert ▷ Custom Insets ▷ Landscape (Floating).

4.13.3 Multiple Columns

This module uses the multicol package and is independent of the option Two-column
document in the Document ▷ Settings ▷ Text Layout dialog. If you want to have two
columns for the whole document, you are recommended to use the Two-column doc-
ument option. For all other cases use this module.
Footnotes within multiple columns will be placed at the bottom of the page and
not under each column. Within the different columns you can use everything, with
the limitation that for floats you need to check the option Span columns in Edit ▷
Float Settings.

4.13.3.1 Basics
If you want to have two columns in your text, insert a multicolumn inset via the
menu Insert ▷ Custom Insets ▷ Multiple Columns where the columns should start. Write
all text that should be printed in 2 columns into this inset.
Here is an example:

The Adventure of the Empty House ing links which make up the whole of that
by Sir Arthur Conan Doyle remarkable chain. The crime was of inter-
est in itself, but that interest was as noth-
It was in the spring of the year 1894 that ing to me compared to the inconceivable se-
all London was interested, and the fashion- quel, which afforded me the greatest shock
able world dismayed, by the murder of the and surprise of any event in my adventur-
Honourable Ronald Adair under most un- ous life. Even now, after this long inter-
usual and inexplicable circumstances. The val, I find myself thrilling as I think of it,
public has already learned those particulars and feeling once more that sudden flood of
of the crime which came out in the police in- joy, amazement, and incredulity which ut-
vestigation, but a good deal was suppressed terly submerged my mind. Let me say to
upon that occasion, since the case for the that public, which has shown some interest
prosecution was so overwhelmingly strong in those glimpses which I have occasionally
that it was not necessary to bring forward given them of the thoughts and actions of a
all the facts. Only now, at the end of nearly very remarkable man, that they are not to
ten years, am I allowed to supply those miss-

68
 4.13 Page Layout

blame me if I have not shared my knowledge by a positive prohibition from his own lips,
with them, for I should have considered it which was only withdrawn upon the third of
my first duty to do so, had I not been barred last month.

To get 3 or more columns, set the cursor into the multicolumn inset and use the
menu Insert ▷ Number of Columns. The number of the desired columns is written into
that inset (for 3 columns write “3”).
Here is an example with 3 columns:

It can be imagined that of Ronald Adair. As I read the or more probably anticipated,
my close intimacy with Sher- evidence at the inquest, which by the trained observation and
lock Holmes had interested me led up to a verdict of will- the alert mind of the first crimi-
deeply in crime, and that after ful murder against some person nal agent in Europe. All day, as
his disappearance I never failed or persons unknown, I realized I drove upon my round, I turned
to read with care the various more clearly than I had ever over the case in my mind and
problems which came before the done the loss which the commu- found no explanation which ap-
public. And I even attempted, nity had sustained by the death peared to me to be adequate.
more than once, for my own of Sherlock Holmes. There were At the risk of telling a twice-
private satisfaction, to employ points about this strange busi- told tale, I will recapitulate the
his methods in their solution, ness which would, I was sure, facts as they were known to the
though with indifferent success. have specially appealed to him, public at the conclusion of the
There was none, however, which and the efforts of the police inquest.
appealed to me like this tragedy would have been supplemented,

You can have up to 10 columns if you want to, but that might not be very pleasant
for the readers of your document.

4.13.3.2 Columns inside Columns

You can also have columns inside columns:

The Honourable Ronald Adair was the second The youth moved rest {sic} the man’s life
son of the Earl of Maynooth, at that time gov- in the best society – moved in a narrow and
ernor of one of the Australian colonies. Adair’s
had, so far as was conventional circle, for
mother had returned from Australia to undergo
the operation for cataract, and she, her son known, no enemies and his habits were quiet
Ronald, and her daughter Hilda were living to- no particular vices. He and his nature unemo-
gether at 427 Park Lane. had been engaged to tional. Yet it was upon
Miss Edith Woodley, this easy-going young
of Carstairs, but the aristocrat that death
engagement had been came, in most strange
broken off by mutual and unexpected form,
consent some months between the hours of
before, and there was ten and eleven-twenty
no sign that it had left on the night of March
any very profound feel- 30, 1894.
ing behind it. For the

69
4 Modules

Ronald Adair was fond of cards – playing con- have lost five pounds, but not more. His fortune
tinually, but never for such stakes as would hurt was a considerable one, and such a loss could
him. He was a member of the Baldwin, the not in any way affect him. He had played nearly
Cavendish, and the Bagatelle card clubs. It was every day at one club or other, but he was a cau-
shown that, after dinner on the day of his death, tious player, and usually rose a winner. It came
he had played a rubber of whist at the latter club. out in evidence that, in partnership with Colonel
He had also played there in the afternoon. The Moran, he had actually won as much as four hun-
evidence of those who had played with him – Mr. dred and twenty pounds in a sitting, some weeks
Murray, Sir John Hardy, and Colonel Moran – before, from Godfrey Milner and Lord Balmoral.
showed that the game was whist, and that there So much for his recent history as it came out at
was a fairly equal fall of the cards. Adair might the inquest.

4.13.3.3 Advanced Examples

The examples in this section show some more special features of multiple columns.
For more features of multiple columns, have a look at the documentation of the
LATEX-package multicol.

Preface To add a preface text for multiple columns, set the cursor into the mul-
ticolumn inset and use the menu Insert ▷ Preface. Write your preface text into that
inset.
This is an example with some preface text:

And the story continues and continues and continues and continues. . .

On the evening of the crime, he returned her daughter. Desiring to say good-night,
from the club exactly at ten. His mother and she attempted to enter her son’s room. The
sister were out spending the evening with door was locked on the inside, and no an-
a relation. The servant deposed that she swer could be got to their cries and knock-
heard him enter the front room on the sec- ing. Help was obtained, and the door forced.
ond floor, generally used as his sitting-room. The unfortunate young man was found lying
She had lit a fire there, and as it smoked near the table. His head had been horribly
she had opened the window. No sound was mutilated by an expanding revolver bullet,
heard from the room until eleven-twenty, the but no weapon of any sort was to be found
hour of the return of Lady Maynooth and in the room.

You can also use a section heading as the preface if you use a section command as
TEX Code. For example the command

\subsection{subsection title}

creates a subsection. In this example the preface is a subsubsection:

4.13.3.4 This is a subsubsection heading as a preface

A minute examination of the circumstances served only to make the case more complex.

70
 4.13 Page Layout

In the first place, no reason could be given Apparently, therefore, it was the young man
why the young man should have fastened the himself who had fastened the door. But how
door upon the inside. There was the possi- did he come by his death? No one could
bility that the murderer had done this, and have climbed up to the window without leav-
had afterwards escaped by the window. The ing traces. Suppose a man had fired through
drop was at least twenty feet, however, and the window, he would indeed be a remark-
a bed of crocuses in full bloom lay beneath. able shot who could with a revolver inflict so
Neither the flowers nor the earth showed any deadly a wound. Again, Park Lane is a fre-
sign of having been disturbed, nor were there quented thoroughfare; there is a cab stand
any marks upon the narrow strip of grass within a hundred yards of the house. No one
which separated the house from the road. had heard a shot.

If there is less vertical space than six text lines is left on the page at the beginning
of the multiple columns, a page break will be inserted before the multiple columns.
Depending on the number of lines of the preface text, you might want to change
this space. This is done by setting the cursor into the mulitcolumn inset behind the
preface (if there is any) and using the menu Insert ▷ Space Before Page Break. Insert
into that inset the amount of space like e. g. “5cm”.
In this example the space is set to 7 text lines by using 7\baselineskip (where the
command \baselineskip needs to be inserted as TEX code):

On the evening of the crime, he returned her daughter. Desiring to say good-night,
from the club exactly at ten. His mother and she attempted to enter her son’s room. The
sister were out spending the evening with door was locked on the inside, and no an-
a relation. The servant deposed that she swer could be got to their cries and knock-
heard him enter the front room on the sec- ing. Help was obtained, and the door forced.
ond floor, generally used as his sitting-room. The unfortunate young man was found lying
She had lit a fire there, and as it smoked near the table. His head had been horribly
she had opened the window. No sound was mutilated by an expanding revolver bullet,
heard from the room until eleven-twenty, the but no weapon of any sort was to be found
hour of the return of Lady Maynooth and in the room.

Surrounding Space The amount of space before and after multiple columns can be
changed by changing the length \multicolsep. For example the command
\setlength{\multicolsep}{3cm}
in TEX Code changes its value to 3 cm. The change must be made before the multiple
columns’ start. The predefined value is 13 pt.
For this example \multicolsep was set to 2.5 cm:

All day I turned these facts over in my

71
4 Modules

mind, endeavouring to hit upon some the- see. A tall, thin man with coloured glasses,
ory which could reconcile them all, and to whom I strongly suspected of being a plain-
find that line of least resistance which my clothes detective, was pointing out some the-
poor friend had declared to be the starting- ory of his own, while the others crowded
point of every investigation. I confess that I round to listen to what he said. I got as near
made little progress. In the evening I strolled him as I could, but his observations seemed
across the Park, and found myself about six to me to be absurd, so I withdrew again in
o’clock at the Oxford Street end of Park some disgust. As I did so I struck against an
Lane. A group of loafers upon the pave- elderly, deformed man, who had been behind
ments, all staring up at a particular window, me, and I knocked down several books which
directed me to the house which I had come to he was carrying.

Note: The values you set with \setlength will be used for all following multiple
columns until you change them again.

Column Breaks A column break can be forced by inserting the command \columnbreak{}
as TEX Code to that position in the text where the column should be broken. Note
that this leads in most cases to whitespace in the text.
Here is an example:

“You’re surprised to see me, sir,” said he, “Well, sir, if it isn’t too great a liberty,
in a strange, croaking voice. I am a neighbour of yours, for you’ll find
I acknowledged that I was. my little bookshop at the corner of Church
“Well, I’ve a conscience, sir, and when I Street, and very happy to see you, I am
chanced to see you go into this house, as I sure. Maybe you collect yourself, sir. Here’s
came hobbling after you, I thought to myself, British Birds, and Catullus, and The
I’ll just step in and see that kind gentleman, Holy War – a bargain, every one of them.
and tell him that if I was a bit gruff in my With five volumes you could just fill that gap
manner there was not any harm meant, and on that second shelf. It looks untidy, does it
that I am much obliged to him for picking not, sir?”
up my books.”
“You make too much of a trifle,” said
I. “May I ask how you knew who I was?”
AFTER THIS SENTENCE THE COLUMN
BREAK IS FORCED.

Column Separation The width of the columns is automatically calculated, but you
can modify the space between the columns. This is done by changing the length
\columnsep. Its predefined value is 10 pt. Here is an example where \columnsep is
set to 3 cm:

72
 4.13 Page Layout

My observations of No. 427 Park ever, I retraced my steps to Kens-

Lane did little to clear up the prob- ington. I had not been in my study
lem in which I was interested. The five minutes when the maid entered
house was separated from the street to say that a person desired to see
by a low wall and railing, the whole me. To my astonishment it was none
not more than five feet high. It was other than my strange old book col-
perfectly easy, therefore, for anyone lector, his sharp, wizened face peer-
to get into the garden, but the win- ing out from a frame of white hair,
dow was entirely inaccessible, since and his precious volumes, a dozen of
there was no water pipe or anything them at least, wedged under his right
which could help the most active arm.
man to climb it. More puzzled than

Vertical Lines Between the columns a rule with a width of the length \columnseprule
is placed. If this rule width is set to 0 pt (this is the default), the rule is suppressed.
In the following example the rule is 2 pt wide:

“You’re surprised to see me, sir,” said he, “You make too much of a trifle,” said I.
in a strange, croaking voice. “May I ask how you knew who I was?”
“Well, sir, if it isn’t too great a liberty,
I acknowledged that I was.
I am a neighbour of yours, for you’ll find
“Well, I’ve a conscience, sir, and when I my little bookshop at the corner of Church
chanced to see you go into this house, as I Street, and very happy to see you, I am
came hobbling after you, I thought to myself, sure. Maybe you collect yourself, sir. Here’s
I’ll just step in and see that kind gentleman, British Birds, and Catullus, and The
and tell him that if I was a bit gruff in my Holy War – a bargain, every one of them.
manner there was not any harm meant, and With five volumes you could just fill that gap
that I am much obliged to him for picking on that second shelf. It looks untidy, does it
up my books.” not, sir?”

The rule can be colored by redefining the command \columnseprulecolor. This

is done by inserting the command

\renewcommand{\columnseprulecolor}{\color{red}}

as TEX Code before the multicolumn inset. Replace red in this command by a color
of your choice. You can use all pre- and self-defined colors. See the EmbeddedOb-
jects manual, section Colored Tables for more information about pre- and self-defined
colors. To go back to the default color insert the command

\renewcommand{\columnseprulecolor}{\normalcolor}

Here is the example with a cyan rule and 1 cm column separation:

73
4 Modules

“You’re surprised to see me, sir,” said “May I ask how you knew who I was?”
he, in a strange, croaking voice. “Well, sir, if it isn’t too great a lib-
I acknowledged that I was. erty, I am a neighbour of yours, for you’ll
“Well, I’ve a conscience, sir, and when find my little bookshop at the corner of
I chanced to see you go into this house, Church Street, and very happy to see you,
as I came hobbling after you, I thought to I am sure. Maybe you collect yourself,
myself, I’ll just step in and see that kind sir. Here’s British Birds, and Catul-
gentleman, and tell him that if I was a bit lus, and The Holy War – a bargain, ev-
gruff in my manner there was not any harm ery one of them. With five volumes you
meant, and that I am much obliged to him could just fill that gap on that second shelf.
for picking up my books.” It looks untidy, does it not, sir?”
“You make too much of a trifle,” said I.

4.14 Paragraph Styles

4.14.1 Custom Paragraph Shapes
LATEX as well as any other text processor uses by default rectangular paragraphs. For
special cases like for example posters, invitation cards or poems you can modify the
paragraph shape to one of your choice. This module uses the shapepar package to
provide over a dozen paragraph shapes as well as commands to define custom shapes.

4.14.1.1 Predefined shapes

The shapepar package provides the following shapes:

Name Description Annotation

Circle with circular hole (in the size Cannot be scaled, take care
CDlabel
of a CD/DVD) there is not too much text
Circle Circle Fragile, calculation might fail
Rhomboid (symbolizing a
Diamond -
“diamond”)
Heart Heart-like shape -
Hexagon Hexagon -
Nut for bolt (hexagon with circular
Nut -
hole)
Square Square -
Star Five-point star -
Candle Burning candle -

74
 4.14 Paragraph Styles

Name Description Annotation

Drop
Normal/reversed rain drop Fragile, calculation might fail
down/up
TEX The TEX logo -
Triangle
up/down/ Triangles in different orientations -
left/right

To use a shape for your paragraph, simply select it in LYX’s pull-down box for
environments in the toolbar.

75
4 Modules

Here is an example paragraph in the shape of a nut:

Lorem ipsum dolor sit

amet, consetetur sadipscing
elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore
magna aliquyam erat, sed diam
voluptua. At vero eos et ac-
cusam et ju- sto duo do-
lores et ea re- bum. Stet cli-
ta kasd guber- gren, no sea ta-
kimata sanc- tus est Lorem
ipsum dolor sit amet. Lo-
rem ipsum dolor sit amet, conse-
tetur sadipscing elitr, sed diam nonu-
my eirmod tempor invidunt ut la-
bore et dolore magna aliquyam
erat, sed diam voluptua.

Note: shapepar paragraphs cannot run over a page break.

The package shapepar takes care that the shape will always be preserved, no
matter how much text is in the paragraph. Therefore the paragraph size changes
with the amount of contained text. This can lead to paragraph sizes exceeding the
page margins. To demonstrate the size scaling, here is the same example paragraph
but with twice as much text:

76
 4.14 Paragraph Styles

Lorem ipsum dolor sit amet, consete-

tur sadipscing elitr, sed diam nonumy eir-
mod tempor invidunt ut labore et dolore ma-
gna aliquyam erat, sed diam voluptua. At vero
eos et accusam et justo duo dolores et ea rebum.
Stet clita kasd gubergren, no sea takimata sanctus est
Lorem ipsum dolor sit amet. Lorem ipsum
dolor sit amet, con- setetur sadipscing
elitr, sed diam no- numy eirmod tem-
por invidunt ut la- bore et dolore ma-
gna aliquyam erat, sed diam voluptua.
Lorem ipsum dolor sit amet, consete-
tur sadipscing eli- tr, sed diam nonu-
my eirmod tempor invidunt ut labo-
re et dolore magna aliquyam erat, sed
diam voluptua. At vero eos et accusam
et justo duo dolores et ea rebum. Stet clita kasd guber-
gren, no sea takimata sanctus est Lorem ipsum dolor
sit amet. Lorem ipsum dolor sit amet, consete-
tur sadipscing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore ma-
gna aliquyam erat, sed diam voluptua.

An exception is the shape CDlabel. It cannot be scaled because it must fit the size
of a CD/DVD. Therefore the amount of text that fits into the shape is limited.
The drop shapes and the circle shape are fragile, meaning that the calculation of
their size can fail, depending on the amount of text. You will then get the LATEX
error “Arithmetic overflow”. In this case one can try to remove or add some text; if
nothing works one has to use another shape.
For shapes with tips you will maybe see that LATEX’s hyphenation routine fails for
text in the tips. Therefore it is often necessary to add hyphenation points () to the
corresponding text parts.
Shapepar paragraphs are either always centered or placed on the page so that their
left border touches the left page margin. You can therefore not use the paragraph
dialog to align such paragraphs. A solution is to put the paragraph into a minipage
or parbox and align the box. The problem is hereby to find the right width for the
box. Because if it is too wide and you center the box, the paragraph is not centered
too because it sticks at the left side of the box. So you might have to play a bit with
the width until it fits. Here are two heart-shaped paragraphs, the first one is not
aligned, the second one is right-aligned:

77
4 Modules

Lorem ipsum
dolor sit amet, consetetur sa-
dipscing elitr, sed diam nonumy eir-
mod tempor invidunt ut labore et do-
lore magna aliquyam erat, sed diam
voluptua. At vero eos et accusam
et justo duo dolores et ea rebum.
Stet clita kasd gubergren, no
sea takimata sanctus est
Lorem ipsum dolor
sit amet.
♡

Lorem ipsum
dolor sit amet, consetetur sa-
dipscing elitr, sed diam nonumy eir-
mod tempor invidunt ut labore et do-
lore magna aliquyam erat, sed diam
voluptua. At vero eos et accusam
et justo duo dolores et ea rebum.
Stet clita kasd gubergren, no
sea takimata sanctus est
Lorem ipsum dolor
sit amet.
♡

4.14.1.2 Custom shapes

You can define any shape you want. Doing this manually is a lot of work because
every coordinate must be specified. But there is a way to let the computer calculate
the coordinates:

1 Install the program Jpgfdraw.

2 In Jpgfdraw go to the menu TeX/LaTeX ▷ Settings ▷ Set Normal Size and select
the font size you are using in your document. For example this document uses
the size 12 pt.

3 Draw a shape.

4 Use the menu TeX/LaTeX ▷ Shapepar to export the shape to coordinates. In the
appearing dialog use either the outline of your shape for the coordinates or the
path itself.1
1
For more information see http://www.dickimaw-books.com/apps/jpgfdraw/manual/shapepar.html

78
 4.14 Paragraph Styles

The coordinates are written into a TEX file. To use it for your LYX document
1 Place the cursor before the first character of your paragraph (or into a new
empty one).
2 Open in LYX the menu Insert ▷ File ▷ Child Document, select the file and use Input
as Include Type.

Note: The changed shape only applies to the current paragraph; everything is
reset to normal for the next paragraph. Therefore the shape definition file must be
input into every paragraph with the desired shape.

Here is an example:

Lorem ipsum dolor sit amet, consetetur sadip-

scing elitr, sed diam no- numy eirmod tem-
por invidunt ut labo- re et dolore ma-
gna aliquyam erat, sed diam volup-
tua. At vero eos et accusam et ju-
sto duo dolores et ea rebum. Stet
clita kasd guber- gren, no sea ta-
kimata sanctus est Lorem ipsum
dolor sit amet. Lo- rem ipsum do-
lor sit amet, con- setetur sadip-
scing elitr, sed diam nonumy eirmod
tempor invidunt ut labore et dolore
magna aliquyam erat, sed diam voluptua.

A tip: to draw complexer shapes in Jpgfdraw you can draw the shape in a program
of your choice and import the resulting image to Jpgfdraw. Then you only need to
draw a line or spline along the outline of the image.
The module Custom paragraph shapes also provides the two commands shapepar and
Shapepar which can be used to define custom shapes coordinate by coordinate.2 For
information how these styles are used and about further customization possibilities,
have a look at the documentation of the package shapepar.

4.14.2 Hanging Paragraphs

This module adds the Hanging paragraph style, that is, one where all but the first
line of the paragraph is indented. This may not appear in your LYX document but
will appear in the final output.
4.14.3 Initials (Drop Caps)
his module adds a drop capitals paragraph style Initials for paragraph environ-
T ments which you can use wherever you want to have drop capitals. You then
2
These commands are internally used for all shapes described here.

79
4 Modules

have three more items in the Insert menu:

• Initial which creates an inset for the drop capital

• Rest of initial which creates an inset for the rest of the word

• Options which allow you configure the formatting of the drop capital.

To customize the appearance of the style, see Help ▷ Embedded Objects ▷ Objects
Surrounded by Text ▷ Initials.

4.15 Text Markup

4.15.1 Hyphenatable Text Markup (Soul)
This module defines text styles to highlight, space-out, strike-through, underline and
capitalize/small-cap text by means of the soul package.
As opposed to the markup provided by the Text Properties dialog, words marked-
up with soul are hyphenated. See the soul documentation.

4.15.2 Logical Markup

This module defines some character styles for logical markup: noun, emph, strong,
and code which are accessed via the Edit ▷ Custom Text Styles menu.

80
5 Bibliography
The most basic information about how to use BibTEX or Biblatex with LYX is con-
tained in the section Bibliography databases of the User’s Guide. The following sub-
sections explain special bibliography features supported by LYX.

5.1 Alternative Citation Styles

Standard BibTEX uses numbers (e. g. “[12]”) to refer to a cited work. However, in
many scientific disciplines, other citation styles are in use. The most common one
is the author-year style (e. g. “Knuth 1984a”). LYX supports three packages that
provide this style, biblatex, natbib, and jurabib. Each of these packages has their
pros and cons, which cannot be listed in detail. If you only want to have simple
author-year (or author-numerical) style, or if you want to use one of the countless
style files for natbib, then the established natbib package is probably your choice.
If you look for specific citation styles common in law studies, you might consider the
jurabib package. If you want to have full control over the formatting or look for
advanced features such as ibidem, footnote citations, full title citations, advanced
date formats (such as 400 BC) or full localization to other languages than English,
you should definitely consider biblatex, which exceeds all other packages in terms
of features, but is also quite heavy and more resource-hungry.
The handling of these packages in LYX is basically the same. Go to Document ▷
Settings and select under Bibliography the Style Format Basic (BibTeX), Biblatex, Bibla-
tex (Natbib mode), Natbib (BibTeX) or Jurabib (BibTeX) (see sec. 6.5.3 in the User’s
Guide for more information on these choices). With all these packages, you will get
some extra features in the citation dialog and you can select the style of the reference
(“Knuth 1984”, “Knuth (1984)”, “Knuth, 1984”, “1984” etc.). Note that either pack-
age needs specifically designed style files. They all ship their own, but there are lots
of additional style files, and there is even an interactive style file builder1 for natbib.

5.2 Subdivided Bibliographies

Sometimes you might need to divide your bibliography into several sections. If you
are for instance a historian, the possibility to separate sources and scientific works
is most likely a “must have”. Unfortunately, BibTEX itself does not allow you to do
1
See ftp://ctan.tug.org/tex-archive/macros/latex/contrib/custom-bib/

81
5 Bibliography

this. But with the help of some LATEX packages, BibTEX can be extended to fit your
needs.
LYX provides native support for one of these packages, bibtopic.2 The advantage
of this package (compared to other packages such as multibib) is that you don’t need
to define new citation commands. Instead, you need to prepare different bibliographic
databases which include the entries for the different sections of the bibliography.
For example: If you want to divide your bibliography into the sections “Sources”
and “Scientific works”, you first need to create two bibliographic databases, e. g.
sources.bib and scientific.bib.
Go to Document ▷ Settings and check under Bibliography the option Subdivided bib-
liography. Now you can insert multiple BibTEX bibliographies, one for each section
of your bibliography. Returning to our example: Insert the BibTEX bibliography
sources.bib and a second one for the database scientific.bib. You are free to
use the same or different styles for each section. Additionally, you can choose if the
bibliography section should contain “all cited references” of the specified database(s)
(which is the default), “all uncited references” or even “all references”. This might
be useful if you would like to separate your bibliography into three sections: “Cited
sources”, “Uncited sources”, and “Scientific works”. The titles for the sections can be
added as ordinary sections or subsections. Since bibtopic removes the bibliography
title, you have to manually re-add that, too (as a chapter* or section*, for instance).
With Biblatex, the procedure is a bit different. Since bibtopic does not work
with Biblatex, the aforementioned Subdivided bibliography option is disabled
if you use Biblatex. However, Biblatex provides its own means to generate subdi-
vided bibliographies. You can either add keywords to bibliography entries via the
keywords entry option and then filter bibliography sections by keyword (by adding
keyword=mykeyword to the Options field of the dialog that opens if you left-click on
the Biblatex Generated Bibliography button), or you can filter by entry types
(such as book or article) by entering e. g. type=book or nottype=collection to the
mentioned Options field, or you can create so-called “Bibliography Categories” to
which you can assign individual entries. Please refer to the Biblatex manual, section
Subdivided Bibliographies, for details.

5.3 Multiple Bibliographies

Multiple bibliographies, e. g. a bibliography for each part, chapter, section, subsection
or child (sub-document) of the document, are also supported by LYX. In order to en-
able it, go to Document ▷ Settings ▷ Bibliography and select the relevant unit (e. g., “per
section”) in the Multiple Bibliographies combo box. Then add a Bib(la)TEX
bibliography to each unit (e. g., section) of your document. In the output, a separate
bibliography, containing only the references done in the current unit is generated.
If you use BibTEX, either the chapterbib or the bibtopic package is used to create
multiple bibliographies. The former package is used if you select “per child document”
2
Available from ftp://ctan.tug.org/tex-archive/macros/latex/contrib/bibtopic/

82
 5.3 Multiple Bibliographies

and do not check Sectioned Bibliography. In all other cases, bibtopic is used.3
If bibtopic is used, LYX encloses the specified units in bibtopic’s \begin{btUnit}
and \end{btUnit} in order to create the units. Note that this approach has some
limitations. First, every citation reference has to be inside some btUnit. So citations
outside a defined unit (e. g., before the first section if you use “by section”) will
appear as “???”. You can also create your own units by entering \begin{btUnit} and
\end{btUnit} as TEX code (for instance to work around the mentioned limitation).
Note, though, that btUnits cannot be nested. A second limitation is that bibtopic
always processes all references of a bibliography database, even if they are not cited.
This can result in odd labels (e. g. “Miller 2014b” if two works of this author from
2014 are in the database, even if only one is cited).
If you use Biblatex, the refsection option is used instead. If you need specific
units, you can start them with the TEX code \newrefsection or \newrefsegment,
respectively. If you also want to control the end of the unit, use the environ-
ment \begin{refsection} . . . \end{refsection} instead. Note, though, that
refsections cannot be nested. In addition to the individual bibliography of the
current unit, Biblatex also provides an easy way to output all bibliographies, subse-
quently, at one place (e. g., at the end of the document). Select “all reference units”
from the Content combo box of the Bib(la)TeX inset dialog in order to achieve this.
Please refer to the Biblatex manual for more information on this topic.

3
An alternative approach, if you are willing to use some TEX Code (see section 2.3), is to use the
bibunits package.

83
6 Bullets
by Allan Rae

6.1 Introduction
LYX provides 216 bullet shapes that can be accessed from a simple dialog. Using this
dialog you can easily specify what bullet shape to use at each level of an itemized
list. These settings are document-wide so you won’t be able to specify different sets
of bullets for different paragraphs.1

6.2 How it looks

Open the dialog by selecting the Document ▷ Settings menu item and then select the
Bullets tab.
The dialog provides you with a table of bullet shapes. A column of buttons on the
left of the table provides access to the six different panels of bullet shapes. The row
of buttons across the top is used to select which bullet depth you are changing.
If you select Custom bullet, a text entry under the table will be activated in which
you can enter a bullet shape’s LATEX equivalent. If you do modify the text you will
also need to specify any needed packages in the LATEX preamble.
The six panels are divided up by the packages they require. The following table
shows the mappings from button name to LATEX package.

Button Packages Required

Standard base LATEX
Maths amssymb.sty
Ding1 pifont.sty
Ding2 pifont.sty
Ding3 pifont.sty
Ding4 pifont.sty

LYX doesn’t stop you using bullets from packages you don’t have. If you get errors
from LATEX when you try to view or print the file, then it is likely you are missing a
package.2
1
Well, actually you can but you’ll have to do it by hand.
2
LYX doesn’t restrict your use since you may be editing locally and exporting elsewhere.

85
6 Bullets

6.3 How to use it

Select which bullet depth you want to change then select the bullet shape and size.
Any changes will not be visible in LYX, but are visible when viewing the document.
You can reset a bullet shape to the default simply by clicking your right mouse
button on the appropriate bullet depth button.
If you really want to have multiple sets of paragraphs with different sets of bullets
in each, then you’re going to have to get your hands dirty with TEX code. The bullet
selection dialog can help though because it provides you with the LATEX code for a
wide range of bullet shapes. To make your own custom paragraphs you have the
following options:

♯ Use the LATEX command \renewcommand to specify a new bullet shape for a
given depth. You’ll also need to save the current bullet shape so you can restore
it again afterwards. In this itemized list the following LATEX code was used to
change the bullet used for the first depth.
\let\savelabelitemi=\labelitemi
\renewcommand\labelitemi[0]{\small\(\sharp\)}

♯ Note that the itemize depth is specified in Roman numerals as part of the
\labelitem command.

⋆ Specify each individual entry by starting each item with the bullet shape en-
closed in a “Custom Item” inset (available at Insert ▷ Custom Item) and set as
TEX Code. For example, this item was started with \(\star\).

You’ll also need to revert the labelitem back to its previous setting for the global
bullet shape settings to remain in effect. The way used here was:

\renewcommand\labelitemi[0]{\savelabelitemi}

86
7 Supplemental Tools
7.1 Multipart Documents
7.1.1 General Operation
When you are working on a large file with many sections, it is often convenient to
break up the document into several files, or perhaps you have something where a table
may change from time to time, but the preceding text does not. In these cases, you
should seriously consider using multipart documents. For example, scientific papers
often have five major sections: the introduction, observations, results, discussion, and
conclusion. Each of these could be its own separate LYX file, with one “master” file
which contains the title, authors, abstract, references, etc., plus the five included files.
It is important to note that each of these files is a full LYX file which can be formatted
and printed on its own, as well as included in a master file. Each of these files must
have the same document class, however—don’t attempt to mix book classes with
article classes. You may also include LATEX files; however, these files must not have
their own preamble (i. e. everything up to and including the \begin{document} line
as well as the \end{document} line must be deleted) or else errors will be generated
when you try to make a DVI file.
LYX allows you to include files quite easily with Insert ▷ Child Document. When
you click on this selection a small box is inserted into the file at the current cursor
location. Clicking on the box raises a dialog which allows you to select the file to be
included, and the method of its inclusion.
The file selection box should by now be obvious. The three inclusion methods are
“include”, “input”, and “verbatim”. The methods “include” and “input” are similar
in many ways, but there are also some notable differences:

1 Files that are “included” are typeset beginning on a new page, while files that
are “inputted” are typeset starting on the current page.

2 “Included” files cannot themselves “include” further files (“grandchilds”). With

“input”, on the other hand, infinite sub-inputting is possible.

3 “Include” allow for the output of only selected “included” files, while maintain-
ing the actual counters (pagination etc.) and references (please refer to the
section Child Documents of the Embedded Objects manual for details).

Hence, “include” is the preferred method for chapters that are outsourced to child
documents, while “input” is more suitable for arbitrary file inheritance.

87
7 Supplemental Tools

A “verbatim” included file allows you to include a file typeset exactly as it ap-
pears in the file, i. e. in verbatim mode, with the characters set in a fixed-width
typewriter font. Normally, spaces in this file are invisible, though two consecutive
spaces are conserved, unlike LYX’s normal treatment of spaces. However, setting the
Mark spaces in output checkbox typesets a mark to unambiguously define the
presence of a space.
Generally, the master file is converted into a full LATEX file before typesetting,
while the included files are converted to LATEX files that do not have all the preamble
information.

7.1.2 Cross-References Between Files

This section is somewhat out of date. Need to describe default master documents
and how children are opened when the master is. [[FIXME]]

It is possible to set up cross-references between the different files. First, open

all the files in question: let’s call them A and B in a two file example, where B is
included in A. Let’s say you insert a label in A, then want to reference it in B. Open
the cross-reference dialog whilst in document B, and you can select the “buffer” to
use.

7.1.3 Bibliography Lists in all Subdocuments

If you work with child documents, you might want to have only one main bibliography
at the end, but still be able to have a selected bibliography for the child if you output
it on its own. Here is how to achieve this.
For the main document, you just insert a bibliography inset at the place where the
main bibliography has to appear (within the master file or within a child). If the
bibliography inset is in the master file, the references will be inherited by all children,
so they are available in the citation dialog within each child.
For child-specific bibliographies, insert bibliography insets within the child docu-
ments, at the place where the bibliography should appear when the child is com-
piled separately. However, the trick is to insert them into a branch (Insert ▷ Branch ▷
Insert New Branch...), e. g. called “Childonly”. Within the children, activate the
branch (Document ▷ Settings... ▷ Branches). Within the master, deactivate the branch
(Document ▷ Settings... ▷ Branches). Now the child’s bibliography will be ignored by
the master, but considered by the child.
If you need multiple bibliographies (e. g., one per child in the main document),
please refer to sec. 5.3.

7.2 LYX Archives

Users sometimes need to be able to “bundle” a LYX file together with all the images
(and other files) on which it depends, either for sending to a publisher or for sharing

88
 7.2 LYX Archives

with a co-author. LYX includes a Python script (lyxpak.py) that automates this
process. To use it, you must have either the zipfile or tarfile python modules
installed on your system. By default, the script prefers the gzip-compressed tar
format on Unix-like systems and the zip format on Windows.
LYX’s configuration process will set the script up to export a ‘LYX Archive’, and
this format will then be available under File ▷ Export.
Independently of the platform, the generation of a particular archive format can be
forced by adding either the -t (for the tar format) or -z (for the zip format) switch
to the LYX->LYX Archive converter in Tools ▷ Preferences ▷ File Handling ▷ Converters.
(Make sure you add the switch after the script name, not before it.)

89
8 LYX and the World Wide Web
LYX has long supported the export of documents to various web-friendly formats, such
as HTML. Before version 2.0, however, HTML export was always accomplished by the
use of external converters.1 These fall into two large groups: there are converters that
use LATEX as an intermediate format, such as htlatex, html2latex, and plastex,
relying upon LYX to produce the LATEX; and there is a converter that works directly
on LYX files, eLYXer. All of these have different advantages and disadvantages.
The LATEX-based converters have the advantage that, in principle, they know ev-
erything about the exported document that LATEX does. Such converters do not care,
for example, if a certain block of code was produced by LYX or was Evil Red Text.
These converters know about aux files, counters, and references, and can often make
use of the bbl files generated by BibTEX. On the other hand, LATEX is a very hard
language to parse—it is sometimes said that only TEX itself understands TEX—and
LATEX-based converters will often choke on what seem to be quite simple constructs;
complex ones can throw them completely, and as of this writing, for example, the
Embedded Objects manual will not export with htlatex, though the others will. The
other issue concerns how math is handled. These converters typically convert the for-
mulae into little pictures that are then linked from the HTML document. Since these
are actually generated by LATEX, they are accurate. But they do not scale well, and
just getting them to look as if they are actually meant to be in your document—so
that the font sizes seem to be roughly the same—can be a challenge.
Alex Fernandez’s eLYXer (http://pinchito.es/elyxer/) solves some of these prob-
lems. In particular, the formulae it produces scale perfectly, since it renders math
using a combination of HTML and CSS rather than converting the formulae to images.
But even moderately complex formula are rendered less well than with htlatex; this
reflects the limitations of HTML.2 More importantly (as of version 1.1.1, at least),
eLYXer has limited support for math macros and no support for user-defined para-
graph or character styles. These limitations make eLYXer unsuitable for many of the
documents LYX users produce. In principle, of course, these problems could be solved,
but the LYX developers have decided to follow a different path and have made LYX
itself capable of writing XHTML, just as it is capable of writing LATEX, DocBook,
and plaintext.
As of this writing, XHTML output remains under development and should prob-
1
For details on the use of external converters with LYX, see the Converters section of the Cus-
tomization manual.
2
That said, eLYXer can also use jsMath and MathJax for equations, but this setting is only available
globally and requires one to have access to a server that runs the backend.

91
8 LYX and the World Wide Web

ably be regarded as “experimental”.3 Still, the developers have chosen this approach
because it has several potential advantages over the other two.
These advantages are primarily due to the fact that the XHTML output routines,
since they are part of LYX, know everything LYX knows about the document being ex-
ported.4 So they know about the table of contents (as displayed in the outline), about
the counters associated with different paragraph styles, and about user-defined styles.
The XHTML output routines know what LYX knows about internationalization, too,
so they will output “Chapter 1” or “Kapitel 1”, depending upon the language in effect
at the time.
Quite generally, the output routines know what LYX knows about document layout,
that is, about how the document is to be rendered on screen. We use this information
when we output the document as XHTML. In particular, LYX automatically generates
CSS style information corresponding to the layout information it uses to render the
document on screen: if section headings are supposed to be sans-serif and bold as
seen in LYX, then (by default) they will be sans-serif and bold when viewed in a web
browser, too. And this is true not just for pre-defined styles, like Section, but for
any style, including user-defined styles. Indeed, the XHTML output routines make
no distinction between user-defined paragraph and text styles and LYX’s own pre-
defined styles: in each case, everything LYX knows about the styles is contained in
the layout files. And much the same is true as regards pre-defined textual insets,
such as footnotes, and various custom insets.
The result is that XHTML output can be customized and extended in exactly the
same way LATEX output can be customized and extended: through layout files and
modules. See chapter five of the Customization manual for the details.
The remainder of this chapter contains more detailed information on XHTML
output, its limitations, and ways to work around those limitations.

8.1 Math Output in XHTML

LYX offers four choices for how math is rendered. These have various advantages and
disadvantages:

• MathML
MathML is a dialect of XML designed specifically for mathematics on the web,
and it typically renders very well in browsers that support it. The disadvantage
is that not all browsers support MathML, and support is not complete even in
the Gecko-based browsers, such as Firefox.
If LYX is unable to render a formula as MathML—for example, if the formula
3
The file development/HTML/HTML.notes, which can be found in the LYX source tree or accessed
online, usually contains up-to-date information about the state of XHTML output. See also the
list of XHTML bugs on the bug tracker.
4
Another advantage is that, since these routines are internal to LYX, they are immune to changes
in LYX’s file format, or to changes in the semantics of existing insets.

92
 8.2 Bibliography and Citations

uses the xymatrix package or ERT—then it will instead output the formula as
an image.

• HTML
As mentioned above, elyxer outputs math as HTML, styled by CSS.5 For sim-
ple formulae, this can work quite well, though with more complicated formulae
it tends to break down. Still, this method has the advantage that it is very
widely supported and so it may be appropriate for documents that contain
only a little, fairly simple math.
If Lyx is unable to render a formula as HTML—for example, if the formula uses
the xymatrix package or ERT—then it will instead output the formula as an
image.

• Images
Like htlatex, LYX will output formulae as images, the very same images, in
fact, that are used for instant preview.6 The advantage to this method is that
the images are simply generated by LATEX, so they are very accurate. The
disadvantage, as mentioned earlier, is that these are bitmapped images, so they
do not scale terribly well, and one cannot copy them, etc.
The size of the images can be controlled by setting the “Math Images Scaling”
parameter under Document ▷ Settings ▷ Output ▷ HTML.7
If LYX for some reason fails to create an image for a formula (e.g., if a required
LATEX package is not installed), then it will fall back to outputing the raw LATEX.

• LATEX
Finally, LYX will happily output math as LATEX. As well as being the output
of last resort, this method can be used with such tools as jsMath, which uses
JavaScript to render LATEX embedded in HTML documents. LYX wraps the
LATEX in either a span (for inline formulas) or div (for displayed formulas)
with class=’math’, as is required for jsMath.

One of these output methods must be selected under Document ▷ Settings ▷ Formats.
By default, LYX outputs MathML. This is a document-wide setting, therefore.
Eventually, LYX will offer the user the option to select an alternate output method
for a particular inset, say, one that isn’t being rendered very well by MathML.8

8.2 Bibliography and Citations

XHTML output fully supports bibliographies and citations.
5
LYX has borrowed some of the CSS for its HTML output from elyxer.
6
Instant preview does not have to be on for images to be output, however.
7
For those who want to know, this controls the resolution of the image in dots per inch and is
based upon a default of 75 dpi.
8
That said, since LYX falls back to images if the inset contains ERT, then one can force output as
an image by putting some harmless ERT into the math, for example: a = b.

93
8 LYX and the World Wide Web

Citation labels are generated by the same machinery that generates LYX’s on-
screen labels, so the labels will look in the output much as they do in LYX, though
better. If you are using numerical citations, then LYX will output numerical labels,
such as [1] or [17], rather than simply showing the citation key in square brackets, as
it does on-screen. If you are using author-year citations, then LYX will add lowercase
letters to the years, just as BibTEX does, if it finds more than one citation for a given
author-year combination. The labels will be printed with the bibliography entries.
Note that there is, at present, no way to customize the appearance of the labels, for
example, to choose between square brackets and parentheses.
Bibliography output is handled by the same machinery that handles the presenta-
tion of reference information in the citation dialog, so you will see in the XHTML
output pretty much what you would see if you were to look at a given entry in the
citation dialog. The formatting can be customized in your layout file or, preferably,
in a module. See the Customization manual for the details.
The main defect at present is that cross-referenced information is printed with
every entry with which it is associated. So you can see things like this:

Jason Stanley, “Context and Logical Form”, in Language in Context: Se-

lected Essays (Oxford: Oxford University Press, 2007), pp. 30–68.
Jason Stanley, “Semantics in Context”, in Language in Context: Selected
Essays (Oxford: Oxford University Press, 2007), pp. 201–30.

This should be fixed before long.

There is no support at present for sectioned bibliographies. If you have multiple
bibliographies, then LYX will print the same bibliography over and over.

8.3 Indexes
LYX will happily export indexes as XHTML, but with certain limitations at the
moment.
Index export will be most reliable when you do not attempt to use the fancy
constructs that are described in the section on indexes in the User’s Guide.9 We’ll
describe how they are handled using the subsection headings from that section.

• Grouping Index Entries (aka, sub-entries): LYX makes an effort to support

these, but the entries must be separated by “ ! ”, that is, there must be spaces
around the exclamation point. This is because it is otherwise too difficult to
check for escaped exclamation points, ones in math, and so forth.

• Page Ranges: There is no support at all for page ranges, since these make no
sense with XHMTL. Instead, you will just get two index entries, one at either
end.
9
The main issue here is that LYX itself does not really handle these. It just lets you enter what
you would have to enter in raw LATEX.

94
 8.4 Nomenclature and Glossary

• Cross-referencing: There is no support for cross-referencing. If LYX finds an

entry containing the “|see. . . ” construct, it is just dropped, and the rest is
treated as an ordinary index entry.

• Index Entry Order: LYX does support attempts to fix the sorting order. It will
take what is before the first ‘@’ it finds and use that for sorting, taking what
follows the first ‘@’ to be the actual entry. At present, LYX does not check for
escaped ‘@’, so do not try to index email addresses.

• Index Entry Layout: You can format entries by using the text style dialog, or
by using any other method available within LYX itself. There is no support for
constructs like: “entry|textbf”. Indeed, if LYX finds a pipe symbol, ‘|’, in an
entry, it will delete it and everything that follows it.

• Multiple Indexes: There is no support for multiple indexes. Rather, all index
entries will be printed as one large index. To avoid our printing several versions
of the index, we print only the main index, so make sure you have one.

8.4 Nomenclature and Glossary

There is at present no support for glossaries. Adding it would be fairly trivial, and
welcome.

95
9 DocBook Output
Apart from HTML, LYX can generate documents in the DocBook XML vocabulary.
With versions 2.3 and before, only select templates could be used to generate Doc-
Book documents (only version 4). Starting with LYX 2.4, most LYX layouts can
generate valid DocBook documents (only version 5). This feature is built into LYX
and does not require the use of external tools.
The result is that the DocBook output can be customized and extended in exactly
the same way LATEX output can be customized and extended: through layout files
and modules. See chapter five of the Customization manual for the details.
Most LYX features are supported with DocBook, like math output.

• Math output is performed mostly in MathML (the major exception being con-
structions not supported by LYX, i.e. ERTs). All formulae are also available in
raw TEX in the DocBook output for further processing.

• Bibliographies and citations are implemented, including with an external Bib-

TeX file. Bibliography entries are not prerendered when the detailed informa-
tion are available, but rather output with the standard DocBook constructs.
The external DocBook processor is expected to handle the rendering of entries.

• Indexes are supported, including multiple indices. Grouping (with !), page
ranges, and cross-references (|see) are supported, with the exception of the
same symbols escaped. Entry order (@) and layout (|mathbf) are not supported.
There is no support for escaping of index entries.

• Glossaries are implemented.

Two major parameters can be set at the document level.

• Format for tables: LYX can generate tables either as HTML (default value) or
CALS, depending on the user’s requirements. Most DocBook processors accept
both formats.

• MathML prefix: in DocBook, MathML is included within its own name space,
unlike HTML. The implication is that there must be an indication of the tags
belonging to the MathML standard. Three choices are offered:
– Inline: the MathML name space is defined for each formula (using the
xmlns attribute on each formula)

97
9 DocBook Output

– With the m prefix (default): the MathML name space is defined at the
document level (using the xmlns:m attribute on the root element). Each
MathML is prefixed with m: for instance, m:math
– With the mml prefix: similar to the m option, but with mml
This option is especially useful if you want LYX to match your personal style
or to work with buggy software that only accepts one prefix for MathML.

98
10 The LYX Server

10.1 Introduction
The ‘LYX server’ allows other programs to talk to LYX, invoke LYX commands, and
retrieve information about the LYX internal state. This is only intended for advanced
users, but they should find it useful. It is by writing to the LYX server, for example,
that bibliography managers, such as JabRef, are able to “push” citations to LYX.

10.2 Starting the LYX Server

The LYX server works through the use of a pair of named pipes. These are usually
located in UserDir, (except on Windows, where local named pipes are special objects
located in \\.\pipe) and have the names “lyxpipe.in” and “lyxpipe.out”. Ex-
ternal programs write into lyxpipe.in and read back data from lyxpipe.out. The
stem of the pipe names can be defined in the Tools ▷ Preferences ▷ Paths dialog, for ex-
ample "/home/myhome/lyxpipe", or "\\.\pipe\lyxpipe" on Windows (where any
working path instead of lyxpipe can be used, for example "\\.\pipe\my\lyx\pipe"
would also work). You must configure this manually in order for the server to start.
LYX will add the ’.in’ and ’.out’ to create the pipes. If one of the pipes already
exists, LYX will assume that another LYX process is already running and will not
start the server. On POSIX (Unix like) systems, if for some other reason, an unused
“stale” pipe is left in existence when LYX closes, then LYX will try to delete it. If
this fails for some reason, you will need to delete the pipes manually and then restart
LYX. On Windows, pipes are deleted by the OS on program termination or crash, so
“stale” pipes should not be possible.
To have several LYX processes with servers at the same time, you have to use
different configurations, perhaps by using separate user directories, each with its own
preferences file, for each process.
If you are developing a client program, you might find it useful to enable debugging
information from the LYX server. Do this by starting LYX as lyx -dbg lyxserver.
You can find a complete example client written in C++ in the source distribution
as development/lyxserver/server_monitor.cpp.
Another useful tool is the command-line based client found in src/client/lyxclient.

99
10 The LYX Server

10.3 Normal communication

To issue a LYX call, the client writes a line of ASCII text into the input pipe. This
line has the following format:

LYXCMD:clientname:function:argument

clientname is a name that the client can choose arbitrarily. Its only use is that LYX
will echo it if it sends an answer—so a client can dispatch results from different
requesters.

function is the function you want LYX to perform. It is the same as the commands
you’d use in the minibuffer.

argument is an optional argument which is meaningful only to some functions (for

instance, the “self-insert” LFUN will insert the argument as text at the cursor
position).

The answer from LYX will arrive in the output pipe and be of the form

INFO:clientname:function:data

where clientname and function are just echoed from the command request, while data
is more or less useful information filled according to how the command execution
worked out. Some commands, such as “font-state”, will return information about the
internal state of LYX, while other will return an empty data-response. This means
that the command execution went fine.
In case of errors, the response from LYX will have this form

ERROR:clientname:function:error message

where the error message should contain an explanation of why the command failed.
Examples:

echo "LYXCMD:test:beginning-of-buffer:" >~/.lyxpipe.in

echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in
read a <~/.lyxpipe.out
echo $a

10.3.1 AppleScript (Mac OS X)

Since LYX 2.1, LYX supports basic interactions with AppleScript for normal com-
munication through the command run. This command takes a direct argument (the
function to perform) and an optional argument. It either returns the output of the
function or triggers an error with the error message and code.
Example:

100
 10.4 Notification

tell application "LYX"

try
-- Stores the current file name into f
set f to (run "server-get-filename" with argument "")
on error the error_message number the error_number
display dialog "Error: " & the error_number & ". " ¬
& the error_message buttons {"OK"} default button 1
end try
end tell

10.4 Notification
LYX can notify clients of events going on asynchronously. Currently it will only do
this if the user binds a key sequence with the function “notify”. The format of the
string LYX sends is as follows:

NOTIFY:key-sequence

where key-sequence is the printed representation of the key sequence that was actually
typed by the user.
This mechanism can be used to extend LYX’s command set and implement macros.
Bind some key sequence to “notify”. Then start a client that listens on the output
pipe, dispatches the command according to the sequence, and starts a function that
may use LYX calls and LYX requests to issue a command or a series of commands to
LYX.

10.5 The simple LYX Server Protocol

LYX implements a simple protocol that can be used for session management. All
messages are of the form

LYXSRV:clientname:protocol message

where protocol message can be “hello” or “bye”. If “hello” is received from a client,
LYX will report back to inform the client that it’s listening to it’s messages, while
“bye” sent from LYX will inform clients that LYX is closing.

10.6 Reverse DVI/PDF search

Some DVI/PDF viewers1 provide reverse search facility (also called inverse search).
This means that you can tell LYX to put the cursor to a specific line in the document
1
The following viewers offer the reverse PDF search feature: Okular on KDE/Linux, Qpdfview on
Unix, Skim on Mac OSX and SumatraPDF on Windows.

101
10 The LYX Server

by clicking at the respective position in the DVI/PDF output. To achieve this, the
viewer must be able to communicate with LYX. This is done via the LYX server either
by using the named pipe (lyxpipe), or the UNIX domain socket (lyxsocket) that LYX
creates in its temporary directory (this is the way the lyxclient program commu-
nicates with LYX). In some cases, you need a helper script that mediates between
the viewer and LYX, in others, the viewer can communicate with LYX directly. This
depends on the selected viewer and on your operating system. The same applies to
the way viewers need to be configured and the way the reverse search is actually
performed. In what follows, we will thus describe how to setup reverse search for
specific viewers. Before we turn to this, though, we will explain what needs to be
done generally to enable reverse search in the DVI/PDF output.

10.6.1 Automatic setup

In most cases LYX will do the work for you by pressing the following button in the
toolbar: . Alternatively, you can also enable the feature by checking Synchronize with
Output in Document ▷ Settings ▷ Output ▷ LaTeX. In such a case LYX will automatically
insert the necessary SyncTEX macro (for PDF) or load the srcltx package (for DVI)
respectively. This option can be easily reached also on View/Update Toolbar.
If you need a different setting, you can select or input a custom macro from the
drop down box just below Document ▷ Settings ▷ Output ▷ Synchronize with Output.
Note that the method \synctex=1 enables gzip compression. If your viewer does
not support it, you should instead use \synctex=-1.
Please also note that including the srcltx package or src-specials sometimes
has an undesired impact on the typesetting. Thus, you should switch output synchro-
nization off for the final typesetting if you use the srcltx package or src-specials.
In case you need some more special settings that are not covered by the automatic
settings, read the next section about how to set up output synchronization manually.
If the automatic setup suits your needs, you can readily jump to section 10.6.3, where
the necessary configuration steps in your viewer – needed both with the automatic
and the manual setup – are described.

10.6.2 Manual setup

LATEX provides several different methods for reverse search. Some are built-in in
the latex/pdflatex program, some are provided by external packages. Your choice
depends on whether your LATEX distribution already provides a given method (the
built-in methods are rather new) and whether your viewer can cope with it. The
available methods are described in the following.

Built-in DVI-search via src-specials (DVI only)

This method provides the DVI file with the necessary information for reverse search.
It is available in LATEX since quite some time (any somewhat recent LATEX distribution

102
 10.6 Reverse DVI/PDF search

should include it), and it works reliably. To enable it, change the LaTeX (plain)-
>DVI or LaTeX (plain)->DraftDVI converter in Preferences ▷ File Handling ▷
Converters to latex -src-specials $$i. If this doesn’t work, check if your TEX
engine needs different options (the syntax might differ in some distributions).

External Packages (PDFSync and scrltx)

The packages pdfsync and scrltx provide reverse search facility for PDF output (via
pdflatex) and DVI output, respectively. In order to enable it, load the packages in
the LYX preamble:

• \usepackage{pdfsync} for reverse PDF search,

• \usepackage[active]{srcltx} for reverse DVI search.

If you want to be able to perform both DVI and PDF reverse searches, you can also
insert in the preamble the following lines

\usepackage{ifpdf}
\ifpdf
\usepackage{pdfsync}
\else
\usepackage[active]{srcltx}
\fi

This way, you can preview the file as either DVI or PDF (pdflatex) and the right
package will be used.
Note that PDFSync might affect the output layout of your document. It is therefore
advised to disable PDFsync for final documents.

Built-in reverse search via SyncTEX (DVI and PDF)

Recent versions of (pdf)latex have built-in support for both PDF and DVI reverse
search. This so-called SyncTEX facility is basically the result of the integration of
the PDFSync package to the pdftex program and its merge with the scr-specials
approach. You need at least TEXLive 2008 or a recent MikTEX distribution in order
to use it.2 Also note that only a few PDF viewers (such as Okular and Qpdfview on
Unix, Skim on the Mac, SumatraPDF on Windows; see the next section for details)
already provide SyncTEX support.
2
For some reason, MikTEX does not understand/obey the command LYX inserts into the pream-
ble when you check the "Enable Forward/Reverse Search" button in the toolbar and does not
generate the necessary info.
The generation of the required info can be forced by changing the converter "LATEX (pdflatex)
-> PDF (pdflatex)" in Preferences->File handling->Converters from the default "pdflatex $$i"
to "pdflatex -synctex=1 $$i" (i.e., by adding the -synctex=1 switch).

103
10 The LYX Server

To enable SyncTEX for DVI output, change the LaTeX (plain) -> DVI or
LaTeX (plain) -> DraftDVI converter in Preferences ▷ File Handling ▷ Converters
to latex -synctex=1 $$i, and for PDF output, change the LaTeX (pdflatex)
-> PDF (pdflatex) converter to pdflatex -synctex=1 $$i. Should your viewer
not be considered in the following description, or in case of missing success, please
check the documentation of your viewer whether the viewer needs to be configured
for the use with SyncTEX.3

10.6.3 Configuring and using specific viewers

Xdvi (all platforms)
If you use xdvi, you don’t need to do anything else for performing a reverse DVI
search, as LYX already provides the necessary hooks for automatically using the
lyxclient program. Just setup your document as described above (reverse search is
triggered by Ctrl-click or Alt-click on Mac OSX, respectively).
However, if for whatever reason you want to use the named pipe instead of the
socket for communicating with LYX, simply change the DVI viewer in Preferences ▷ File
Handling ▷ File formats to4 xdvi -editor "lyxeditor.sh %f %l", where lyxeditor.sh
is a suitable script. For example, a minimal shell script is the following one:

#!/bin/sh
LYXPIPE="/path/to/lyxpipe"
COMMAND="LYXCMD:revdvi:server-goto-file-row:$1 $2"
echo "$COMMAND" > "${LYXPIPE}".in || exit
read TMP < "${LYXPIPE}".out || exit

where /path/to/lyxpipe is the LyXServer pipe path specified in Preferences ▷ Paths.5

MacDviX (Mac OSX)

At the end of /Applications/MacDviX_Folder/calleditor.script, add the fol-
lowing lines:

/Applications/LyX.app/Contents/MacOS/lyxeditor "$2" $1
exit 1

Modify the lines accordingly if you install LYX somewhere else than in the Applica-
tions folder.
Reverse search is triggered by Alt-click (OPTION-click).
3
Note that the option -synctex=1 option enables gzip compression. If your viewer does not support
it, you should instead use -synctex=-1.
4
On Mac OSX you have to use DISPLAY=:0.0 xdvi -editor "lyxeditor.sh %f %l"
5
In the development/tools folder of a source distribution you can find a lyxeditor script which
is able to locate the lyxpipe based on your preferences.

104
 10.6 Reverse DVI/PDF search

Skim (Mac OSX)

Enter open -a Skim.app $$i to the viewer setting in Preferences ▷ File Handling ▷ File
formats ▷ PDF (pdflatex), and then in Skim ▷ Preferences ▷ Sync choose custom preset
and enter command /Applications/LYX.app/Contents/MacOS/lyxeditor.
Reverse search is triggered by COMMAND-SHIFT-click

Evince (GNOME)
Reverse search with evince does not work out of the box, but it can be achieved by
means of some third party helper scripts. Please refer to https://wiki.lyx.org/LyX/SyncTeX
for details.

Okular (KDE)
Go to Settings ▷ Configure Okular ▷ Editor and select LyX” as editor. This inserts the
appropriate command (lyxclient -g %f %l).
Reverse search is triggered by SHIFT-click. Note that this only works if Okular is
in “Browse” mode (i. e., the hand symbol is clicked).

Qpdfview (Unix)
Qpdfview supports SyncTEX since version 0.3.5. Go to Edit ▷ Settings ▷ Behavior, click
on the input field of the “Source editor” item and add the command lyxclient -g
%1 %2.
Reverse search is triggered by double-click or, in more recent versions, by context
menu.

YAP (Windows)
Launch yap, choose its View ▷ Options menu and select the “Inverse DVI Search” tab.
Click on the “New. . . ” button and, in the window that opens, enter “LYX Editor”
(or any other name you like) in the “Name:” field. Now click on the button labeled
“. . . ” to open a file dialog and navigate to the directory containing the batch file
lyxeditor.bat (see below). Select lyxeditor.bat and then specify the program
arguments as %f %l. The lyxeditor.bat wrapper is used for communicating with
LYX through the lyxpipe and is as follows:

@echo off
echo LYXCMD:revdvi:server-goto-file-row:%~1 %2> \\.\pipe\lyxpipe.in
type \\.\pipe\lyxpipe.out

Make sure that the LYXServer pipe path you specified in LYX is \\.\pipe\lyxpipe,
otherwise change the lyxeditor.bat wrapper accordingly.
In yap, reverse search is triggered by double-click.

105
10 The LYX Server

SumatraPDF (Windows)
In order to use SumatraPDF for inverse search, enter SumatraPDF -inverse-search
"lyxeditor.bat "%f" %l" in the viewer setting in Preferences ▷ File Handling ▷ File
formats ▷ PDF (pdflatex), where lyxeditor.bat is the previous wrapper. If Suma-
traPDF.exe is not in your command PATH, use its full file name.
Reverse search is triggered by double-click.

YAP (Cygwin)
First of all, make sure that yap is your default DVI viewer in the Windows envi-
ronment, then launch it, choose its View ▷ Options menu and select the “Inverse DVI
Search” tab. Click on the “New. . . ” button and, in the window that opens, enter
“LYX Editor” (or any other name you like) in the “Name:” field. Now click on the
button labeled “. . . ” to open a file dialog and navigate to the directory containing
the lyxeditor.exe program (which is installed by default on Cygwin along with the
LYX executable). Select lyxeditor.exe and then specify the program arguments as
-g %f %l. In this way, you will be using the lyxsocket for communicating with LYX.
If, for whatever reason, you want to use the lyxpipe, omit the -g option and be sure
to specify the LYXServer pipe path in the LYX preferences.
In yap, reverse search is triggered by double-click.

SumatraPDF (Cygwin)
In order to use SumatraPDF for inverse search, enter SumatraPDF -inverse-search
"lyxeditor -g %f %l" in the viewer setting in Preferences ▷ File Handling ▷ File for-
mats ▷ PDF (pdflatex). If SumatraPDF.exe is not in your command PATH, use its
full posix path. The -g enables communication via the lyxsocket. Again, omit the
-g option if you want to use the lyxpipe, and be sure to specify the LYXServer pipe
path in the LYX preferences.
Reverse search is triggered by double-click.

10.7 Forward search

Forward search is, as the name implies, in a sense the “opposite” of reverse search.
It allows you to let the viewer jump to a given position from within LYX. If forward
search is set up (as described in what follows), you can put the cursor anywhere in
your LYX document, and hit Navigate ▷ Forward search (or select Forward search in the
context menu via right mouse click), and then the viewer will jump to that position
as well. This implies, of course, that your viewer supports this function.
To make forward search possible, you first need to provide the generated output
PDF/DVI file with additional information about the TEX sources. This can be done
via the methods described in the section 10.6.1.

106
 10.7 Forward search

Additionally, you need to configure LYX for using your viewers in Tools ▷ Preferences ▷
Output ▷ General. We provide a range of tested configurations for some viewers, which
you can select from the drop down list. If none of these configurations suits you, you
have to find out and enter a suitable configuration yourself. The definition syntax
uses the following placeholders:

• $$n: row number

• $$t: name of the (temporary) exported .tex file (without path)

• $$f: name of the (temporary) exported .tex file (including path)

• $$o: name of the exported output file (either dvi or pdf, depending on which
one exists in the temporary directory)

Note that only some of the viewers provide full and usable forward search functionality
out of the box, among them yap, xdvi, okular6 , qpdfview, and SumatraPDF7 . Others,
such as evince8 , require some extra tools in order to use forward search. While many
of the widespread PDF viewers (most notably Adobe Reader) do not support forward
search at all, some other viewers – e. g. xpdf – allow at least to reload the document
and jump to a specific page of the file, so you can at least navigate “near”. This latter
functionality is provided by an external call of synctex (see the predefined example
configurations).
Forward search works both with DVI and PDF output. LYX simply checks which
preview format you have used before (i. e., which format is already there in the
temporary directory) and chooses the appropriate configuration for the respective
format.

6
You might want to set okular --unique in Tools ▷ Preferences ▷ File Handling ▷ File Formats
7
SumatraPDF can also use DDE commands through the external program CMCDDE — down-
loadable from http://www.istri.fr/spip/zip/CMCDDE.zip
8
Forward search with evince can be achieved by means of third party helper scripts. Please refer
to https://wiki.lyx.org/LyX/SyncTeX for details.

107
11 LYX Features needing Extra
Software
11.1 Checking TEX
by Asger Alstrup

11.1.1 Introduction
If you have the chktex program installed1 , you’ll find in the Tools menu the entry:
Check TeX. You can get chktex from CTAN,
https://www.ctan.org/tex-archive/help/Catalogue/entries/chktex.html.
The ChkTEX package is a program that was written by Jens T. Berger Thiele-
mann in frustration because some constructs in LATEX are sometimes non-intuitive,
and easy to forget. The program runs over your LATEX file, checks the integrity of the
file, and flags some common errors. In other technical words, it is lint for LATEX.
Well, what is a syntax checker doing in LYX which is supposed to produce correct
L TEX anyways? The answer is simple: Just as Lint not only checks the syntax of
A

C programs, but also does semantic checks for type-errors, ChkTEX catches some
common typographic errors, in addition to the syntactical ones. Specifically, ChkTEX
is capable of detecting several common errors, such as
• Ellipsis detection:
Use . . . instead of ...
• No space in front of/after parenthesis:
( wrong spacing )
• Enforcement of normal space after common abbreviations:
e. g. is too wide spacing.
• Enforcement of end-of-sentence space when the last sentence ends with a capital
letter:
This is a TEST. And this is wrong spacing.
• Space in front of labels and similar commands:
2
The label should stick right up to the text to avoid falling to a wrong page.
The label is separated too much.
1
chktex is not yet available when you are using the LATEX distribution MiKTEX.
2
This footnote is in danger of falling off to a wrong page

109
11 LYX Features needing Extra Software

• Space in front of references, instead of hard spaces:

If you have bad luck, the text will break right between the referenced text and
reference number, and that’s a pity. See section 11.1.1.

• Use of “x” instead of × between numbers:

2x2 looks cheap compared to 2 × 2.

and more . . . It is an invaluable tool when you are “finishing up” your document
before printing, and you should run it right after the obligatory spelling check, and
before you go fine tuning the typesetting.

11.1.2 How to use it

If you have the program installed, usage is as simple as choosing Tools ▷ Check TeX.
This will make LYX generate a LATEX file of your document, start ChkTEX to check
it, and then make LYX insert “error boxes” with the warnings from ChkTEX, if there
were any. The warnings will be placed close to the point of the mistake, and you can
quickly find them by using the Navigate ▷ Error menu item, or the shortcut key C-g
from the default cua bind file. Open the error boxes by clicking on them with the
mouse, or use the shortcut key C-i from cua bindings, or the corresponding C-o for
the alternate emacs bind file. Read the warning and correct the mistake, if it is a
mistake. If you have trouble understanding what the warning is about, you can safely
ignore it. Remember that there is a hidden layer between the document on screen
and the technical details in invoking ChkTEX, and this gap can make some warnings
seem arcane or just plain silly.
This document is an excellent testing bed for the feature, and it should provide
quite a few warnings for you to fiddle with. Since computers are only so smart, expect
most of the warnings to be false alarms, though.

11.1.3 How to fine tune it

Sometimes, you’ll find that ChkTEX makes more noise than suits your mood. Then
you can choose not to use it, wait until your mood changes, or try to customize
ChkTEX to get better along with you.
Although ChkTEX is very configurable and extensible, you should not expect to
solve all problems with ChkTEX in LYX this way. Since LYX has to generate a some-
what special LATEX file to be able to match the line numbers from the ChkTEX output3
to the internal document structure, some of the warnings will not appear correctly.
There are two things you can do about this:

• Fine tune the ChkTEX invocation command line in Tools ▷ Preferences ▷ Output ▷
LaTeX ▷ CheckTeX command, or the global ChkTEX installation configuration file
3
You can inspect the specific output from chktex by using Document ▷ LATEX Log right after a chktex
run.

110
 11.1 Checking TEX

(usually with the file chktexrc). See below to learn what warnings can be
enabled and disabled on the command line.

• Export your document as a raw LATEX file using File ▷ Export ▷ LATEX and run
chktex manually on that. Invoked in this way, it can be a hassle to find the
corresponding place in the document inside LYX, but with a little patience, you
should be able to do it.

Here follows the warning messages that can be enabled and disabled in Preferences.
Use -n# to disable a warning, and -w# to enable a warning. The emphasized entries
are disabled by default, because the default is "chktex -n1 -n3 -n6 -n9 -n22 -n25
-n30 -n38".
Notice that you should only use the options that enable and disable warnings,
because LYX relies on some of the other command line parameters to be set in a
specific way to have a chance to communicate with chktex.
1 Command terminated with space.
2 Non-breaking space (“~”) should have been used.
3 You should enclose the previous parenthesis with “{} ”.
4 Italic correction (“\/”) found in non-italic buffer.
5 Italic correction (“\/”) found more than once.
6 No italic correction (“\/ ”) found.
7 Accent command “cmd” needs use of “cmd”.
8 Wrong length of dash may have been used.
9 “%s ” expected, found “%s ”.
10 Solo “%s” found.
11 You should use “%s” to achieve an ellipsis.
12 Inter-word spacing (“\ “) should perhaps be used.
13 Inter-sentence spacing (“\@”) should perhaps be used.
14 Could not find argument for command.
15 No match found for “%s”.
16 Math mode still on at end of LATEX file.
17 Number of “char” doesn’t match the number of “char”.
18 You should use either “ or ” as an alternative to “"”.

111
11 LYX Features needing Extra Software

19 You should use "’" (ASCII 39) instead of "´" (ASCII 180).
20 User-specified pattern found.
21 This command might not be intended.
22 Comment displayed.
23 Either ”\,’ or ’\,” will look better.
24 Delete this space to maintain correct page references.
25 You might wish to put this between a pair of “{} ”.
26 You ought to remove spaces in front of punctuation.
27 Could not execute LATEX command.
28 Don’t use \/ in front of small punctuation.
29 $\times$ may look prettier here.
30 Multiple spaces detected in output.
31 This text may be ignored.
32 Use “ to begin quotation, not ’.
33 Use ’ to end quotation, not “.
34 Don’t mix quotes.
35 You should perhaps use “cmd” instead.
36 You should put a space in front of/after parenthesis.
37 You should avoid spaces in front of/after parenthesis.
38 You should not use punctuation in front of/after quotes.
39 Double space found.
40 You should put punctuation outside inner/inside display math mode.
41 You ought to not use primitive TEX in LATEX code.
42 You should remove spaces in front of “%s”
43 “%s” is normally not followed by “%c”.
In later versions of LYX, we hope to provide a more complete interface to this tool
(and it’s smaller cousin lacheck) to exploit the full power of it. But it’s not exactly
useless as it is now: go try it on one of your existing documents of a certain length
and be surprised.

112
 11.2 Version Control in LYX

11.2 Version Control in LYX

by Lars Gullik Bjønnes and Pavel Sanda

11.2.1 Introduction
LYX supports some of the most basic RCS/CVS/SVN/GIT commands. If you need
something a bit more sophisticated you will have to do that manually in a terminal
or your favourite client.
Also note that CVS support is not as good as subversion support, so we advise
using SVN instead. A good place to start learning Subversion is the SVN Book4 . In
the case of RCS you should read “rcsintro” (a man file, read it with man rcsintro).
This file describes all the basic features of RCS. You should especially notice the
comment about a RCS directory, and the notion of a master RCS file (the file ending
in ,v).
Before you begin to use the version control features in LYX, you should be familiar
with RCS/CVS/SVN/GIT usage. The implementation in LYX assumes a recent
version of the GNU RCS or CVS/SVN package — no guarantees are made for older
versions. Most of the log messages are not currently displayed after operations —
you can check them in the Messages pane if you are unsure. Regular users of version
control will appreciate the VC toolbar, which can be enabled via View ▷ Toolbars ▷
Version Control.
For introducing your own external commands consult vc-command in the manual
LYX Functions.
It is strongly recommended to store documents in uncompressed format if using
version control (uncheck Document ▷ Compressed if it is checked): Uncompressed LyX
documents are text files and therefore for merging two different versions by ver-
sion control systems. Compressed LyX documents are binary files, which cannot be
merged by version control systems. Also to avoid unnecessary merge conflicts we
advise to disable Document ▷ Settings ▷ Output ▷ Save transient properties when more
users work on the same document.

11.2.2 RCS commands in LYX

The following sections describe the RCS commands supported by LYX. You can find
them in the File ▷ Version Control submenu. LYX was tested against RCS 5.7/5.8/5.10.

11.2.2.1 Register

If your document is not under revision control, this is the only item shown in the
menu. And if it is under revision control, the Register item is not visible.
4
http://svnbook.red-bean.com/

113
11 LYX Features needing Extra Software

This command registers your document with RCS (unless you are under the di-
rectory managed by CVS). You are asked interactively to supply an initial descrip-
tion of the document. The document is now set in Read-Only mode and you have
to Check Out For Edit, before making any changes to it. A document under revi-
sion control has a “[RCS:<version> <locker>]” item tagged to the filename in the
minibuffer.
RCS command that is run:

ci -q -u -i -t-"<initial description>" <file-name>

Read man ci to understand the switches.

11.2.2.2 Check In Changes

When you are finished editing a file, you check in your changes. When you do this,
you are asked for a description of the changes. This is stored in the history log.
The version number is bumped, your changes are applied to the master RCS file, the
document is unlocked and set to Read-Only mode.
• RCS command: ci -q -u -m"<description>" <file-name>

11.2.2.3 Check Out For Edit

By doing this you lock the document so that only you can edit it. This will also make
the document Read-Write only for you. You will usually continue editing for a while
and when you are finished you check in your changes. The status line is changed to
reflect that you have locked the file.
• RCS command: co -q -l <file-name>

11.2.2.4 Revert To Repository Version

This will discard all changes made to the document since the last check in. You get
a warning before changes are discarded.
• RCS command: co -f -u<version> <file-name>

11.2.2.5 Copy
This will create a copy of the current document. Since RCS does not support copy
operations natively, the version history is not preserved, and the copy is added as a
new file. It requires a clean document without any changes since the last checkin.
You are asked for a file name and a description of the copy operation. After that the
copy is created, both locally and in the repository. If the parent directories of the
copied and original document differ, all relative paths of included files of the copy are
adjusted (like in File ▷ Save As. . . ). Finally, the copy is loaded instead of the original
document.

114
 11.2 Version Control in LYX

RCS commands:
Copy "<file-name>" to "<new-file-name>"
ci -q -u -i "<new-file-name>"

11.2.2.6 Undo Last Checkin

This makes as if the last check in never happened. No changes are made to the
document loaded into LYX, but the last version is removed from the master RCS file.

• RCS command: rcs -o<version> <file-name>

11.2.2.7 Show History

This shows the complete history of the RCS document. The output of rlog <file-name>
is shown in a browser. See man rlog for more info.

11.2.2.8 Revision info

LYX supports RCS version number, author name, date and time of last commit. All
those are extracted from rlog -r <file-name>. See 11.2.4.11 for details.

11.2.3 CVS commands in LYX

A subset of CVS operations is supported by LYX. You can find the commands in the
File ▷ Version Control submenu. The version control system SVN is more powerful, so
please use it instead of CVS if possible.

11.2.3.1 General CVS usage

If you start from scratch with CVS you have to create your repository and checkout
the working copy with external tools. If you’re using a client-server setup you may
need to login before doing the first repository checkout.
If your documents are under revision control and others are using the same reposi-
tory problems arise when different changes to the same document at the same location
happen. Standard CVS repositories don’t operate with a file locking mechanism. This
may be surprising, but conflicts only occur if people disagree on the proper content
of the same part of a document. So, if co-workers are used to communicate regularly,
these conflicts occur rarely. If they don’t communicate they have a fundamental
problem anyway. Nevertheless some people like to work with so called “reserved
checkouts”. If they do so the working copy of all files is readonly when checked out
first and the user starts editing after using a special command to make the working
copy writable. When the changes are checked in the working copy returns to readonly
state. With LYX one has to edit the .cvsrc file and add the line cvs -r to work
with reserved checkouts. The benefit is the possibility to see who is using a writable
copy of some document. It’s not guaranteed only one user makes a copy writable.

115
11 LYX Features needing Extra Software

LYX tries to guess if you’re using reserved or non-reserved checkouts. If your

working copy is readonly or it is writable and an additional copy of your document
exists in the CVS/Base sub-directory a reserved otherwise a non-reserved checkout is
assumed. When a reserved checkout is detected you have to use Check Out to make
your working copy writable if it’s readonly. After doing so the Check In operation
is possible and that makes your working copy readonly again after transferring your
changes to the repository.
More information about CVS can be found here http://www.nongnu.org/cvs and
here http://ximbiot.com/cvs.
Read man cvs to understand the sub-commands and the switches mentioned below.

11.2.3.2 Register
If your document is not under revision control, this is the only item shown in the
menu. And if it is under revision control, the Register item is not visible.
This command registers in CVS your document only in the case you have already
the documents directory under CVS control (in particular CVS/Entries file exists).
This means you have to create or checkout the archive by yourself using external
tools. (In case you forget that step LYX registers the document with RCS.)
Then you are asked interactively to supply an initial description of the document.
Don’t forget that registered file is not yet checked in.
CVS command that is run: cvs -q add -m"<entered message>" "<file-name>"
The term "<file-name>" above and for all other CVS commands is an abbreviation
for “change the current working directory to file location and use the file name without
path component as argument”.

11.2.3.3 Check In Changes

When you are finished editing a file, you commit your changes. When you do this and
you had changed the document, you are asked for a description of the changes. After
that changes are written to the repository. In case you didn’t change the document
and a reserved checkout is detected the reservation made on Check Out is undone.

CVS command:
cvs -q commit -m"<description>" "<file-name>" or
cvs -q unedit "<file-name>"

11.2.3.4 Check Out Changes

When you are sharing a repository with others, you may have to incorporate their
changes into your working copy.
CVS command: cvs -q update "<file-name>"
If a readonly checkout is detected the working copy is made writable and reserved.
CVS command: cvs -q edit "<file-name>"

116
 11.2 Version Control in LYX

11.2.3.5 Revert To Repository Version

This will discard all changes made to the document since the last check in. You get
a warning before changes are discarded. Firstly the file is deleted, secondly CVS
update command is run.
CVS command: cvs -q update "<file-name>"
If a reserved checkout is detected and the working copy has no changes only the
reservation is undone.
CVS command: cvs -q unedit "<file-name>"

11.2.3.6 Copy
This will create a copy of the current document. Since CVS does not support copy
operations natively, the version history is not preserved, and the copy is added as a
new file. It requires a clean document without any changes since the last checkin.
You are asked for a file name and a description of the copy operation. After that the
copy is created, both locally and in the repository. If the parent directories of the
copied and original document differ, all relative paths of included files of the copy are
adjusted (like in File ▷ Save As. . . ). Finally, the copy is loaded instead of the original
document.

CVS commands:
Copy "<file-name>" to "<new-file-name>"
cvs -q add "<new-file-name>"

11.2.3.7 Rename
This will rename the current document. Since CVS does not support rename opera-
tions natively, the version history is not preserved, the renamed document is added as
a new file, and the original document is deleted. It requires a clean document without
any changes since the last checkin. You are asked for a file name and a description of
the rename operation. After that the document is renamed, both locally and in the
repository. If the parent directories of the new and old file names differ, all relative
paths of included files are adjusted (like in File ▷ Save As. . . ). Finally, the document
is reloaded using the new name.

CVS commands:
Rename "<file-name>" to "<new-file-name>"
cvs -q add "<new-file-name>"
cvs -q remove "<file-name>"

11.2.3.8 Update of the local directory checkout from repository

Once your documents gets more complex, containing sub-documents and pictures,
including external .tex files and so on using version control becomes more compli-
cated. LYX supports updating the whole tree in which resides the document. This

117
11 LYX Features needing Extra Software

become especially useful once you cooperate with people which neither have detailed
knowledge about CVS usage nor they have ambition to commit additional material
to the repository. You have to organize the files structure so that all external files are
in the same directory or subdirectories of the document. It’s good practice anyway
to store multipart documents in an extra directory.
The Update local directory from repository command updates the whole di-
rectory. If local changes are detected user is warned before update starts. In case
of merge conflicts both versions of the conflicting document parts are placed in the
final document. You have to review and correct the result of the merge. You’ll find
the conflicts enclosed in pairs of <‌<‌<‌<‌<‌<‌< and >‌>‌>‌>‌>‌>‌> separated by =======. The
first part is your version as before the update operation with the document name
prepended. The second one is the repository version with the version number after
the sequence of > signs.
CVS commands:
cd $path; cvs diff "." (Ask if changes are detected.)
cd $path; cvs -q update "."
where $path stands for the path to the document.

11.2.3.9 Show History

This shows the complete history of the CVS document. The output of cvs log
"<file-name>" is shown in a browser.

11.2.3.10 Revision info

LYX supports CVS version number, author name, date and time of last commit. All
those are extracted from cvs log -r <file-name>. See 11.2.4.11 for details.

11.2.4 SVN commands in LYX

SVN is now partially supported by LYX. You can find the commands in the File ▷
Version Control submenu. Please note that if you use password protected access to
repository via ssh, you will be asked in terminal window. LYX was tested against
SVN 1.5, 1.6, 1.7 and 1.85

11.2.4.1 Register
If your document is not under revision control, this is the only item shown in the
menu. And if it is under revision control, the Register item is not visible.
This command registers in SVN your document ONLY in case you have already
the documents directory under SVN control (in particular .svn/entries file exists).
This means you have to checkout the archive by yourself.
5
Most of the commands will work with 1.4 too, see 11.2.4.7. There seems to be currently unresolved
permissions problem under SVN 1.8 with reverting changes when file is locked.

118
 11.2 Version Control in LYX

Then you are asked interactively to supply an initial description of the document.
Don’t forget that registered file is not yet commited.
SVN command that is run: svn add -q "<file-name>"
Read man svn to understand the switches.

11.2.4.2 Check In Changes

When you are finished editing a file, you commit your changes. When you do this,
you are asked for a description of the changes. After that changes are commited.
SVN command:6 svn commit -q -m"<description>" <file-name>

11.2.4.3 Check Out For Edit

Updates the changes of this file from the repository. Be sure you understand SVN
merging and conflicts resolving before using this function, because all conflicts has
to be resolved manually by you!
SVN command:7 svn update --non-interactive "<file-name>"

11.2.4.4 Revert To Repository Version

This will discard all changes made to the document since the last check in. You get
a warning before changes are discarded.
SVN command: svn revert -q "<file-name>"

11.2.4.5 Copy
This will create a copy of the current document including the version history. It
requires a clean document without any changes since the last checkin. You are asked
for a file name and a description of the copy operation. After that the copy is created,
both locally and in the repository. If the parent directories of the copied and original
document differ, all relative paths of included files of the copy are adjusted (like in
File ▷ Save As. . . ). Finally, the copy is loaded instead of the original document.

SVN commands:
svn copy -q "<file-name>" "<new-file-name>"
svn commit

11.2.4.6 Rename
This will rename the current document including the version history. It requires a
clean document without any changes since the last checkin. You are asked for a
file name and a description of the rename operation. After that the document is
renamed, both locally and in the repository. If the parent directories of the new and
6
In case locking is not enabled. See Section 11.2.4.9.
7
Ditto.

119
11 LYX Features needing Extra Software

old file names differ, all relative paths of included files are adjusted (like in File ▷ Save
As. . . ). Finally, the document is reloaded using the new name.
SVN commands:
svn move -q "<file-name>" "<new-file-name>"
svn commit

11.2.4.7 Update of the local directory checkout from repository8

All the commands above have one shortcoming – they deal with the current docu-
ment only. Once your document contains pictures, includes external .tex files and
so on administration becomes more complicated. LYX now supports updating the
whole tree in which resides the document9 . This become especially useful once you
cooperate with people which neither know about subversion management nor they
have ambition to commit additional material to the repository.
Update local directory from repository command updates the whole direc-
tory and in case of merge conflicts local version of the files are left, so no unintended
data loss occurs. If local changes are detected user is warned before update starts.
SVN commands:
svn diff $path (Ask if changes are detected.)
svn update --accept mine-full $path
where $path stands for the path to the document.

11.2.4.8 Show History

This shows the complete history of the SVN document. The output of svn log
"<file-name>" is shown in a browser.

11.2.4.9 File Locking

The file exchange through various revision control systems brings the problem of
merge conflicts in case two different users try to edit the same (parts of) document.
When such a conflict happens it needs manual resolving and one reasonable alterna-
tive is to provide some kind of locking mechanism, which guarantees that only one
user is allowed to edit file at the given time.
SVN has two such mechanisms to provide mutual exclusivity for file access – locks
and automatic setting of write permissions (see sec. 11.2.4.10) based on svn:needs-lock
file svn property10 . If this property is detected for a given document LYX starts to
use SVN locks for document editing automatically and the whole check-in/out mech-
anism switches to the same regimen as for RCS. This in particular means there are
two different modes of file use in LYX:
8
Note that this command will work only with subversion ≧ 1.5
9
One need to organize the files structure so that all external files are in the same directory or
subdirectories of the document.
10
http://svnbook.red-bean.com/en/1.2/svn.advanced.locking.html

120
 11.2 Version Control in LYX

• Unlocked state. The loaded file is in the read-only mode. For editing on needs
to check-out. Check-out consists of updating from the repository and gaining
write lock. If the lock is not possible to obtain, we remain in unlocked state.

• Locked state. The loaded file is in the ‘normal’ edit mode. No other user is
allowed to edit the file. Check-in consists of commiting changes and releasing
write-lock. If no changes have been made to the document, no commit will be
produced11 and only the write-lock will be released.

SVN commands:

Check-in: svn commit -q -m"<description>" "<file-name>"

svn unlock "<file-name>"

Check-out: svn update "<file-name>"

svn lock "<file-name>"

11.2.4.10 Automatic Locking Property

The above mentioned automatic setting of write permissions of the .lyx file can be
set through File ▷ Version Control ▷ Use Locking Property. This command is active only
when the file is not locked on the svn server (i.e. you need to check-out before
proceeding).

SVN commands:

Set: svn propset svn:needs-lock ON "<file-name>"

Unset: svn propdel svn:needs-lock "<file-name>"

11.2.4.11 Revision Information in Documents

There are more possibilities how to activate revision information in our document.

• LYX supports directly:

– tree revision information (vcs-tree-revision). The result is the output
of the svnversion command, the following table gives you an idea, how
to read the results.
Output Meaning
4123:4168 mixed revision working copy
4168M modified working copy
4123S switched working copy
4123P partial working copy, from a sparse checkout
4123:4168MS mixed revision, modified, switched working copy
11
Don’t be puzzled by the fact that you will be asked for commit message anyway.

121
11 LYX Features needing Extra Software

– file revision information. The result comes from parsing the output of
svn info --xml file.lyx. Supported flags are:
∗ version number of the last commit (vcs-revision)
∗ author of the last commit (vcs-author)
∗ date of the last commit (vcs-date)
∗ time of the last commit (vcs-time)

You can obtain this info via InsetInfo (Insert ▷ Field ▷ Version Control Revision).
The information will be available only when you have the file stored under svn
managment (i.e. the .svn directory is available with your document).

• Another—a hacking one—possibility is to use svn keywords12 . In short – you

set file keywords property (e.g. svn propset svn:keywords ’Rev’ file.lyx) and then
paste keyword TEX code13 tag in your document (e.g. $Rev$). This way svn
client will automatically substitute revision number (e.g. $Rev: 59 $) after
each update and commit. There are more problems with this approach. Firstly,
the ’$’ character is used in TEX world for math equations, so any occurence of
math formula Rev become Rev : 59 in your LYX document. Similarly for
other keywords like Id, Date, Author, etc. Secondly svn output is dependent
on your locales, so its very easy that svn would produce some problematic
strings once Date is used. Thirdly you get the whole ’Rev: 59’ string in your
document instead of the plain number. Until subversion implements user’s
custom keywords it will be hard to use this approach reliably or let LYX to
support it directly.

11.2.5 SVN and Windows Environment

My inclination is to say that if the user cannot figure out the command
line operations on their own fairly quickly, they would be well advised to
use TortoiseSVN. —P. A. Rubin

11.2.5.1 Preparation
In addition to installing LYX, and having access to a Subversion repository, the user
will need to install the Subversion client program. A Windows installer for the client
program is available from CollabNet. The user may also want to install TortoiseSVN,
which integrates Subversion operations into the context (rightclick) menu of Windows
Explorer. Operations done outside LYX will typically be more convenient using the
Explorer context menu. Note that TortoiseSVN is not a replacement for the client
program, which is what LYX itself will use.
12
http://svnbook.red-bean.com/en/1.4/svn.advanced.props.special.keywords.html
13
This is an easy way how to ensure that LYX won’t break the line in the middle of keyword tag.

122
 11.2 Version Control in LYX

11.2.5.2 Bringing a document under Subversion control

Before a LYX document can be brought under version control in Subversion, its
parent directory needs to be under version control. If the document is being added
to a project already in the repository, this is accomplished by checking the project
out to the directory where the new document will be placed. If the project itself is
not yet under version control (for instance, if this document starts a new project),
the directory must be imported into the repository. This is done outside LYX. Both
import and checkout are easily accomplished from the Explorer context menu using
TortoiseSVN, or alternatively can be done using the command line client at a DOS
prompt. The procedure for importing the project using TortoiseSVN is described
below, assuming an existing repository and a new project being started in C:\new
project. For information on using the Subversion client program, run svn --help
in a DOS shell.

1 Locate C:\new project in Windows Explorer, right click it, and select Tor-
toiseSVN ▷ Repo-browser. If necessary, adjust the URL for the repository, then
click OK.

2 Right click the level of the repository under which you want to place the new
project folder (typically the top level) and click Create folder Supply a name
for the project folder and click OK. Add a message for the log file if desired,
then click OK again. The new project folder should appear in the repository.
Finally, click OK again to exit the repository browser.

3 Once again right click C:\new project, this time selecting SVN Checkout. . .
Select the URL of the project folder you just created in the repository, and
set the checkout directory to C:\new project. Click OK. You will be warned
about a non-empty folder; click OK to proceed. You should now have a .svn
directory under C:\new project.

4 Create or open your document in LYX and click File ▷ Version Control ▷ Register.
Add a log message and click OK to commit the document to version control.

From this point onward, you should have full functionality in the File ▷ Version Control
menu. You also have the option of checking the document in and out, viewing
its history, etc. using the TortoiseSVN context menu in Windows Explorer or the
Subversion client program from a command prompt.

11.2.5.3 SSH tunnel used with SVN under Windows

Compared with Linux setting up an svn client to communicate over ssh under Win-
dows is a rather troublesome task. We will at least offer some hints how to setup the
client side but prior knowledge about ssh and the Windows command line is needed,
also be prepared for a great deal of frustration. . .

123
11 LYX Features needing Extra Software

1 Get an svn client for windows, as described in the previous sections. When it
is a fresh install run some svn command (e.g. svn --version) to create config
files, which you will need to change later on.

2 Choose an ssh client for Windows. There are several possibilities, we will use
the one from Putty tools14 . You will need to set the connection up so that the
client doesn’t ask for any password from you. To keep things easy we will use
only keys without any additional password protection etc.
a) Generate keys by puttygen. Save your private .ppk key file and put the
public one on the server side. If the SVN server runs on Linux, note
that the format of the public key is not compatible with Linux openssh
and you will need to direcly copy-paste the key from the “Public key for
pasting into OpenSSH authorized_keys file:” edit field into the server’s
~/.ssh/authorized_keys / authorized_keys2 file.
b) Get the Putty’s plink. In the SVN config file15 , section [tunnels], setup ssh
command, e.g. ssh=c:/path/plink.exe -i c:/path/private_key.ppk.16

3 Checkout the SVN archive, e. g.

svn co svn+ssh://user@server/repository_path.

11.2.5.4 End-of-Line Conversions

When the collaborators are mixing Linux and Windows environments, LYX will use
different line endings inside the .lyx files. This is not a problem as far as LYX
functionality is concerned, but the commit diffs will be huge and merge-conflicts
prone. Fortunately SVN itself knows17 how to deal with CR/LF problems when
switching .lyx files to the native mode.18

11.2.6 GIT commands in LYX

A minimal subset of GIT commands is now supported by LYX. You can find the
commands in the File ▷ Version Control submenu. Please note that if you use password
protected access to repository via ssh, you will be asked in terminal window. LYX
was tested against GIT 1.7/2.30.19
14
http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
15
Exact path depends on Windows version, usually somewhere around c:\Documents and
Settings\user\Application Data\Subversion\config / AppData\Roaming\Subversion.
16
It will usually take a lot of time to get exact command right and it depends on many things. For
example do not have some remote server saved as a default session in Putty etc. If things fail,
try to connect via plink without SVN first.
17
http://svnbook.red-bean.com/en/1.4/svn.advanced.props.file-portability.html
18
For the lazy guys: svn propset svn:eol-style native FILE_NAME
19
Windows users please note that you need to ensure that git is on the path. This can be set from
within LYX at Tools ▷ Preferences ▷ Paths ▷ PATH prefix.

124
 11.2 Version Control in LYX

One big difference of GIT and the other supported version control systems is the
distributed nature of GIT: With traditional version control systems there is one cen-
tral server which hosts the repository. Users commit their changes to the server, and
get updates made by other users from it. With GIT, users commit to a local reposi-
tory. The local repository can be synchronized with one or more remote repositories
using the pull and push GIT commands. LYX does not interact in any way with
remote GIT repositories. It works exclusively with the local repository in a very sim-
ilar way as with a central CVS or SVN repository. If you use remote GIT repositories
you need to do the pull and push operations with your favourite GIT client.

11.2.6.1 Register
If your document is not under revision control, this is the only item shown in the
menu. And if it is under revision control, the Register item is not visible.
This command registers in GIT your document ONLY in case you have already
the documents directory under GIT control (in particular .git/index file exists20 ).
This means you have to checkout the archive by yourself.
Then you are asked interactively to supply an initial description of the document.
Don’t forget that registered file is not yet committed.
GIT command that is run: git add "<file-name>"
Read man git to understand the switches.

11.2.6.2 Check In Changes

When you are finished editing a file, you commit your changes. When you do this,
you are asked for a description of the changes. After that changes are committed.
GIT command: git commit -q -m"<description>" <file-name>

11.2.6.3 Revert To Repository Version

This will discard all changes made to the document since the last check in. You get
a warning before changes are discarded.
GIT command: git checkout -q "<file-name>"

11.2.6.4 Rename
This will rename the current document including the version history. It requires a
clean document without any changes since the last checkin. You are asked for a
file name and a description of the rename operation. After that the document is
renamed, both locally and in the repository. If the parent directories of the new and
old file names differ, all relative paths of included files are adjusted (like in File ▷ Save
As. . . ). Finally, the document is reloaded using the new name.
20
For that both git init *and* initial repository commit (or at least git add) needs to be man-
ually done.

125
11 LYX Features needing Extra Software

GIT commands:
git mv "<file-name>" "<new-file-name>"
git commit

11.2.6.5 Show History

This shows the complete history of the GIT document. The output of git log
"<file-name>" is shown in a browser.

11.2.6.6 Version Info

LYX supports GIT hash number of the last commit to the file, its abbreviated form,
author name, date and time of last commit. All those are extracted from git log
-n 1 --pretty=format:%H%n%h%n%an%n%ai. Tree version information is obtained
via git describe --abbrev --dirty --long. See 11.2.4.11 for other details.

11.2.7 Further tuning

With the recent addition of the vc-command function LYX power users are allowed
to create their own commands for revision control.
As an example you can see how two TortoiseSVN commands could be integrated
directly:

Commit: vc-command DR "." "TortoiseProc /command:commit /path:$$p"

Revert: vc-command DR "." "TortoiseProc /command:revert /path:$$p"

11.2.8 Version control and Document comparison

One of the typical uses of version control is to inspect the changes between revisions,
usually by creating diff dumps. While this is useful for plain text files, it is much less
useful in the case of LYX files, which have more a complicated structure. Hence we
provide binding to the Document comparison feature. There are two ways of calling
this feature – either by direct call of vc-compare LYX function (for details see LYX
functions manual) or by the toolbar icon or the menu item , respectively. One can
either compare two chosen revisions of the document or he can simply compare the
current version of edited text with older revisions (where ’0’ revisions back means
comparison of the edited file with last commited revision).
This feature is supported for SVN and RCS though due to the more complicated
versioning scheme of RCS there is a constraint – when addressing the revisions in
dialog, numbers always point to the last number in RCS revision number, i.e. ’35’
in ’1.2.35’. We don’t currently support GIT addressing of revisions, one can just
compare edited document with its revision X steps backs, where X is addressed as
HEAD~X.

126
 11.3 Literate Programming

11.3 Literate Programming

Updated by Kayvan Sylvan ([email protected]), original documentation written
by Edmar Wienskoski Jr. ([email protected])

11.3.1 Introduction
The main purpose of this documentation is to show you how to use LYX for liter-
ate programming, where it is assumed that you are familiar with this programming
technique, and know what “tangling” and “weaving” means. If that is not the case,
please follow the web links provided in the following sections. There is a lot of good
documentation out there covering old development history to the latest tools tips.
It is also assumed that you are familiar with LYX itself to a point that you are
comfortable changing your LYX preferences, and X resources file. If that is not the
case please refer to other LYX documentation to cover your specific needs.

11.3.2 Literate Programming

From the Literate Programming FAQ:
Literate programming is the combination of documentation and source
together in a fashion suited for reading by human beings. In fact, liter-
ate programs should be enjoyable reading, even inviting! (Sorry Bob, I
couldn’t resist!) In general, literate programs combine source and doc-
umentation in a single file. Literate programming tools then parse the
file to produce either readable documentation or compilable source. The
WEB style of literate programming was created by D. E. Knuth during
the development of his TEX typesetting software.
Another excerpt says:
How is literate programming different from verbose commenting?
There are three distinguishing characteristics. In order of importance,
they are:
• flexible order of elaboration
• automatic support for browsing
• typeset documentation, especially diagrams and mathematics
Now that I sparked your curiosity, take a look in the references.

11.3.2.1 References
The complete Literate Programming FAQ can be found at:
Literate Programming FAQ http://www.literateprogramming.com/lpfaq.
pdf

127
11 LYX Features needing Extra Software

The FAQ lists 23 (twenty three!) different literate programming tools. Where some
are specialized or “tailored” for particular programming languages, while other have
general scope. I selected Noweb for my own use for several reasons:

• It can generate the documentation either in LATEX or HTML.

• It has a open architecture, i. e. it is easy to plug in new filters21 and to perform

special processing that you may need.

• There is a good selection of filters available already (the HTML is one of them).

• It is free.

The Noweb web page can be found at:

Noweb home page https://www.cs.tufts.edu/~nr/noweb/

Starting from there you can reach many other interesting links and even some literate
program examples.

11.3.3 LYX and Literate Programming with Noweb

The LYX support for Literate Programming is provided by using the generic LYX
converters mechanism. This support is provided in a “Noweb independent” way, i. e.
you will be able to use this new LYX feature with some other literate programming
tool of your choice by just changing your LYX preferences.

11.3.3.1 Generating documents and code (weaving and tangling)

Using the noweb module If you have installed Noweb and LYX successfully, when-
ever you open a new document, after you have chosen its document class, use the
Document ▷ Settings menu to add the “noweb” module. If Noweb is correctly in-
stalled, when you click on the “Modules” link, you will see the “noweb” module in
the available list and you can add it to your document.

Typing code in LYX enables you to write code with a custom inset named Chunk.
Noweb delimits chunks like this:

<‌<My code>‌>=
code
more code
even more code
@
21
Filters are programs that read a given data stream and output a manipulated data stream. That
way, a WEB file (consisting of literate code) can be turned into a file consisting only of C program
code or LATEX code.

128
 11.3 Literate Programming

The problem is that whatever is written in between the <‌< and the @ must be taken
literally, i. e. LYX should be prevented from making any special interpretation of what
has been written. This is also handled by Chunk, that works like a normal text inset
but has a free spacing capability.
As a special note, you can also use the “%def” construct of Noweb in your chunks
to add items to Noweb’s identifier cross-reference:

<‌<My chunk>‌>=
def some_function(args):
"This is the doc string for this function."
print "My args: ", args
@ %def some_function

For an example of this usage and the resulting cross-reference output, look at the
Literate python program in LIBDIR/examples/listerrors.lyx which should make this
all clear.

Generating the documentation At this point you already have a new document
file with a proper document class, and with some code and text on it. How do I print
it? The answer is simple, you select View ▷ DVI, etc. Just like you would do for a
plain document. No special procedure is required.
To help orientate you, I will now explain what happens inside LYX:

1 When the Update ▷ DVI menu option is chosen, a LATEX file is generated.
If the document is of any literate class the generated file will be named with
an extension name defined by the “literate” format (defined in the Preferences
panel), otherwise the file will have the usual .tex extension.

2 Note that the only difference so far is in the name of the file, no special process-
ing is required by LYX. Given that you formatted the code using the Chunk
inset that, by itself, takes care of the business.

3 If the document is of any literate class LYX will then use the internal LYX to
Noweb converter, followed by the Noweb to LATEX converter22 to generate the
LATEX file.
Otherwise it will just skip this step.

4 Finally, LATEX is invoked and the regular post processing continues as in a plain
document.

Independence from a particular “literate tool” is easily achieved by changing the

commands that are run by the various converters.
22
The converters are defined in the Tools ▷ Preferences panel, under the “Conversion” tab. See
section Converters of the Customization manual for general information about converters.

129
11 LYX Features needing Extra Software

Generating the code When the build menu option is chosen or the corresponding
button in the toolbar is pressed, a LATEX file is generated just like step 1 above. Next,
LYX invokes the Noweb->Program converter. This converter needs to be defined by
the user and is not installed by default, though the Program format is. This converter
(like any other converter) will have two parts:

1 The converter program itself. This program performs the conversion from the
one format to the other (in this case, from the Noweb format to the Program
pseudo-format).

2 The error log parser. This is a program whose sole purpose is to rewrite error
messages in a format that LYX understands. This makes it possible for LYX to
place error boxes in the right places in the file buffer.

The first part, the “Converter” setting, should be set to

build-script $$i $$r

This basically means that LYX will call “build-script” (a program or script) with the
name of the Noweb file (normally a file in the LYX temp directory) and the directory
path of the original LYX file.
This is an implementation of “build-script” that you can place in a directory on
your path:

#!/bin/sh
#
notangle -Rbuild-
script $1 | env NOWEB_SOURCE=$1 NOWEB_OUTPUT_DIR=$2 sh

The next part of the converter setting is the “Flags” which is to be set to

parselog=$$s/scripts/listerrors

This will run any errors that are generated by the “build-script” process through the
“listerrors” program.
The build will normally take place in LYX’s temporary directory, so the files pro-
duced by the conversion will be in that directory. LYX will copy out what it regards
as the ‘main’ file, but the Noweb->Program conversion may produce several files, and
so most of these would then be deleted when LYX was closed. This is why we pass in
the NOWEB_OUTPUT_DIR environment variable so that the build-script chunk
can place the generated files in that location.

130
 11.3 Literate Programming

Build instructions in the document The last piece of the integration between LYX
and noweb is the “build-script” chunk. Generally, the instructions for building your
program should be embedded in a chunk of its own. The noweb-specific “build-script”
above uses the notangle command to look for this chunk (called “build-script”) and
runs its contents through “sh”.
Typically, such a chunk would look something like this:

<‌<build-script>‌>=
#!/bin/sh
if [ -z "${NOWEB_SOURCE}" ]
then
NOWEB_SOURCE=myfile.nw
fi
[... code to extract files ... use NOWEB_OUTPUT_DIR here ...]
[... code to compile files ...]
@

Look in File ▷ Open Example ▷ Modules ▷ Noweb Listerrors or in File ▷ Open Example ▷
Modules ▷ Noweb2LyX which implement versions of the “listerrors” program for some
illustrations of how all of these pieces go together . Interestingly, these files show off
the language independency of the LYX literate programming support since they are
written in Python and Perl respectively.

11.3.3.2 Configuring LYX

All the Literate Programming support is configured by the Tools ▷ Preferences panel
in the “File Handling” tab. The important parts are:

the “NoWeb” format Set up via the File Formats tab, this is where the Noweb-
specific pieces are set up. The GUI Name is set to NoWeb, the file extension is
set to .nw. This tells LYX to create a file with a .nw extension in the first step
of the conversion process.

the Program format This is an empty format whose sole purpose is to be the end-
point of a conversion (which then allows us to set up a converter for it).

NoWeb->LATEX This converter performs the “weaving” of the literate document.

For Noweb, it is set to “noweave -delay -index $$i > $$o”

NoWeb->Program This performs the “tangling step”. As stated above, the Con-
verter is set to “build-script $$i $$r”, with Flags set to
“parselog=$$s/scripts/listerrors”.

131
11 LYX Features needing Extra Software

11.3.3.3 Debug extensions

There is also a new function implemented in the LYX server, the “server-goto-file-row"
function, to be used with ddd/gdb or other debugger.
When debugging code with ddd/gdb, it is possible to invoke a text editor at the
current execution position with a single key stroke. The default ddd configuration
for that is shift-ctrl-V. It happens that you can define the editor command line
invocation in ddd by accessing the Edit ▷ Preferences ▷ Helpers dialog and changing
the "Edit Sources" entry.
I take advantage of the newly created LYX server function and this ddd feature,
and set “Edit Sources” to:

echo "LYXCMD:monitor:server-goto-file-row:@FILE@ @LINE@" >~/.lyxpipe.in

With this, whenever you are using ddd and find a point in the program that you
want to edit, you just press shift-ctrl-V (in the ddd window), and ddd will forward
this information to LYX through the LYX server and then the LYX window will show
the same file with the cursor at the same position ddd was pointing to. No more
guessing or long scrolling to locate a point in the program back from debugging !
Note however that you must enable the LYX server to get this feature working (it
is disabled by default). Sec. 10.2 explains how to do that.

11.3.3.4 Toolbar extensions

There are six new buttons that can be added to your LYX toolbar. Four of these
buttons are short cuts to layout styles: Standard, Section, LATEX, and LYX-Code, one
for the custom inset Chunk. The last one is a short cut to the “Build Program” File
menu entry.
LYX has a range of buttons that are available for tool bar customization. In my
toolbar I like to combine the six short cuts above with two more: One for Document ▷
Update ▷ DVI and the other for Document ▷ View ▷ DVI File menu entries. Here is how
it looks like:

Toolbar
Layouts
Icon "layout Standard"
Icon "layout Section"
Icon "layout LATEX"
Icon "layout LYX-Code"
Icon "flex.insert Chunk"
Separator
Icon "buffer-view"
Icon "buffer-typeset"
Icon "build-program"

132
 11.3 Literate Programming

Separator
.
.
.
End

11.3.3.5 Colors customization

There are a number of colors in LYX that can be customized in Preferences. One of
the things that bothers people is the LATEX font color. The default color is red, since
the chunks uses LATEX font, and there is a lot of chunks in literate documents, you
may get tired of seeing everything in red. You can change it by going to the tabs
Look&Feel, Colors.
The next thing is the visible presence of the newline character in the screen. You
can choose the color of this particular character and make it blend in the background.
I recommend you choosing a color that is close to the background but not equal, that
way you still can see it is there, but it is not bothering you anymore.

11.3.4 LYX and knitr/Sweave

Support for knitr and Sweave is documented in Help ▷ Specific Manuals ▷ Knitr and
File ▷ Open Example ▷ Modules ▷ Rnw (knitr) and in Help ▷ Specific Manuals ▷ Sweave and
File ▷ Open Example ▷ Modules ▷ Sweave.

133
Index

L
LATEX-packages
enumitem, 61
multicol, 68
Lists
Customization, 61
Spacing, 60

135