X-Git-Url: https://git.lyx.org/gitweb/?a=blobdiff_plain;f=lib%2Fdoc%2FCustomization.lyx;h=edf09186a7f51a7635c3d5c9c3d7a2772668d496;hb=ea74988acc29767d2d34d9e4466e4993eb544171;hp=fa0ec9924d5eccfdbd02441f157e28acfb32effd;hpb=8acae542414b8728b68052926f99e69c3a10b4c5;p=lyx.git diff --git a/lib/doc/Customization.lyx b/lib/doc/Customization.lyx index fa0ec9924d..edf09186a7 100644 --- a/lib/doc/Customization.lyx +++ b/lib/doc/Customization.lyx @@ -1,5 +1,5 @@ #LyX 1.5.0svn created this file. For more info see http://www.lyx.org/ -\lyxformat 263 +\lyxformat 276 \begin_document \begin_header \textclass book @@ -39,8 +39,10 @@ \paperpagestyle headings \tracking_changes false \output_changes false -\author "usti" -\author "Jean-Marc Lasgouttes" +\author "" +\author "" +\author "" +\author "" \end_header \begin_body @@ -1698,75 +1700,191 @@ s. \end_layout \begin_layout Section -Converters, Formats, Viewers, Editors and Copiers +\begin_inset LatexCommand label +name "sec:converters-etc" + +\end_inset + +Converters, Formats, and Copiers \end_layout \begin_layout Standard LyX has a powerful mechanism to convert to and from any file format using external programs. - Define a pair of formats, e.g. -\family typewriter -LaTeX -\family default - and -\family typewriter -PDF -\family default -. - Now define a converter from one format to the other. - In our example, two possible mechanisms exist. \end_layout -\begin_layout Enumerate -A direct conversion, from LaTeX to PDF using pdflatex +\begin_layout Subsection +Formats \end_layout -\begin_layout Enumerate -A more convoluted route using intermediate formats and converters: LaTeX - to DVI (using latex) to PostScript® (using dvips) to PDF (using ps2pdf). +\begin_layout Standard +The first step is to define your file formats, e.g. + PDF, if they are not already defined. + To do so, open the +\family sans +\bar under +T +\bar default +ools\SpecialChar \menuseparator + +\bar under +P +\bar default +references:Converters +\family default + dialog. + Enter a new format name; a new GUI name (used in, e.g., the View and Export + menus); and a file extension. + These are required. + \end_layout \begin_layout Standard -LyX will always choose the shortest possible route, so you must specify - two different Format names for +There are also two flags that can be set using the checkboxes in the dialog. + The \family typewriter -.pdf +document \family default - files to be able to use either. - Both are included by default in the + flag tells LyX that a format is suitable for document export. + If this flag is set for a format, and if a suitable conversion route exists, + then the format will appear in the \family sans -Preferences +\bar under +F +\bar default +ile\SpecialChar \menuseparator + +\bar under +E +\bar default +xport \family default - dialog. - Have a look and then invent your own! + menu. + The format will also appear in the +\family sans +\bar under +V +\bar default +iew +\family default + menu if it has a viewer associated with it. + (See below.) Pure image formats (e.g.\InsetSpace ~ + +\family typewriter +png +\family default +) should not have this flag set; formats that can both represent vector + graphics and documents (e.g.\InsetSpace ~ + +\family typewriter +pdf +\family default +) should have it set. +\end_layout + +\begin_layout Standard +The +\family typewriter +vector +\family default + flag tells LyX whether a format can contain vector graphics. + This information is used to determine the target format of included graphics + for +\family typewriter +pdflatex +\family default + export. + Included graphics may need to be converted to either +\family typewriter +pdf +\family default +, +\family typewriter +png +\family default + or +\family typewriter +jpg +\family default +, since +\family typewriter +pdflatex +\family default + cannot handle other image formats. + If an included graphic is not already in +\family typewriter +pdf +\family default +, +\family typewriter +png +\family default + or +\family typewriter +jpg +\family default + format, it is converted to +\family typewriter +pdf +\family default + if the +\family typewriter +vector +\family default + flag of the format is set, and otherwise to +\family typewriter +png +\family default +. \end_layout \begin_layout Standard -Moreover, each Format can have a Viewer associated with it. +A Format can have a Viewer associated with it. For example, you might want to use \family typewriter ghostview \family default - to examine PostScript® files, or + to look at PostScript® files, or \family typewriter xdvi \family default to preview the LaTeX output. - You can alter the viewer to use (and what options to pass to it) via the - + You can enter the program to use as a viewer (and what options to pass + to it) in the Viewer field. + You can also modify the viewer associated with a pre-defined format simply + by changing what you find in this field, clicking the \family sans -\bar under -T -\bar default -ools\SpecialChar \menuseparator +Modify +\family default + button, and then (if you're sure you want to do this) clicking the +\family sans +Apply +\family default + or +\family sans +Save +\family default + button. +\begin_inset Foot +status collapsed -\bar under -P -\bar default -references:Conversion +\begin_layout Standard +Changes to the formats are kept in the +\family typewriter +preferences \family default - dialog. + file in you local LyX directory (for example, +\family typewriter +$HOME/.lyx/ +\family default +). + If you want to restore the defaults, edit this file and delete the lines + in the Formats and Converters sections. +\end_layout + +\end_inset + For example, to change the \family typewriter dvi @@ -1790,28 +1908,16 @@ odify \end_layout \begin_layout Standard -If the operating system has a default viewer associated to a format it is - used instead of the one you can define via the -\family sans -\bar under -T -\bar default -ools\SpecialChar \menuseparator - -\bar under -P -\bar default -references:Conversion -\family default - dialog. - This does currently only work in the Windows® and Mac OS X ports of LyX, - but it is planned to implement this feature on all other ports that can - support it, too. +If the operating system has a default viewer associated to a format, this + viewer is used instead of the one defined here in the Windows® and OS X + versions of LyX. + (It is planned to implement this feature on other platforms.) \end_layout \begin_layout Standard Editors are like viewers: Each Format can have an Editor associated to it, - and they can be altered via the + entered in the Editor field, and the editor associated with a format can + be altered via the \family sans \bar under T @@ -1821,10 +1927,10 @@ ools\SpecialChar \menuseparator \bar under P \bar default -references:Conversion +references:Converters \family default dialog. - LyX uses them whenever an included file + LyX will launch the associated editor whenever an included file \begin_inset Foot status collapsed @@ -1842,128 +1948,262 @@ This can be an included needs to be edited. \end_layout +\begin_layout Subsection +Copiers +\end_layout + \begin_layout Standard -Finally, each Format can have a Copier associated to it. - Since all conversions from one Format to another take place in a temporary +Each Format can have a Copier associated with it. + These are defined in the +\family sans +\bar under +T +\bar default +ools\SpecialChar \menuseparator + +\bar under +P +\bar default +references:Copiers +\family default + dialog. + Since all conversions from one Format to another take place in LyX's temporary directory, it is sometimes necessary to modify a file before copying it - to the temporary directory + to the temporary directory in order that the conversion may be performed. \begin_inset Foot status collapsed \begin_layout Standard -For example, the file may reference other files with relative filenames, - which will become invalid in the temporary directory +For example, the file may refer to other files---images, for example---using + relative filenames, and these may become invalid when the file is copied + to the temporary directory. \end_layout \end_inset -. This is done by the Copier: It copies a file to (or from) the temporary directory and may modify it in the process. + \end_layout \begin_layout Standard -Sometimes LyX needs to know a bit more about the properties of a format. - These bits can be specified with flags. - Currently there are two of them: -\end_layout - -\begin_layout Standard -The -\family typewriter -document -\family default - flag tells LyX that a format is suitable for document export. - If this flag is set for a format, and if a suitable conversion route exists, - then the format will appear in the -\family sans -\bar under -F -\bar default -ile\SpecialChar \menuseparator +Copiers may also be used for other purposes. + For example, if appropriate converters are found, LyX will automatically + install copiers for the html and wordhtml formats. + When these formats are exported, the copier sees to it that not just the + main HTML file but various associated files (style files, images, and the + like) are also copied, and all these files are written to a subdirectory + of the directory in which the original LyX file was found. + The copier may of course be customized. + The optional -e argument takes a comma-separated list of extensions to + be copied; if it is omitted, all files will be copied. + The -t argument determines the extension added to the generated directory. + By default, it is +\begin_inset Quotes eld +\end_inset -\bar under -E -\bar default -xport -\family default - menu. - The format will also appear in the -\family sans -\bar under -V -\bar default -iew -\family default - menu if it has a viewer associated to it. - Pure image formats (e.g.\InsetSpace ~ +LyXconv +\begin_inset Quotes erd +\end_inset +, so HTML generated from \family typewriter -png +/path/to/filename.lyx \family default -) do not have this flag set, formats that can both represent images and - documents (e.g.\InsetSpace ~ - + will end up in \family typewriter -pdf +/path/to/filename.html.LyXconv \family default -) do have it set. +. + \end_layout \begin_layout Standard -The -\family typewriter -vector -\family default - flag tells LyX whether a format can contain vector graphics. - This information is used to determine the target format of included graphics - for -\family typewriter -pdflatex -\family default - export. - Included graphics may need to be converted to either -\family typewriter -pdf -\family default -, -\family typewriter -png -\family default - or -\family typewriter -jpg -\family default -, since -\family typewriter -pdflatex -\family default - cannot handle other image formats. - If an included graphic is not already in +The definitions of the copiers may use four variables: +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +$$s The LyX system directory (e.g., \family typewriter -pdf +/usr/share/lyx \family default -, +). +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +$$i The input file +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +$$o The output file +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +$$l The `LaTeX name' +\end_layout + +\begin_layout Standard +The latter is to be given in a form suitable for inclusion in a LaTeX \family typewriter -png + +\backslash +include \family default - or + command and is relevant only when exporting files suitable for such inclusion. +\end_layout + +\begin_layout Subsection +Converters +\end_layout + +\begin_layout Standard +To define a converter from one format to another---e.g., LaTeX to PDF---select + the Converters panel. + Choose the `From' and `To' formats, and then enter the program to be used + in the conversion in the Converter field. + +\end_layout + +\begin_layout Standard +You do not have to define converters between all the Formats between which + you want to convert. + For example, you will note that there is no `LyX to PostScript®' converter, + but LyX will export PostScript®. + It does so by first creating a LaTeX file (no converter needs to be defined + for this) which it then converts to DVI using the `LaTeX to DVI' converter, + and then it converts the resulting DVI file to PostScript®. + LyX finds such `chains' of converters automatically, and it will always + choose the shortest chain possible. + You can, though, still define multiple conversion methods between file + formats. + For example, the standard LyX configuration provides three ways to convert + LaTeX to PDF: Directly, using pdflatex; via (DVI and) PostScript®, using + ps2pdf; or via DVI, using dvipdfm. + To define such alternate chains, you must define multiple target `file + formats'. + In the standard configuration, for example, formats named `pdf', `pdf2', + and `pdf3' are defined, all of which share the extension `pdf'. + +\end_layout + +\begin_layout Standard +Several variables can be used in the definition of converters: +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +$$s The LyX system directory (e.g., \family typewriter -jpg +/usr/share/lyx \family default - format it is converted to -\family typewriter -pdf +). +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +$$i The input file +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +$$o The output file +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +$$b The base filename of the input file +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +$$p The path to the input file +\end_layout + +\begin_layout Standard +In the `Extra Flag' field you can enter as many of the following flags as + you wish, separated by commas: +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +latex This converter runs some form of LaTeX. + (This will make LyX's LaTeX error logs available.) +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +needaux Needs the LaTeX .aux file for the conversion. +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +xml Output is XML. +\end_layout + +\begin_layout Standard +The following three variables are not really flags at all but take an argument + in the +\family sans +key\InsetSpace ~ += value \family default - if the + format. +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +parselog If set, the converter's standard error will be redirected to a + file \family typewriter -vector +infile.out \family default - flag of the format is set, and otherwise to +, and the script given as argument will be run as: \family typewriter -png +script infile.log \family default . + The argument may contain $$s. +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +resultdir The name of the directory in which the +\emph on +converter +\emph default + will dump the generated files. + LyX will not create this directory, and it does not copy anything into + it, though it will copy this directory to the destination. + The argument may contain $$b, which will be replaced by the basename of + the input and output files, respectively, when the directory is copied. +\newline +Note + that resultdir and usetempdir make no sense together. + The latter will be ignored if the former is given. +\end_layout + +\begin_layout List +\labelwidthstring 00.00.0000 +resultfile Determines the output filename and may, again, contain $$b. + Sensible only with resultdir, and optional even then; if not given, it + defaults to `index'. + +\end_layout + +\begin_layout Standard +None of these last three are presently used in any of the converters that + are installed with LyX. + But see section +\begin_inset LatexCommand ref +reference "sub:LyX-and-Literate" + +\end_inset + + of the Extended Features guide for some examples of how you might use parselog. \end_layout \begin_layout Section @@ -5728,7 +5968,7 @@ DeclareLaTeXClass[article,foo.sty]{article (with my own headings)} \begin_layout Standard This indicates that your text class uses the foo.sty package. - Finally, it is also possible to declare classes for SGML and DocBook code. + Finally, it is also possible to declare classes for DocBook code. Typical declarations will look like \end_layout @@ -5743,20 +5983,6 @@ This indicates that your text class uses the foo.sty package. \size small # \backslash -DeclareSGMLClass{SGML (LinuxDoc)} -\end_layout - -\begin_layout Standard -or -\end_layout - -\begin_layout LyX-Code -#% Do not delete the line below; configure depends on this -\end_layout - -\begin_layout LyX-Code -# -\backslash DeclareDocBookClass[article]{SGML (DocBook article)} \end_layout @@ -5987,86 +6213,30 @@ reference "sec:classoptions" \family typewriter \series medium -ProvidesAmsmath -\family default -\series default - [ -\family typewriter -\emph on -0 -\emph default -, 1 -\family default -] Whether the class already loads the -\family typewriter -amsmath -\family default - package. - This is the case of the -\family typewriter -amsart -\family default - and -\family typewriter -amsbook -\family default - document classes. -\end_layout - -\begin_layout Description - -\family typewriter -\series medium -ProvidesMakeidx +Provides \family default \series default - [ +[ \family typewriter -\emph on -0 -\emph default -, 1 -\family default -] Whether the class already provides the functionality of the -\family typewriter -makeidx -\family default - package. - This is the case of the -\family typewriter -amsart -\family default - and -\family typewriter -amsbook -\family default - document classes. -\end_layout - -\begin_layout Description - -\family typewriter -\series medium -ProvidesUrl +string \family default -\series default - [ +] [ \family typewriter \emph on 0 \emph default , 1 \family default -] Whether the class already provides the functionality of the +] Whether the class already provides the feature \family typewriter -url -\family default - package. - This is the case of the -\family typewriter -AASTeX + string \family default - document class. +. + A feature is in general the name of a package (amsmath, makeidx, \SpecialChar \ldots{} +) or a + macro (url, boldsymbol,\SpecialChar \ldots{} +); the complete list of supported features is unfortunat +ely not documented. \end_layout \begin_layout Description @@ -7278,12 +7448,25 @@ LabelStringAppendix \family typewriter string="" \family default -] If non-empty, this is used inside the appendix instead of +] This is used inside the appendix instead of \family typewriter LabelString \family default . - + Note that every +\family typewriter +LabelString +\family default + statement resets +\family typewriter +\series medium +LabelStringAppendix +\family default +\series default + too +\family typewriter +\series medium +. \end_layout \begin_layout Description @@ -9276,10 +9459,6 @@ ReferencedFile docbook-xml "$$AbsPath$$Basename.eps" FormatEnd \end_layout -\begin_layout LyX-Code -Format LinuxDoc -\end_layout - \begin_layout LyX-Code Product "[XFig: $$FName]" \end_layout @@ -9470,7 +9649,7 @@ The Format section \family typewriter \series medium Format\InsetSpace ~ -LaTeX|PDFLaTeX|PlainText|DocBook|LinuxDoc +LaTeX|PDFLaTeX|PlainText|DocBook \family default \series default The primary document file format that this format definition is for. @@ -9480,8 +9659,7 @@ LaTeX|PDFLaTeX|PlainText|DocBook|LinuxDoc Format \family default section for all formats. - Use a dummy text when no representation is available (see the LinuxDoc - format in the example above). + Use a dummy text when no representation is available. Then you can at least see a reference to the external material in the exported document. \end_layout