#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass paper
\begin_preamble
%% RCS %%%%%%%%%%%%%%%
%% $Id: lyx_article.lyx,v 1.4 2005/02/19 00:29:22 gerrit Exp $
%%
%% $Log: lyx_article.lyx,v $
%% Revision 1.4 2005/02/19 00:29:22 gerrit
%% now I am starting the conversion into html
%%
%% Revision 1.3 2005/02/18 00:51:48 gerrit
%% typed most of the article. Several sections, such as roll your own layout or prosper are still missing
%%
%% Revision 1.2 2005/02/09 22:26:38 gerrit
%% set the title
%%
%% Revision 1.1 2005/02/09 22:23:06 gerrit
%% Initial revision
%%
%%
%% PDF ONLY
\usepackage{ae,aecompl}
%% hyperref (deactivated)
%\usepackage{hyperref}
\end_preamble
\language english
\inputencoding default
\fontscheme default
\graphics default
\float_placement h
\paperfontsize default
\spacing single
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default
\layout Title
Professional Tex(t) authoring with LyX
\layout Abstract
This text is aimed at people who have a lot of text editing/authoring to
do and who are primarily interested in getting a text edited in a fast,
reliable, well-formatted way without having to put in (a) lots of wordprocessor
skills or (b) guru-level LateX knowledge.
The main tool that this article describes is LyX, an extremely robust and
powerful LaTeX frontend based on a client-server architecture.
\layout Abstract
This article is not so much an application overview, but rather concentrates
on the writing process and summarizes experiences of using LyX on a day-to-day
basis for five years.
Other issues, such as versioning or which graphics to use, are also discussed,
as well as additional tools that are helpful for document preparation.
\layout Section
Motivation
\layout Standard
Imagine you have to hand in two texts until some close date in the very
near future, a report describing your recent work progress and a small
user manual for a piece of software which has just matured.
There won't be extra credits for using cute layouts and flashy special
fonts, in fact you are not worried about such issues.
All you want is to get over with writing the text, once it is done one
could maybe jazz up the layout a bit, but that is not of primary importance.
\layout Standard
There are usually two choices, either one uses a GUI-based word processor
or one resorts to source-level LaTeX editing.
The first has the advantage of direct control on the layout process --
in fact it is more of a layout program than an editing tool, which lead
to the acronym WYSIWYG (
\emph on
what you see is what you get
\emph default
).
The second is very robust software with an incredible print quality.
It however follows a different paradigm, WYSIS (
\emph on
what you see is source
\emph default
) and has some learning curve, especially for newcomers.
As little as you would care about fancy headings when writing a text, you
are not likely to be enthusiastic about having to dig into source code
when the primary focus is the text itself, not its embellishments or markup.
I was precisely in this situation four years ago, I didn't know any LaTeX,
got production-ready within half a day and had a big document with lots
of illustrations and references ready quite soon afterwards.
\layout Standard
LyX is exactly in the middle of the above two paradigms, it is called WYSIWYM
(
\emph on
what you see is what you mean
\emph default
), quoting
\begin_inset LatexCommand \cite{lyx-intro}
\end_inset
:
\begin_inset Quotes eld
\end_inset
\emph on
LyX is a program that provides a modern approach to writing documents with
a computer by using a markup language paradigm, an approach that breaks
with the obsolete tradition of the `typewriter concept.' It is designed
for authors who want professional output quickly with a minimum of effort
without becoming specialists in typesetting.
The job of typesetting is done mostly by the computer, not the author;
with LyX, the author can concentrate on the contents of her writing.
\emph default
\begin_inset Quotes erd
\end_inset
\layout Standard
Editing in LyX is done in a GUI environment, no source code is needed (but
can be inserted in extra blocks when required).
Have a look here which shows this article text at an early stage.
The gray box that you see is a cross-reference, you can click on it and
edit the reference.
This edit window is not to be confused with the output, LyX generates a
text file which can then be translated into LaTeX, you can view the complete
output by pressing ALT-d, which pops up a DVI window (DVI=device-independent-fo
rmat is an intermediate file format used by LaTeX), ALT-t does the same
for postscript.
The capitalised variants ALT-D, ALT-T are used when you want to update
changes you made in the editor window.
\layout Standard
The procedure is thus similar to the typical LaTeX-editing process, with
the advantage that you have the structure of the text sitting in front
of you, not cluttered by source code tags.
With pure LaTeX-editing the temptation is often, comparable to word processors,
to increase a little font size here, change a little environment setting
there and in summary do lots of things that have only remote relevance
for the text itself.
\layout Standard
In summary, when you need a reliable text authoring tool and want to concentrate
on the text itself, LyX is a strong recommendation.
Its clear strengths are managing large documents (which can be split into
pieces), its integration with other software detailed below and its incredible
robustness.
Since less main memory is spent on the cycle of actualising the current
layout, there is much less of a slow-down when editing large documents.
I have heard about word processor programs crashing under large files (and
producing irreparable binary garbage).
LyX is text-based and when forcefully aborted (e.g.
power-down) leaves an emergency file; even with the most bizarre settings
and huge text lengths I could not witness a decrease in performance.
I have been using it during the last five years almost on a day-to-day
basis and out of nearly 800 pages of authored text, some huge, I have not
lost more than half a paragraph.
As a bonus, LaTeX code can be sourced into LyX via the reLyX(1) script.
\layout Standard
If you really would prefer to do source-level editing of LaTeX, a look at
kile may be of interest, it is a KDE editor especially for LaTeX with additiona
l features,
\begin_inset LatexCommand \htmlurl{http://kile.sourceforge.net/}
\end_inset
.
\layout Section
Getting started
\layout Standard
This article differs from the earlier one in March 1998 (
\begin_inset LatexCommand \htmlurl{http://linuxfocus.open.ac.uk/English/March1998/article31.html}
\end_inset
) in that it provides less general introduction, instead I will just point
where to get the information and summarize how to get there.
Instead of doing a graphical walk-through here (as initially planned),
if you have not seen LyX before, I highly recommend to do the following
tour through the editing process, it also describes how to get your hand
on the first document in a very nice manner:
\begin_inset LatexCommand \htmlurl{http://www.lyx.org/LGT/ }
\end_inset
.
\layout Subsection
Prerequisites
\layout Standard
The first thing to do is to check whether Latex is already fully installed
on your system.
In RedHat/Fedora systems this is quite conveniently possible via the graphical
package installer which has a single tick-box for the entire latex distribution.
You can manually check via
\layout Standard
\family typewriter
rpm -qa | grep tex
\layout Standard
\noindent
which should list the following packages (assuming you are using the TeTeX
implementation of latex):
\layout Itemize
tetex and tetex-latex (base packages)
\layout Itemize
tetex-afm (a PostScript font converter for TeX)
\layout Itemize
tetex-xdvi (for previewing .dvi files)
\layout Itemize
tetex-doc
\layout Standard
The last is very useful if you want to check out different packages, the
documentation resides in /usr/share/texmf/doc/index.html.
As further prerequisites, check for aiksaurus (a thesaurus to be used while
editing) and, more importantly, for the spell-checker aspell.
Aspell also has packages for several non-English languages.
In LyX this spell-checker is activated via F7.
\layout Subsection
Installation
\layout Standard
LyX comes in two flavours now, the older x-forms variant (which at times
was a little tricky to build) and the modern Qt variant which I'd say is
preferable.
RPMs for both variants are available, under debian the installation is
as easy as
\layout Standard
\family typewriter
apt-get install lyx lyx-common lyx-qt \SpecialChar ~
\SpecialChar ~
## or lyx-xforms if you prefer
\layout Standard
\noindent
If you would like to build the sources yourself, these are at
\begin_inset LatexCommand \url{www.lyx.org}
\end_inset
.
You might find the following build script useful.LaLyX is a small coding
masterpiece, everything is written in C++ and compiled from scratch, the
build process takes longer than building a kernel.
\layout Subsection
Configuration
\layout Standard
LyX needs to check your installation first.
Upon first editing, run Edit -> Reconfigure, which updates the internal
database.
When changing anything to your LaTeX installation, this step should also
be re-run.
The results of this step can conveniently be browsed under Help -> LaTeX
configuration which also tells you how to get potentially missing packages.
It pays to enable autosave under Edit -> Preferences, it really is not
an expensive but rather very useful option to take.
\layout Section
Editing and producing output
\layout Standard
Writing costs (i) inspiration (creativity) and (ii) transpiration (simply
manual work).
I found that it really pays off to put in the effort and learn 10-finger
\begin_inset Quotes eld
\end_inset
touch
\begin_inset Quotes erd
\end_inset
-typing.
There are cheap books out with some exercises and after a couple of weeks
one is able to write without all these terrible two-finger search system
typos.
To make hard work a fun game, check out ktouch which is made exactly for
learning touch-typing.
It starts, like playstation, with an easy level and you can go on to higher
and higher levels.
It is really nicely made, ships with the kdeedu package or can be found
on
\begin_inset LatexCommand \htmlurl{http://ktouch.sourceforge.net/}
\end_inset
.
\layout Standard
For the inspirational part of getting a structure together before starting
with the transpiration, there is a very helpful article about text outliners
(I use the vim outliner) and mind-mapping tools in
\begin_inset LatexCommand \cite{key-1}
\end_inset
.
\layout Subsection
Basic editing
\layout Standard
There is not much to say here since the interface is fairly self-explanatory,
if you get stuck check out the graphical tour mentioned above.
Let's say you have some preliminary notes which sit in some textfile created
on your favourite hand-held.
This can be imported via File->Import (either line by line or as block)
and so there is a rough structure.
This can now be converted into text segments, the listbox on the toolbar
presents the options allowed by the chosen style file.
Usually one can set standard via ALT-p s and headings via ALT-p n where
n is a number from 1..6, the smaller the number the bigger the heading.
For things you don't want to see in the output, you can use notes via ALT-i
n, shown in the following figure as the blue area.
Once the text is ready you can use View and check it or export it (Latex,
PDF, Ascii, HTML (see notes further down), \SpecialChar \ldots{}
) via File->Export.
\layout Subsection
References
\layout Standard
LaTeX fun starts with the excessive choices of section, subsection, page,
image, table crossreferences plus the external bibliographical data.
To be able to reference something in the text, first a
\emph on
label
\emph default
needs to be created via ALT-i.
Any text can be used for labelling, but spaces within are to be avoided.
Having done that, this label can be back (and forward) referenced anywhere
in the text by simply inserting it via ALT-i r (for reference), which gives
you a choice of referencing modes.
For quoting URLs within the text, use ALT-i u instead.
With regard to
\emph on
bibliographical references
\emph default
there are two choices:
\layout Enumerate
Create a
\emph on
bibliography section
\emph default
manually at the end of the document by selecting `Bibliography' from the
style selector.
\layout Enumerate
Use an external
\emph on
BiBteX database
\emph default
, which is referenced by putting in Insert -> Lists&TOC -> BibTeX Reference
(as many as you want).
\layout Standard
For the first option you can check the first version of this article here.
If you have never seen a BibTex database before, here is an example.
It is simply a standardised text-markup of bibliographical data.
And it is not necessary to mess with that, since there is a wonderful database
tool called pybliographer (
\begin_inset LatexCommand \url{http://www.pybliographer.org}
\end_inset
).
It allows the complete management of all such databases including incremental
text search and conversion into other formats such as e.g.
HTML.
Here is a screenshot showing such an incremental search.
When you have set up one of the two alternatives, you can use the bibliographic
al references anywhere in the text via ALT-i c (for citation).
But there is an even smarter way which shows the flexibility of lyx.
Pybliographer, as well as some other tools, can interface with the lyx
server process.
This happens via the $HOME/.lyx/lyxpipe.in (and lyxpipe.out) pipes.
The server protocol is described in detail in the LyX documentation, here
it suffices to say that you can simply hit `Cite' on pybliographer to insert
the reference that you have just rediscovered as part of an incremental
search of your database.
For other applications, this communication protocol opens ways such as
automatically generating text from scripts and \SpecialChar \ldots{}
you choose.
\layout Subsection
Version control
\layout Standard
This is especially useful when the text is longer and changed several times.
Lyx comes RCS-ready, it is simple to set up.
\layout Enumerate
create a directory named RCS in the same directory where you keep the LyX
source
\layout Enumerate
edit the lyx file and go to File -> Version Control -> Check In Changes
\layout Enumerate
next time you open the file, lyx will ask you whether you want to retrieve
the document via RCS
\layout Standard
You can use all the usual RCS commands from the commandline (man rcs or
rcsintro).
I usually just use rcs -l to create a lock, co -l when I want to lock upon
checkout and rcsclean to remove all unchanged files.
If you are the only author, disable strict locking via rcs -U <file> which
considerably simplifies the procedure.
\layout Subsection
Math stuff
\layout Standard
If you need many formulae then LyX/LaTeX provides one of the best facilities
of documenting mathematical text.
To check out math mode, enter it via ALT-m m (yes twice) and then you can
pick any symbol from Insert->Math->Math Panel.
Lyx recognizes when you type in latex math commands -- try for instance
ALT-m m and then the sequence
\backslash
mathcal P then space then
\backslash
frac (n-1) TAB 2.
\layout Subsection
Graphics
\layout Standard
A variety of graphics formats can be used.
Encapsulated postscript (.eps) is often the best option when producing PS
output, but .png, .jpg and .gif also work.
You can put in images directly via ALT-i g (graphics), but it is better
for the layouting to use so-called
\emph on
floats
\emph default
, which are just a wrapper and allow several placement options as well as
a caption underneath.
To produce a float, use ALT-i a and then `Figure'; when right-clicking
the outer frame you can force the position (to some extent, this is latex,
not a layouting program).
\layout Subsection
Document settings and layout formats
\layout Standard
I haven't spoken much about the output format of the document, which is
set via Layout->Document.
Depending on what lyx has found during its test-run, there is normally
a standard selection of formats such as article, report, letter, book etc.
By choosing one of these, the layout of the entire document is changed.
This directly affects the list of styles available on the left of the menu.
Internally, these choices are lyx-layout wrappers around the latex document
classes.
Further below, I give a small example how to hack such a layout (which
is not too hard).
But for the most purposes, one of the given formats should more than do,
there are also individual choices possible.
\layout Standard
An interesting feature are the use of templates, in particular the letter
template.
Try File -> New from Template.
This opens the templates in /usr/share/lyx/templates.
These are just text files which can be modified, e.g.
for your own letter format.
Very nice is for instance the g-brief (German
\begin_inset Quotes eld
\end_inset
Gesch
\begin_inset ERT
status Collapsed
\layout Standard
\backslash
"a
\end_inset
ftsbrief
\begin_inset Quotes erd
\end_inset
= business letter) which works for those envelopes which have a little
transparent address window on the left.
The blue stuff in a template is invisible for the output and just hints
where to fill in.
\layout Subsection
Generating output
\layout Standard
LyX hides the internals of LaTeX compilation away from you, it creates a
temporary directory in /tmp which you can look at by
\layout Standard
ls -l /tmp/lyx_tmpdir*/lyx_tmpbuf[0-9]/*
\layout Standard
\noindent
This is useful to know when exporting to HTML.
In all other formats (PS, PDF, Ascii, LaTeX, DVI), LyX simply creates the
desired file in your current directory.
With HTML, it copies the HTML page, but not the images and stylefiles that
come with it and are generated by latex2html -- these can simply be copied
from the temporary compilation directory.
Lastly, to produce output you don't even need the GUI, lyx(1) has a number
of commandline options, for instance to generate a PDF file from a given
source file, simply type
\layout Standard
lyx -e pdf my_lyx_source_file.lyx
\layout Standard
\noindent
which produces a fresh PDF file.
I use this for a larger repository of documentations where PS and PDF files
are generated automatically by a script from LyX code.
\layout Section
Internals and general tips
\layout Subsection
Errors, the preamble and hyperlinks
\layout Standard
If the latex compilation fails, an error box is produced like the one below.
Usually, context-sensitive error location is quite good and you can jump
to the error, which is marked in your document by a red Error box, via
ALT-g.
If that does not help, try to look at the stderror output (assuming you
have started lyx from some xterm) or try View -> Latex Logfile.
In some occasions you may be in trouble because a certain document style
was not included (e.g.
`package xyz not found').
This can easily be fixed by adding it in the Latex preamble, which serves
the same purpose for Latex documents as the <head> section does for HTML
-- declaration of global style files, inclusion etc.
To access the Preamble, select Layout -> Document -> Preamble.
For instance, you can add
\layout Standard
\family typewriter
\backslash
usepackage{url} \SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
%% for URLs (also in Bibtex)
\layout Standard
\family typewriter
\backslash
usepackage{ae,aecompl} %% generates nicer PDF output (better fonts)
\layout Standard
\family typewriter
\backslash
usepackage{hyperref} \SpecialChar ~
\SpecialChar ~
%% best at the end, generates PDF with hyperlinks
\layout Standard
\noindent
The last one is well worth checking out.
You probably know these PDF documents which have clickable, coloured links
in them and a bookmarks section where you can choose the section you want
to jump to.
Such documents are created using this package.
Just be sure to add it last in the list since it overrides settings from
other packages (can be tricky but works smoothly in almost all cases).
\layout Subsection
Useful paths
\layout Standard
Apart from making emergency backups and auto-saving files, lyx also keeps
a backup of every file in $HOME/.lyx/backups.
If you have accidentally deleted a lyx file, you can find the latest copy
there.
This is also the place where user-defined style-files are kept ($HOME/.lyx/layou
ts).
If you create one or more style files for yourself, put them here rather
than in /usr/share/lyx/layouts, since the directory contents get erased
on every new installation or update of RPMs.
I found it a good habit to back $HOME/.lyx/ up on a regular basis.
\layout Subsection
Adding LaTeX styles
\layout Standard
If you need to add new style-files for lyx (and latex) to use, there is
a two way process.
First the style file needs to be placed in a directory where latex can
find it.
Usually, you can use any subdirectory of /usr/share/texmf/tex/latex/.
To avoid that an RPM update clears these areas, it is a good idea to create
a subdirectory (e.g.
my_style_files) and to back it up regularly.
Once the new style file resides in that directory, the latex configuration
needs to be updated, which is as simple as running
\layout Standard
texhash
\layout Standard
\noindent
(as root).
If you are curious, you can also try `texconfig'.
Required style files can in almost all cases be found on
\begin_inset LatexCommand \url{http://www.ctan.org}
\end_inset
.
The second step involves to run Edit->Reconfigure under LyX and then restart
it.
\layout Subsection
Roll your own layout
\layout Standard
Okay, this is the sixty second tutorial to defining your own document flavour.
Since we are under Lunix, we can exercise the classical virtues of software
reuse and make something new.
Why write everything from scratch when there is so much out there which
invites to modify it to taste.
Suppose you are a professional tourist and want to write an article about
interesting holiday experiences.
You would like to have something which starts a new section with bold-face
words like
\begin_inset Quotes eld
\end_inset
my funny holiday experience number ...
\begin_inset Quotes erd
\end_inset
-- you get the idea.
Lyx expects a text file which tells it (a) which Latex packages to use
(here we will simple use the article package which is standard) and (b)
what you want to support environment-wise in your document.
The first bit of important information are the first two second lines which
should read like this
\layout Standard
\family typewriter
#% Do not delete the line below; configure depends on this
\layout Standard
\family typewriter
#
\backslash
DeclareLaTeXClass[article]{article -- about holiday stuff }
\layout Standard
\noindent
The argument in square brackets gives the latex package to use, you can
insert several separeted by commata.
The second argument tells Lyx how to label this style, after you have saved
the file in $HOME/.lyx/layouts and run Edit->Reconfigure, you will actually
read the string
\begin_inset Quotes eld
\end_inset
article -- about holiday stuff
\begin_inset Quotes erd
\end_inset
(or whatever you choose to call it) under Layout -> Document -> Layout
-> Document Class.
But we are not finished yet.
First we are lazy and simply import an existing layout called article.layout
(no paths necessary, Lyx searches its layout directory or $HOME/.lyx/layouts)
\layout Standard
\family typewriter
## This is called modification by extension
\layout Standard
\family typewriter
Input article.layout
\layout Standard
\noindent
Next we construct a suitable latex command which has to go into the preamble
(document header).
To put something into the preamble we use the Preamble environment.
\layout Standard
\family typewriter
## this adds the new environment to the LaTeX preamble.
\layout Standard
\family typewriter
Preamble
\layout Standard
\family typewriter
\SpecialChar ~
\SpecialChar ~
\backslash
newtheorem{holiday}{My funniest holiday experience Nr.
}
\layout Standard
\family typewriter
EndPreamble
\layout Standard
\added_space_top smallskip \added_space_bottom smallskip \noindent
Last we need to tell lyx how to use this command
\layout Standard
\family typewriter
Style My_Holiday
\layout Standard
\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
Margin First_Dynamic
\layout Standard
\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
LatexType Environment
\layout Standard
\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
LatexName holiday ## this issues the Latex command
\layout Standard
\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
AlignPossible Block, Left
\layout Standard
\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
LabelType Static
\layout Standard
\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
LabelString "Holiday Experience #.
"
\layout Standard
\family typewriter
End
\layout Standard
\noindent
After editing this file, store it in $HOME/.lyx/layouts, reconfigure, restart
and voila -- you now find an environment called
\begin_inset Quotes eld
\end_inset
My Holiday
\begin_inset Quotes erd
\end_inset
in the style selector.
Here is an example document.
\layout Section
Conclusion
\layout Standard
\noindent
Certainly, if you only have to write your shopping list or a two-paragraph
memo using LyX is somehow overkill.
But if you are looking at texts of more than 500 words where working with
structure and crossreferences is a must, you should check out LyX which
excels for this kind of task.
\layout Itemize
Lyx wiki:
\begin_inset LatexCommand \htmlurl{http://wiki.lyx.org/}
\end_inset
\layout Itemize
Lyx Mailing list:
\begin_inset LatexCommand \url{http://www.lyx.org/internet/mailing.php3}
\end_inset
\layout Itemize
Tips & Tricks
\begin_inset LatexCommand \htmlurl{http://www.texnik.de/}
\end_inset
\layout Bibliography
\bibitem {lyx-intro}
\emph on
\begin_inset Quotes eld
\end_inset
Introduction to LyX
\emph default
\begin_inset Quotes erd
\end_inset
.
By the LyX Team.
Available under Help -> Introduction.
\layout Bibliography
\bibitem {key-1}
"
\emph on
Outliners and Mind Mapping
\emph default
".
By Jimmy O'Regan.
Linux Gazette Nr.
108, November 2004.
\begin_inset LatexCommand \url{http://linux.open.ac.uk/108/oregan.html}
\end_inset
\the_end