diff options
author | Shaun McCance <shaunm@gnome.org> | 2015-05-27 20:05:08 -0400 |
---|---|---|
committer | Shaun McCance <shaunm@gnome.org> | 2015-05-27 20:05:08 -0400 |
commit | 3c0f83d87b215b1262f78a7d30f152f9774d0b08 (patch) | |
tree | 472ded9ab11ff0754a41d1dcbc5cdc68878bf593 | |
parent | a572f35ba8b3143b9b67b251721634c3fedd9c1f (diff) | |
download | yelp-tools-3c0f83d87b215b1262f78a7d30f152f9774d0b08.tar.gz |
help/C: Adding some docs in Mallard
-rw-r--r-- | help/C/index.page | 14 | ||||
-rw-r--r-- | help/C/yelp-build.page | 186 | ||||
-rw-r--r-- | help/C/yelp-check.page | 356 | ||||
-rw-r--r-- | help/C/yelp-new.page | 71 | ||||
-rw-r--r-- | help/C/yelp.m4.page | 232 |
5 files changed, 859 insertions, 0 deletions
diff --git a/help/C/index.page b/help/C/index.page new file mode 100644 index 0000000..5f8c4f4 --- /dev/null +++ b/help/C/index.page @@ -0,0 +1,14 @@ +<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> diff --git a/help/C/yelp-build.page b/help/C/yelp-build.page new file mode 100644 index 0000000..32c6d9d --- /dev/null +++ b/help/C/yelp-build.page @@ -0,0 +1,186 @@ +<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> diff --git a/help/C/yelp-check.page b/help/C/yelp-check.page new file mode 100644 index 0000000..5b3d7d2 --- /dev/null +++ b/help/C/yelp-check.page @@ -0,0 +1,356 @@ +<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> diff --git a/help/C/yelp-new.page b/help/C/yelp-new.page new file mode 100644 index 0000000..27405ba --- /dev/null +++ b/help/C/yelp-new.page @@ -0,0 +1,71 @@ +<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> diff --git a/help/C/yelp.m4.page b/help/C/yelp.m4.page new file mode 100644 index 0000000..181ed5f --- /dev/null +++ b/help/C/yelp.m4.page @@ -0,0 +1,232 @@ +<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> + <p>A space-separated list of the primary XML files. These files will be + translated using the PO files and localized versions will be output when + running <cmd>make</cmd>. This variable is appropriate for Mallard page + files, top-level DocBook files, and any XML files that are included with + XInclude. All files listed in <code>HELP_FILES</code> must be well-formed + XML. List all files relative to the C directory.</p> + + <note> + <p>Because of the way <file>yelp.m4</file> calls <cmd>itstool</cmd>, + currently files in HELP_FILES must be directly in the <file>C</file> + directory, not a subdirectory. If you use a subdirectory, the directory + structure will not be reproduced in translations. See + <link href="https://bugzilla.gnome.org/show_bug.cgi?id=690561">bug 690561</link>.</p> + </note> + </item> + + <item> + <title><code>HELP_EXTRA</code></title> + + <p>A space-separated list of files that are disted and installed for + <file>C</file>, but are not in any way localized. This variable is + appropriate for XML files that are included with <code>SYSTEM</code> + entities and text files included with XInclude. These types of files + are merged by default by <cmd>itstool</cmd> when creating PO files, + so they are redundant in localizations. List all files relative to + the <file>C</file> directory.</p> + </item> + + <item> + <title><code>HELP_MEDIA</code></title> + <p>A space-separated list of files that are disted and installed for + <file>C</file>, and which translators may create localized copies of. + If translators do not create localized copies, the build utilities + automatically create symlinks to the <file>C</file> files on <cmd>make + install</cmd>, unless you pass the <code>no-lc-media-links</code> + option to <code>YELP_HELP_INIT</code>. This variable is appropriate + for images, videos, and any external files that are linked to within + the help. List all files relative to the <file>C</file> directory.</p> + </item> + + <item> + <title><code>HELP_LINGUAS</code></title> + <p>A space-separated list of locales that are enabled. The build + utilities will only use translations listed in this variable.</p> + </item> +</terms> + +<p>The build utilities automatically handle <cmd>make</cmd>, <cmd>make +install</cmd>, <cmd>make uninstall</cmd>, and <cmd>make dist</cmd>. +Additionally, the following make targets are handled:</p> + +<terms> + <item> + <title><cmd>make check</cmd></title> + <p>When running the standard <cmd>make check</cmd> target, all + files in <code>HELP_FILES</code> are checked for well-formedness + using <cmd>xmllint</cmd>. Note that <cmd>make check</cmd> does + not automatically do validation against schemas.</p> + </item> + + <item> + <title><cmd>make pot</cmd></title> + <p>Create POT file using <cmd>itstool</cmd> from the files in + <code>HELP_FILES</code>. The name of the POT file can be specified + by the <code>HELP_POT</code> variable, and defaults to + <file><var>${HELP_ID}</var>.pot</file>. This is not called as part + of <cmd>make all</cmd>. However, some projects store the POT file + in version control, even though it's auto-generated, so that it + can easily be picked up by online translation tools. If you do + this, it's a good idea to make the all target depends on + <cmd>pot</cmd>.</p> + </item> + + <item> + <title><cmd>make repo</cmd></title> + <p>Updates all the languages' PO files using the latest sources. + This is not called as part of <cmd>make all</cmd>.</p> + </item> +</terms> + +</page> + |