X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Frunning.itely;h=995119e57b061b5122dfb412a7b05e4de04c1a50;hb=0fa6f042cccacb643d46781dde23617c71a9753e;hp=864f90555fccbba691a4057bf51c17d78c841ffa;hpb=88cfc9ee61dece9cffff98ab7f10318633698c39;p=lilypond.git

diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely
index 864f90555f..995119e57b 100644
--- a/Documentation/usage/running.itely
+++ b/Documentation/usage/running.itely
@@ -246,6 +246,10 @@ which formats should be written.  Choices for @code{format} are
 
 Example: @code{lilypond -fpng @var{filename}.ly}
 
+@noindent
+For @code{svg} and @code{eps} formats use the @code{-dbackend} option.
+See @ref{Advanced command line options for LilyPond}.
+
 @item -h, --help
 Show a summary of usage.
 
@@ -411,8 +415,10 @@ Show the warranty with which GNU LilyPond comes.  (It comes with
 
 @table @code
 
-@item -d@var{[option-name]}=@var{[value]},--define-default=@var{[option-name]}=@var{[value]}
-This sets the equivalent internal Scheme function to @var{value}.
+@item -d@var{[option-name]}=@var{[value]},
+--define-default=@var{[option-name]}=@var{[value]}
+This sets the equivalent internal Scheme function to @var{value}.  For
+example;
 
 @example
 -dbackend=svg
@@ -420,7 +426,7 @@ This sets the equivalent internal Scheme function to @var{value}.
 
 If a @var{value} is not supplied, then the default value is used.  The
 prefix @code{no-} may be added to @var{option-name} to switch @q{off} an
-option, e.g.
+option.  For example;
 
 @cindex point and click, command line
 
@@ -445,47 +451,73 @@ default values:
 
 @item @code{anti-alias-factor}
 @tab @code{1}
-@tab Render at higher resolution (using given factor) and scale down
-result to prevent @q{jaggies} in @code{PNG} images.
+@tab Render at a higher resolution (using the given factor) and scale
+down the result to prevent @q{jaggies} in @code{PNG} images.
 
 @item @code{aux-files}
 @tab @code{#t}
-@tab Create @code{.tex}, @code{.texi}, @code{.count} files in the
-@code{EPS} backend.
+@tab Create @code{.tex}, @code{.texi} and @code{.count} files when used
+with the @code{eps} backend option.
 
 @item @code{backend}
 @tab @code{ps}
-@tab Select backend.  Postscript files (default) include @code{TTF},
-@code{Type1} and @code{OTF} fonts.  No subsetting of these fonts is
-done.  Using @q{oriental} character sets can lead to very large files.
+@tab This is the default setting.  Postscript files (default) include
+@code{TTF}, @code{Type1} and @code{OTF} fonts.  No @q{subsetting} of
+these fonts is done.  Be aware that using @q{oriental} character sets
+can lead to very large file sizes.
 
 @item
 @tab @code{eps}
-@tab Encapsulated PostScript.  This dumps every page (system) as a
-separate @file{EPS} file, without fonts, and as one collated @file{EPS}
-file with all pages (systems) including fonts.  Used as default by
-@command{lilypond-book}.
+@tab Used as default by the @command{lilypond-book} command.  This dumps
+every page as both a single file with all pages and fonts included and
+as separate encapsulated postscript files for each page but without fonts
+included.
 
 @item
 @tab @code{null}
-@tab Do not output a printed score; has the same effect as
+@tab Do not output a printed score.  This has the same effect as
 @code{-dno-print-pages}.
 
 @item
-@tab @code{svg}
-@tab Scalable Vector Graphics.  This creates a single SVG file,
-without embedded fonts, for every page of output.  It is recommended to
-install the Century Schoolbook fonts, included with your LilyPond
-installation, for optimal rendering.  Under UNIX, simply copy these
-fonts from the LilyPond directory (typically
-@file{/usr/share/lilypond/VERSION/fonts/otf/}) to @file{~/.fonts/}.
-There is also an option @code{svg-woff} (below) for use of woff font
-files in the SVG backend.
+@tab @code{scm}
+@tab This dumps out the raw, internal Scheme-based drawing commands.
 
 @item
-@tab @code{scm}
-@tab Dump of the raw, internal Scheme-based drawing commands.
+@tab @code{svg}
+@tab Scalable Vector Graphics.
+A single SVG file is created for every page of output.  Music glyphs
+are encoded as vector graphics, but text fonts are @emph{not} embedded
+in the SVG files.  Any SVG viewer will therefore need the relevant text
+fonts to be available to it for proper rendering of both text and
+lyrics.  It is recommended to not use font @q{lists} or @q{aliases}
+in case an SVG viewer is unable to handle them.  When using
+@emph{Web Open Font Format} (WOFF) files the additional
+@code{--svg-woff} switch is required.
+@end multitable
+
+@noindent
+@strong{Note for backend svg output:}
+By default in svg output LilyPond will use the generic
+@code{font-family} values of @code{serif}, @code{sans-serif}, or
+@code{monospace}.  Therefore, when using the backend @code{svg} command
+you should explicitly define particular default fonts in your source
+file;
 
+@quotation
+@verbatim
+\paper  {
+  #(define fonts
+    (make-pango-font-tree "TeX Gyre Schola"
+                          "TeX Gyre Heros"
+                          "TeX Gyre Cursor"
+                          (/ staff-height pt 20)))
+}
+@end verbatim
+@end quotation
+
+Also see @ruser{Entire document fonts}.
+
+@multitable @columnfractions .33 .16 .51
 @item @code{check-internal-types}
 @tab @code{#f}
 @tab Check every property assignment for types.
@@ -548,6 +580,10 @@ compilation.
 @tab @code{#f}
 @tab Dump output signatures of each system. Used for regression testing.
 
+@item @code{embed-source-code}
+@tab @code{#f}
+@tab Embed the LilyPond source files inside the generated PDF document.
+
 @item @code{eps-box-padding}
 @tab @code{#f}
 @tab Pad left edge of the output EPS bounding box by the given amount
@@ -751,7 +787,13 @@ size increases in PDF files.
 
 @item @code{svg-woff}
 @tab @code{#f}
-@tab Use woff font files in SVG backend.
+@tab This option is required when using Web Open Font Format (WOFF) font
+files with the backend @code{svg} command.  A single SVG file is created
+for every page of output.  Apart from LilyPond's own music glyphs, no
+other font information will be included.  Any SVG viewer will therefore
+require the fonts be available to it for the proper rendering of both
+text and lyrics.  It is also recommended not to use any font @q{aliases}
+or @q{lists} in case the SVG viewer cannot handle them.
 
 @item @code{trace-memory-frequency}
 @tab @code{#f}
@@ -1166,8 +1208,7 @@ staves are introduced in parallel, i.e. simultaneously:
 @end lilypond
 
 @node Warning this voice needs a voiceXx or shiftXx setting
-@unnumberedsubsec Warning this voice needs a @code{@bs{}voiceXx}
- or @code{@bs{}shiftXx} setting
+@unnumberedsubsec Warning this voice needs a @code{@bs{}voiceXx} or @code{@bs{}shiftXx} setting
 
 If notes from two different voices with stems in the same direction
 occur at the same musical moment, but the voices have no