#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 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 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