Create HTML, EPUB, and other files from source documents.yelp-build
Command
Mallard
DocBook 4
DocBook 5
yelp-build cache
Yes
No
No
yelp-build epub
Yes
No
No
yelp-build html
Yes
Yes
Yes
yelp-build xhtml
Yes
Yes
Yes
yelp-build cache
Create a Mallard cache
file from a Mallard document. A cache file is necessary to build
other formats from Mallard documents. The other build commands generate a
cache file automatically, but sometimes it's useful to provide a cache file
explicitly. For example, if you only want to output the HTML for one page,
you might run:
yelp-build html foo.page
But then yelp-build will assume that foo.page is
the entirety of the document, and will create a cache file for just that page.
If you have a cache file with the cache for all pages, say index.cache,
you can instead run:
yelp-build html -c index.cache foo.page
You can pass yelp-build cache a list of page files, or just pass
it a directory to have it cache all page files in that directory.
yelp-build cache *.page
yelp-build cache .
By default, the output cache file name is index.cache. Use the -o
option to output a different file name.
yelp-build cache -o foo.cache .yelp-build epub
Output an EPUB file, currently for
Mallard documents only. An EPUB file is a special zip file containing XHTML files,
stylesheets and other supporting files, and EPUB-specific files that specify the
document structure. You can pass yelp-build epub a list of page files,
or just pass it a directory to have it use all page files in that directory.
Just as for yelp-build html or yelp-build xhtml, you can
pass a custom cache file with the -c option, a customization stylesheet
with the -x option, a path for external files with the -p
option, and the option to ignore missing media files with -i. See the
documentation for yelp-build html for more information. Note that
setting URL roots for JavaScript, CSS, and icon files is usually not a good idea
for EPUB, because yelp-build epub places those files in a fixed
location inside the zip file.
By default, the output file name is index.epub. Use the -o
option to specify a different output file.
yelp-build html
Output HTML files from a Mallard or DocBook document. The output file
names are taken from the IDs in the XML, regardless of the input file names.
For Mallard, you can pass yelp-build html a list of page files,
or just pass it a directory to have it create HTML for all page files in
that directory. For DocBook, pass the top-level XML file.
yelp-build html index.page foo.page bar.page
yelp-build html .
yelp-build html index.docbook
By default, files are output to the current working directory. Use the
-o option to specify an output directory.
mkdir html_out
yelp-build html -o html_out .
If you use the -o option, yelp-build html will also
copy media files to the output directory and create the appropriate directory
structure under the output directory. It will look inside the XML for tags
like media and imagedata to find media files to copy.
Sometimes, some media files and external resources are not under the same
path. This happens, for example, when you generate translated files in another
directory but don't create copies of untranslated files. Pass a path of other
base directories to use for files lookups with the -p option to
resolve these files.
If a referenced media file does not exist (potentially anywhere within the
path), yelp-build will still attempt to copy it, which will produce
warnings on stderr. To make yelp-build check for the file's existence
before copying, use the -i option. Be careful: without the warnings,
you could easily end up with broken images in your document.
For Mallard documents, a cache file is created for you by default from the
pages you pass on the command line. You can also pass a cache file explicitly
with the -c option. This is useful if you only want to rebuild a
few pages, but you want yelp-build to know about all the pages in
the document for linking purposes. See yelp-build cache above.
When creating HTML, yelp-build also outputs CSS and JavaScript
files, as well as PNG files for icons and watermarks. What it outputs depends
on what's in your document. For JavaScript, a static set of files are copied,
as well as additional JavaScript files for syntax highlighting. Which files
are copied depends on what syntaxes you use in program listings and code
blocks. For CSS, yelp-build creates a separate CSS file for each
top-level language. For icons and watermarks, which images are copied depends
on what types of admonitions and other elements you use.
The stylesheets that do the conversion to HTML are flexible and customizable.
You can add customizations to affect the layout and presentation. You can pass
a customization stylesheet to yelp-build html using the -x option.
yelp-build html -x custom.xsl .
The customization stylesheet should not include or import the Yelp stylesheets.
The yelp-build command will automatically create a wrapper stylesheet
that includes the customization and imports the Yelp stylesheets.
The stylesheets allow you to specify URL roots for CSS, JavaScript, and icon
files. By default, it's the same directory as the output HTML files. You can
override these by setting parameters in a customization stylesheet, but
yelp-build html does not change where it outputs those files. If you
set these parameters to use common files on your web site, you must manage those
files manually.
yelp-build xhtml
Output XHTML files from a Mallard or DocBook document. This works exaclty
like the yelp-build html command and allows the same options, but
it serializes the files as XML. See the documentation for
yelp-build html for details.