Commit 3c0f83d8 authored by Shaun McCance's avatar Shaun McCance

help/C: Adding some docs in Mallard

parent a572f35b
<page xmlns="http://projectmallard.org/1.0/"
type="guide"
id="index">
<info>
</info>
<title>Yelp Tools</title>
<p>The <sys>yelp-tools</sys> package contains small programs that help you
create, edit, manage, and publish your
<link href="http://projectmallard.org/">Mallard</link> or
<link href="http://docbook.org/">DocBook</link> documentation.</p>
</page>
<page xmlns="http://projectmallard.org/1.0/"
id="yelp-build">
<info>
<link type="guide" xref="index"/>
<desc>Create HTML, EPUB, and other files from source documents.</desc>
</info>
<title><cmd>yelp-build</cmd></title>
<table>
<thead>
<tr>
<td><p>Command</p></td>
<td><p>Mallard</p></td>
<td><p>DocBook 4</p></td>
<td><p>DocBook 5</p></td>
</tr>
</thead>
<tbody>
<tr>
<td><p><cmd xref="#cache">yelp-build cache</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#epub">yelp-build epub</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#html">yelp-build html</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
<tr>
<td><p><cmd xref="#html">yelp-build xhtml</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
</tbody>
</table>
<section id="cache">
<title><cmd>yelp-build cache</cmd></title>
<p>Create a <link href="http://projectmallard.org/cache/1.0/">Mallard cache
file</link> 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:</p>
<screen>yelp-build html foo.page</screen>
<p>But then <cmd>yelp-build</cmd> will assume that <file>foo.page</file> 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 <file>index.cache</file>,
you can instead run:</p>
<screen>yelp-build html -c index.cache foo.page</screen>
<p>You can pass <cmd>yelp-build cache</cmd> a list of page files, or just pass
it a directory to have it cache all page files in that directory.</p>
<screen>yelp-build cache *.page
yelp-build cache .</screen>
<p>By default, the output cache file name is index.cache. Use the <cmd>-o</cmd>
option to output a different file name.</p>
<screen>yelp-build cache -o foo.cache .</screen>
</section>
<section id="epub">
<title><cmd>yelp-build epub</cmd></title>
<p>Output an <link href="http://idpf.org/epub">EPUB</link> 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 <cmd>yelp-build epub</cmd> a list of page files,
or just pass it a directory to have it use all page files in that directory.</p>
<p>Just as for <cmd>yelp-build html</cmd> or <cmd>yelp-build xhtml</cmd>, you can
pass a custom cache file with the <cmd>-c</cmd> option, a customization stylesheet
with the <cmd>-x</cmd> option, a path for external files with the <cmd>-p</cmd>
option, and the option to ignore missing media files with <cmd>-i</cmd>. See the
documentation for <cmd>yelp-build html</cmd> for more information. Note that
setting URL roots for JavaScript, CSS, and icon files is usually not a good idea
for EPUB, because <cmd>yelp-build epub</cmd> places those files in a fixed
location inside the zip file.</p>
<p>By default, the output file name is <file>index.epub</file>. Use the <cmd>-o</cmd>
option to specify a different output file.</p>
</section>
<section id="html">
<title><cmd>yelp-build html</cmd></title>
<p>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 <cmd>yelp-build html</cmd> 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.</p>
<screen>
yelp-build html index.page foo.page bar.page
yelp-build html .
yelp-build html index.docbook
</screen>
<p>By default, files are output to the current working directory. Use the
<cmd>-o</cmd> option to specify an output directory.</p>
<screen>
mkdir html_out
yelp-build html -o html_out .
</screen>
<p>If you use the <cmd>-o</cmd> option, <cmd>yelp-build html</cmd> 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 <code>media</code> and <code>imagedata</code> to find media files to copy.</p>
<p>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 <cmd>-p</cmd> option to
resolve these files.</p>
<p>If a referenced media file does not exist (potentially anywhere within the
path), <cmd>yelp-build</cmd> will still attempt to copy it, which will produce
warnings on stderr. To make <cmd>yelp-build</cmd> check for the file's existence
before copying, use the <cmd>-i</cmd> option. Be careful: without the warnings,
you could easily end up with broken images in your document.</p>
<p>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 <cmd>-c</cmd> option. This is useful if you only want to rebuild a
few pages, but you want <cmd>yelp-build</cmd> to know about all the pages in
the document for linking purposes. See <cmd>yelp-build cache</cmd> above.</p>
<p>When creating HTML, <cmd>yelp-build</cmd> 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, <cmd>yelp-build</cmd> 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.</p>
<p>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 <cmd>-x</cmd> option.</p>
<screen>yelp-build html -x custom.xsl .</screen>
<p>The customization stylesheet should not include or import the Yelp stylesheets.
The <cmd>yelp-build</cmd> command will automatically create a wrapper stylesheet
that includes the customization and imports the Yelp stylesheets.</p>
<!--
For information
about the extension points and how to customize the stylesheets, see ?Yelp XSL.
-->
<p>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
<cmd>yelp-build html</cmd> 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.</p>
</section>
<section id="xhtml">
<title><cmd>yelp-build xhtml</cmd></title>
<p>Output XHTML files from a Mallard or DocBook document. This works exaclty
like the <cmd>yelp-build html</cmd> command and allows the same options, but
it serializes the files as XML. See the documentation for
<cmd>yelp-build html</cmd> for details.</p>
</section>
</page>
<page xmlns="http://projectmallard.org/1.0/"
id="yelp-check">
<info>
<link type="guide" xref="index"/>
<desc>Validate documents, check link integrity, find orphaned
pages, and perform various other checks.</desc>
</info>
<title><cmd>yelp-check</cmd></title>
<table>
<thead>
<tr>
<td><p>Command</p></td>
<td><p>Mallard</p></td>
<td><p>DocBook 4</p></td>
<td><p>DocBook 5</p></td>
</tr>
</thead>
<tbody>
<tr>
<td><p><cmd xref="#comments">yelp-check comments</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
<tr>
<td><p><cmd xref="#hrefs">yelp-check hrefs</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
<tr>
<td><p><cmd xref="#ids">yelp-check ids</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#license">yelp-check license</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#links">yelp-check links</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
<tr>
<td><p><cmd xref="#media">yelp-check media</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
<tr>
<td><p><cmd xref="#orphans">yelp-check orphans</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#status">yelp-check status</cmd></p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
</tr>
<tr>
<td><p><cmd xref="#validate">yelp-check validate</cmd></p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
</tr>
</tbody>
</table>
<section id="comments">
<title><cmd>yelp-check comments</cmd></title>
<p>Print the editorial comments in a Mallard or DocBook document. Both
Mallard and DocBook allow editors to embed remarks in a document that
are not normally shown when formatting the document. (These remarks
are displayed by Yelp when using the <cmd>--editor-mode</cmd> option.)
Mallard uses the <code>comment</code> element, and DocBook uses the
<code>remark</code> element.</p>
<p>For Mallard documents, you can pass <cmd>yelp-check comments</cmd>
a list of page files, or you can pass it a directory to process all
page files in that directory. For DocBook, you can pass any DocBook
file, including any well-formed files that are included in a top-level
file.</p>
<p>Mallard comments are printed with the enclosing page and section ID,
the author of the comment, and the date the comment was made. Mallard
comments allow any block content, but <cmd>yelp-check comments</cmd>
cannot format all block content in plain text. Any content that is not
in a <code>p</code> element currently results in a FIXME statement.</p>
<p>DocBook comments are printed with the closest enclosing ID and the
value of the <code>revisionflag</code> attribute.</p>
</section>
<section id="hrefs">
<title><cmd>yelp-check hrefs</cmd></title>
<p>Check the target of all external links in a Mallard or DocBook
document. For Mallard documents, <cmd>yelp-check hrefs</cmd> uses
all <code>href</code> attributes in the document. For DocBook
documents, it uses the <code>url</code> attribute of all
<code>ulink</code> elements as well as all <code>xlink:href</code>
attributes in the document. In both cases, <sys>mailto:</sys>
links are excluded.</p>
<p>For Mallard documents, you can pass <cmd>yelp-check hrefs</cmd>
a list of page files, or you can pass it a directory to process all
page files in that directory. For DocBook, you can pass any DocBook
file, including any well-formed files that are included in a top-level
file.</p>
<p>If a URL is relative, <cmd>yelp-check hrefs</cmd> checks for the
file locally. If a URL is absolute, it uses <cmd>curl</cmd> to check
the HTTP status of the resource.</p>
</section>
<section id="ids">
<title><cmd>yelp-check ids</cmd></title>
<p>Check if the <code>id</code> attributes of pages match the base
file name (without the <file>.page</file> extension) of the page
files they're defined in. It is not mandatory for them to match in
Mallard, but it's generally considered a best practice.</p>
</section>
<section id="license">
<title><cmd>yelp-check license</cmd></title>
<p>Report the license of Mallard page files, taken from the
<code>license</code> element. The license is reported based on
the <code>href</code> attribute. The block content of the
license element is not used at all. For certain known licenses
(such as those from GNU and Creative Commons), a shortened
identifier is shown instead of the full URL. If a license
element does not have an <code>href</code> attribute, it is
listed as unknown.</p>
<p>Pages may have multiple <code>license</code> elements. If
they do, the license identifiers will all be reported, joined
with a comma. If a page has no license element, it is reported
as none.</p>
<p>You can restrict which licenses are shown using the following
options:</p>
<terms>
<item>
<title><cmd>--only <var>LICENSES</var></cmd></title>
<p>Only show pages that have a license from the space-separated
list <var>LICENSES</var>.</p>
</item>
<item>
<title><cmd>--except <var>LICENSES</var></cmd></title>
<p>Only show pages that do not any license in the
space-separated list <var>LICENSES</var>.</p>
</item>
</terms>
<p>You can also get a summary of which licenses are in a document:</p>
<terms>
<item>
<title><cmd>--totals</cmd></title>
<p>Instead of the normal output of <output>"page: license"</output>,
print a list of licenses along with the number of pages that have
each license. All of the options above can still be used to filter
the pages that are used to calculate the totals.</p>
</item>
</terms>
</section>
<section id="media">
<title><cmd>yelp-check media</cmd></title>
<p>Check for references to external media files that do not exist. For
Mallard, <code>media</code>, <code>ui:thumb</code>, <code>uix:thumb</code>,
and <code>e:mouseover</code> elements are used. For DocBook, <code>audiodata</code>,
<code>imagedata</code>, and <code>videodata</code> elements are used.</p>
</section>
<section id="links">
<title><cmd>yelp-check links</cmd></title>
<p>Check the target of all internal links. For Mallard, all <code>xref</code>
attributes are used. For DocBook, all <code>linkend</code> attributes
are used. If the value does not correspond to an actual ID in the
document, <cmd>yelp-check links</cmd> prints the source and target
of the link.</p>
<p>For Mallard documents, you can pass <cmd>yelp-check links</cmd> a
list of page files, or you can pass it a directory to process all
page files in that directory. If you pass only a set of pages,
<code>yelp-check links</code> will only know about those pages,
and will report links as broken if they point to pages you did
not pass. However, you can create a cache file with
<cmd>yelp-build cache</cmd> that contains all the pages in the
document and pass this to <cmd>yelp-check</cmd> links with the
<cmd>-c</cmd> option.</p>
<p>Mallard allows links to provide both an <code>xref</code> and
an <code>href</code> attribute, and defines implementations to use
the <code>href</code> when the <code>xref</code> is not understood.
Use the <cmd>-i</cmd> option to ignore unknown <code>xref</code>
attributes when an <code>href</code> attribute is also present.</p>
<p>For DocBook, you can pass any DocBook file, including any
well-formed files that are included in a top-level file. However,
if you only check a file that is meant to be included in another
file, links will be reported as broken if they point to targets
outside that file or the files it includes.</p>
</section>
<section id="orphans">
<title><cmd>yelp-check orphans</cmd></title>
<p>Check for Mallard pages that cannot be reached by topic links.
You may still be able to reach the page by other links, but they
do not appear in the primary topic navigation of the document.</p>
<p>You can pass <cmd>yelp-check orphans</cmd> a list of page files,
or you can pass it a directory to process all page files in that
directory. If you pass only a set of pages, <cmd>yelp-check
orphans</cmd> will only know about those pages, and will probably
report many false positives. However, you can create a cache file
with <cmd>yelp-build cache</cmd> that contains all the pages in
the document and pass this to <cmd>yelp-check orphans</cmd> with
the <cmd>-c</cmd> option.</p>
</section>
<section id="status">
<title><cmd>yelp-check status</cmd></title>
<p>Report the status of Mallard page files, taken from the status
attribute of the revision elements for each page. You can pass a
list of page files, or pass a directory to process all page files
in that directory.</p>
<p>A page may have more than one revision element. When this happens,
<cmd>yelp-check status</cmd> filters the elements based on the
<code>version</code>, <code>docversion</code>, <code>pkgversion</code>,
and <code>date</code> attributes, depending on the arguments below.
It then sorts the <code>revision</code> elements primarily descending
by the <code>date</code> attribute, then by document order, and uses
the <code>status</code> attribute from the first. If the selected
<code>revision</code> element has no <code>status</code> attribute,
or if there are no matching revision elements, the status is
<code>"none"</code>.</p>
<terms>
<item>
<title><cmd>--version <var>VERSIONS</var></cmd></title>
<title><cmd>--docversion <var>VERSIONS</var></cmd></title>
<title><cmd>--pkgversion <var>VERSIONS</var></cmd></title>
<p>Only consider revision elements with a matching
<code>version</code>, <code>docversion</code>, or <code>pkgversion</code>
attribute, respectively. These options can be combined, and they
must all match. In all cases, <var>VERSIONS</var> can be a list
of versions separated by spaces or commas. The option matches if
any version matches the corresponding attribute.</p>
</item>
<item>
<title><cmd>--older <var>DATE</var></cmd></title>
<title><cmd>--newer <var>DATE</var></cmd></title>
<p>Only consider revision elements with a <code>date</code>
attribute that comes before (<cmd>--older</cmd>) or after
(<cmd>--newer</cmd>) the specified date. Dates are expected
to be in the form <sys>YYYY-MM-DD</sys>. These options may be
combined to specify a range the revision dates must fall in.</p>
</item>
</terms>
<p>There are also options that change what is output.</p>
<terms>
<item>
<title><cmd>--only <var>STATUSES</var></cmd></title>
<title><cmd>--except <var>STATUSES</var></cmd></title>
<p>After the status is determined as above, only print those
pages whose status matches (<cmd>--only</cmd>) or does not
match (<cmd>--except</cmd>) the specified statuses. In both
cases, <var>STATUSES</var> can be a list of statuses separated
by spaces or commas.</p>
</item>
<item>
<title><cmd>--totals</cmd></title>
<p>Instead of the normal output of <output>"page: status"</output>,
print a list of statuses along with the number of pages that
have each status. All of the options above can still be used
to filter the revision elements and to limit which statuses
the report on.</p>
</item>
</terms>
</section>
<section id="validate">
<title><cmd>yelp-check validate</cmd></title>
<p>Validate files against a DTD or RNG schema.</p>
<p>For Mallard documents, <cmd>yelp-check validate</cmd> implements
<link href="http://projectmallard.org/1.0/mal_attr_version">automatic
schema merging</link> based on the <code>version</code> attribute. If
there is no <code>version</code> attribute on a page, it is assumed
to be <code>"1.0"</code>, and the base Mallard 1.0 schema is used.</p>
<p>The Mallard schema allows elements and attributes from unknown
namespaces in many places, where the list of known namespaces is
built from the merged schemas. You can pass the <cmd>--strict</cmd>
option to disallow elements and attributes from unknown namespaces.
This is useful if you want to prevent unknown extensions.</p>
<terms>
<item>
<title><cmd>--strict</cmd></title>
<p>Disallow elements and attributes from namespaces that aren't
explicitly defined by the schemas imported based on the
<code>version</code> attribute.</p>
</item>
<item>
<title><cmd>--allow <var>NAMESPACE</var></cmd></title>
<p>When using strict validation, explicitly allow elements and
attributes from the namespace <var>NAMESPACE</var> in places
where any external-namespace nodes would normally be allowed.
You can pass the <cmd>--allow</cmd> option multiple times to
provide multiple namespaces that should be allowed.</p>
</item>
</terms>
<p>For DocBook 4, <cmd>yelp-check validate</cmd> uses the DTD set
by the <sys>DOCTYPE</sys>. If a document appears to be DocBook 4
but does not contain a DOCTYPE, the 4.5 DTD is used.</p>
<p>For DocBook 5, <cmd>yelp-check validate</cmd> selects an RNG
schema based on the <code>version</code> attribute.</p>
</section>
</page>
<page xmlns="http://projectmallard.org/1.0/"
id="yelp-new">
<info>
<link type="guide" xref="index"/>
<desc>Easily create new documents and pages from template files.</desc>
</info>
<title><cmd>yelp-new</cmd></title>
<p>Create a new file from a template. You can quickly create a new
page or other file from a template. This is useful when many of your
pages have a common layout or structure. You must pass at least two
arguments: the identifier of the template, and the ID of the file to
create. The second argument is used both for the base file name of
the new file and for the id attribute. You can optionally pass a page
title as the third argument.</p>
<p>Template files can be installed with <cmd>yelp-new</cmd> or they
can be kept locally in the same directory. Local templates are useful
if you have common page styles that are specific to your project. To
get a list of available templates, run <cmd>yelp-new --help</cmd>.</p>
<p>You can create your own template files. Just create a file with the
<file>.tmpl</file> extension appended. You can also use the <cmd>--tmpl</cmd>
option on yelp-new to copy an existing template to the current directory
without substituting, allowing you to build off of it for your own template.</p>
<p>Output files are created by substituting special markers in the template.</p>
<terms>
<item>
<title><code>@ID@</code></title>
<p>The ID value passed as the second argument to yelp-new, which is
the same as the base file name of the output file.</p>
</item>
<item>
<title><code>@DATE@</code></title>
<p>The current date in the format <sys>YYYY-MM-DD</sys>.</p>
</item>
<item>
<title><code>@YEAR@</code></title>
<p>The current year in the format <sys>YYYY</sys>.</p>
</item>
<item>
<title><code>@NAME@</code></title>
<p>The name of the person running the command. This value may come
from either <cmd>git</cmd> or <cmd>bzr</cmd>. Failing that, the
value <code>"YOUR NAME"</code> is used.</p>
</item>
<item>
<title><code>@EMAIL@</code></title>
<p>The email address of the person running the command. This value
may come from either <cmd>git</cmd> or <cmd>bzr</cmd>. Failing that,
the value <code>"YOUR EMAIL ADDRESS"</code> is used.</p>
</item>
<item>
<title><code>@TITLE@</code></title>
<p>The title as passed as the third argument to <code>yelp-new</code>.
If you do not pass a title, the value <code>"TITLE"</code> is used.</p>
</item>
</terms>
<p>You can also pass the <cmd>--stub</cmd> option to create a
<file>.page.stub</file> file instead of a regular <file>.page</file> file.</p>
</page>
<page xmlns="http://projectmallard.org/1.0/"
xmlns:e="http://projectmallard.org/experimental/"
id="yelp.m4">
<info>
<link type="guide" xref="index"/>
<desc>Automatically manage documentation in an autotools+make
build environment.</desc>
</info>
<title><file>yelp.m4</file></title>
<p>The <sys>yelp-tools</sys> package contains build utilities that help you build
and install your help files according to the
<link href="http://www.freedesktop.org/wiki/Specifications/help-spec/">freedesktop.org
help specification</link>. The freedesktop.org help specification was jointly
created by GNOME and KDE developers to create a single help system that all
desktop environments use. To date, Yelp is the only implementation.</p>
<p>The build utilities are contained in a single file, <file>yelp.m4</file>.
To use it, add the following to your <file>configure.ac</file> file:</p>
<code>YELP_HELP_INIT</code>
<p>You can also pass a space-separated list of options as the first argument
to <code>YELP_HELP_INIT</code>:</p>
<code>YELP_HELP_INIT([<var>options...</var>])</code>
<p>The following options are currently recognized:</p>
<terms>
<item>
<title><code>no-lc-media-links</code></title>
<p>Normally, the build utilies create symlinks for localized media
files when translators have not provided an actual localization.
This means that copies of media files always exist in each locale's
directory, even if there is no translation. Passing the
<code>no-lc-media-links</code> option suppresses these symlinks.</p>
<p>For normal images and videos, Yelp is able to look up files
according to a document search path, so the symlinks are actually
unnecessary. This has been true since at least Yelp 3.0. If you are
only installing images and videos that are embedded in pages, use
this option. If you use HELP_MEDIA for other types of files, such
as source code or other files that get linked to, only use this
option if you have verified that it works in production.</p>
<p><e:hi>Added in 3.12</e:hi></p>
</item>
<item>
<title><code>no-lc-dist</code></title>
<p>Normally, the build utilities dist the generated translated files,
including the localized copies of <code>HELP_FILES</code> output by
<cmd>itstool</cmd> and the stamp file used for tracking when the
localized files were built. Using the <code>no-lc-dist</code> option
makes these generated files not be included in the tarball. This
reduces the size of the tarball, but increases the time it takes
to build from the tarball.</p>
<note>
<p>Note that currently, help.gnome.org does not use any sort of
build system, and only uses files found in tarballs. If you use
<code>no-lc-dist</code>, translations of your documents will not
show up correctly on help.gnome.org or any other site that uses
the same code.</p>
</note>
<p><e:hi>Added in 3.12</e:hi></p>
</item>
</terms>
<p>By default, the help directory is <file><var>$PREFIX</var>/help</file>,
and each language is installed to
<file><var>$PREFIX</var>/help/<var>$LANG</var>/<var>$HELP_ID</var>/</file>.
The build utilities automatically provide a configure option
<cmd>--with-help-dir</cmd>, allowing users to override the help directory.</p>
<p>The build utilities expect a layout that looks something like this:</p>
<tree>
<item>
<file>help/</file>
<item><file>Makefile.am</file></item>
<item>
<file>C/</file>
<item><var>help files...</var></item>
<item>
<file>media/</file>
<item><var>help media files...</var></item>
</item>
</item>
<item>
<file>ll/</file>
<item><file>ll.po</file></item>
<item>
<file>media/</file>
<item><var>help media files for ll...</var></item>
</item>
</item>
</item>
</tree>
<p>There is a single <file>Makefile.am</file> file in the help directory
that manages all translations. The help directory can have any name, or
be arbitrarily deep. For projects with a single help document, it's common
to simply use a top-level help directory.</p>
<p>The source files are expected to be in a directory called <file>C</file>.
It's common to put images, videos, and other non-XML files in a subdirectory
called <file>media</file> or <file>figures</file>. The actual name of the
subdirectory doesn't matter, but examples on this page will use <file>media</file>.</p>
<p>Each translation has its own directory named according to the locale.
That directory contains a PO file also named according to the locale.
The name of the directory must match the base name of the PO file. For
media files (those not translated using the PO files), translators add
localized files using the same names and directory layout as the source
files. If a media file does not need to be localized, you do not need to
copy it. The build utilities take care of this automatically.</p>
<p>The Makefile.am file must start with the following line:</p>
<code>@YELP_HELP_RULES@</code>
<p>You can set the following variables:</p>
<terms>
<item>
<title><code>HELP_ID</code></title>
<p>The ID of the help document. This determines the install location,
and will be referenced in the <sys>help:</sys> URIs used in your
application. This variable is required.</p>
</item>
<item>
<title><code>HELP_POT</code></title>
<p>A file name for a POT file to create when running <cmd>make pot</cmd>.
This variable is optional. It defaults to <file><var>${HELP_ID}</var>.pot</file>.
Note that <cmd>make pot</cmd> is not run as part of <cmd>make</cmd>. This
is useful for Mallard page sets that are designed to merge into another
document with the same <code>HELP_ID</code>. If <cmd>make pot</cmd> is
used to generate a POT file for an external translation tool, that tool
may expect POT file names to be globally unique.</p>
</item>
<item>
<title><code>HELP_FILES</code></title>