Yelp tools

yelp‑tools is a software package of tools which can be used to build the Mallard document and run validity checks. Even though it is named yelp‑tools, this package is not dependent on Yelp, the viewer.

All the commands which are a part of yelp‑tools can take either a single file, a list of files or a directory as an argument.

yelp‑build

yelp‑build is a tool which transforms Mallard pages into other formats. Currently supported formats are:

• HTML
• XHTML
• ePUB

The generated output can be used in your project or distributed in some other way. For example, the HTML output can be hosted as a static website.

yelp‑build html and yelp‑build xhtml

yelp‑build can output Mallard documents to HTML or XHTML. The filenames for the exported files are taken from the page IDs of the corresponding Mallard files regardless of the actual names of the Mallard files. For the following examples, yelp‑build html will be used. yelp‑build xhtml works in exactly the same way.

You can pass yelp‑build html a list of page files or a directory that contains all the page files.

$ yelp-build html index.page foo.page bar.page
$ yelp-build html .

The generated output will be self contained, meaning that only the pages that you pass to yelp‑build will be included and linked to. If you want to include links to pages which you are not building, you need to generate a cache which includes them and pass it to yelp‑build.

By default, the exported HTML files are stored in the current working directory, but you can also use the ‑o option to specify an output directory of your choice. The ‑o argument also exports any image and video files enclosed within media elements in the help pages.

$ mkdir html_out
$ yelp-build html -o html_out .

yelp-build epub

yelp‑build can output Mallard documents to the Electronic Publication (ePUB) format. The output file is named index.epub by default but you can use the ‑o option and specify a different output filename.

$ yelp-build epub help/ -o book.epub

yelp‑build cache

A cache file of the whole document or some of the help pages can be used by other tools. For example, if you want to generate HTML only for a guide page, but you want it to show the links to all the topics which are on it, you will need to create a cache of the topics and pass it to yelp‑build when you generate the HTML.

A cache file is necessary to build other formats from Mallard documents. Cache files are generated automatically when you build Mallard documents in other formats, but yelp‑build can also explicitly generate cache files.

$ yelp-build cache *.page

yelp-check

yelp‑check is a tool that helps validate Mallard documentation. It can find broken external and internal links, files that have unmatched page IDs and filenames, orphaned pages and it can validate the XML in the pages against a Relax‑NG schema. It can also display any editorial comments the revision status status of a page.

All of the yelp‑check tools can take individual pages or a directory of pages as an argument.

yelp‑check comments

The <comment> element in Mallard allows you to embed editorial notes in the XML. Mallard comments are printed with the page name and section ID that contains them, the author of the comment and the date on which the comment was made, which are taken from the <cite> element.

yelp‑check links and yelp‑check hrefs

yelp‑check links verifies that all internal (xref) links are valid. If the value does not correspond to an actual ID in the document, yelp‑check links prints the source and target of the link. If you pass only a set of pages, yelp‑check links will only know about those pages, and will report links as broken if they point to pages which you are not validating. You can also supply a Mallard cache file that contains all the pages in the document and pass this to yelp‑check orphans with the ‑c argument when validating individual pages.

yelp‑check hrefs checks for the validity of external links. You will need to be connected to the internet for external links to be verified.

yelp‑check ids

yelp‑check ids is useful to check if the Mallard file names match their corresponding page IDs. It is not mandatory for these to match, but it's generally considered a best practice.

yelp‑check orphans

Topic pages should be accessible from other Mallard pages. yelp‑check orphans finds pages which are not linked to from other help pages.

As with other yelp‑check tools, if you pass only a set of pages, it will only know about those pages, and will probably report many false positives. You can also supply a Mallard cache file that contains all the pages in the document and pass this to yelp‑check orphans with the ‑c argument when validating individual pages.

yelp‑check status

yelp‑check status outputs the current progress status of different Mallard page files, taken from the status attribute of the <revision> element.

When a page has more than one <revision> element, the one with the latest date attribute is chosen. If the latest revision element has no status attribute, or if there is no revision element, the status is "none".

yelp-new

You can generate Mallard pages with basic structure using yelp‑new. To generates pages from default templates you need to specify the type of page and the page ID. You can also generate Mallard pages by supplying your own custom templates. This is useful when many of your pages have a common layout. Template files can be installed with yelp‑new or you can keep them in your working directory. To create your own template, create your .page template, then append .tmpl to the filename.