GNOME.org
 

[yelp-tools] help/C: Adding some docs in Mallard

commit 3c0f83d87b215b1262f78a7d30f152f9774d0b08
Author: Shaun McCance <shaunm gnome org>
Date:   Wed May 27 20:05:08 2015 -0400

    help/C: Adding some docs in Mallard

 help/C/index.page      |   14 ++
 help/C/yelp-build.page |  186 +++++++++++++++++++++++++
 help/C/yelp-check.page |  356 ++++++++++++++++++++++++++++++++++++++++++++++++
 help/C/yelp-new.page   |   71 ++++++++++
 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>
+
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]