yelp-check
Command |
Mallard |
DocBook 4 |
DocBook 5 |
Yes |
Yes |
Yes |
|
Yes |
Yes |
Yes |
|
Yes |
No |
No |
|
Yes |
No |
No |
|
Yes |
Yes |
Yes |
|
Yes |
Yes |
Yes |
|
Yes |
No |
No |
|
Yes |
No |
No |
|
Yes |
Yes |
Yes |
yelp-check comments
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 --editor-mode option.) Mallard uses the comment element, and DocBook uses the remark element.
For Mallard documents, you can pass yelp-check comments 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.
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 yelp-check comments cannot format all block content in plain text. Any content that is not in a p element currently results in a FIXME statement.
DocBook comments are printed with the closest enclosing ID and the value of the revisionflag attribute.
yelp-check hrefs
Check the target of all external links in a Mallard or DocBook document. For Mallard documents, yelp-check hrefs uses all href attributes in the document. For DocBook documents, it uses the url attribute of all ulink elements as well as all xlink:href attributes in the document. In both cases, mailto: links are excluded.
For Mallard documents, you can pass yelp-check hrefs 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.
If a URL is relative, yelp-check hrefs checks for the file locally. If a URL is absolute, it uses curl to check the HTTP status of the resource.
yelp-check ids
Check if the id attributes of pages match the base file name (without the .page 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.
yelp-check license
Report the license of Mallard page files, taken from the license element. The license is reported based on the href 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 href attribute, it is listed as unknown.
Pages may have multiple license 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.
A page may have more than one revision element. When this happens, yelp-check status filters the elements based on the version, docversion, pkgversion, and date attributes, depending on the arguments below. It then sorts the revision elements primarily descending by the date attribute, then by document order, and uses status attribute from the first. If the selected revision element has no status attribute, or if there are no matching revision elements, the status is "none".
You can restrict which licenses are shown using the following attributes:
--only LICENSES
- Only show pages that have the license LICENSES, or one of the licenses in a space- or comma-separated list.
--except LICENSES
- Only show pages that do not have the license LICENSES, or one of the licenses in a space- or comma-separated list.
You can also get a summary of which licenses are in a document:
--totals
- Instead of the normal output of "page: license", 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.
yelp-check media
Check for references to external media files that do not exist. For Mallard, media, ui:thumb, uix:thumb, and e:mouseover elements are used. For DocBook, audiodata, imagedata, and videodata elements are used.
yelp-check links
Check the target of all internal links. For Mallard, all xref attributes are used. For DocBook, all linkend attributes are used. If the value does not correspond to an actual ID in the document, yelp-check links prints the source and target of the link.
For Mallard documents, you can pass yelp-check links 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, yelp-check links 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 yelp-build cache that contains all the pages in the document and pass this to yelp-check links with the -c option.
Mallard allows links to provide both an xref and an href attribute, and defines implementations to use the href when the xref is not understood. Use the -i option to ignore unknown xref attributes when an href attribute is also present.
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.
yelp-check orphans
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.
You can pass yelp-check orphans 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, yelp-check orphans will only know about those pages, and will probably report many false positives. However, you can create a cache file with yelp-build cache that contains all the pages in the document and pass this to yelp-check orphans with the -c option.
yelp-check status
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.
A page may have more than one revision element. When this happens, yelp-check status filters the elements based on the version, docversion, pkgversion, and date attributes, depending on the arguments below. It then sorts the revision elements primarily descending by the date attribute, then by document order, and uses status attribute from the first. If the selected revision element has no status attribute, or if there are no matching revision elements, the status is "none".
--version VERSIONS
--docversion VERSIONS
--pkgversion VERSIONSOnly consider revision elements with a matching version, docversion, or pkgversion attribute, respectively. These options can be combined, and they must all match. In all cases, VERSIONS can be a list of versions separated by spaces or commas. The option matches if any version matches the corresponding attribute.
--older DATE
--newer DATEOnly consider revision elements with a date attribute that comes before (--older) or after (--newer) the specified date. Dates are expected to be in the form YYYY-MM-DD. These options may be combined to specify a range the revision dates must fall in.
There are also options that change what is output.
--only STATUSES
--except STATUSESAfter the status is determined as above, only print those pages whose status matches (--only) or does not match (--except) the specified statuses. In both cases, STATUSES can be a list of statuses separated by spaces or commas.
--totals
Instead of the normal output of "page: status", 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.
yelp-check validate
Validate files against a DTD or RNG schema.
For Mallard documents, yelp-check validate implements automatic schema merging based on the version attribute. If there is no version attribute on a page, it is assumed to be "1.0", and the base Mallard 1.0 schema is used.
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 --strict option to disallow elements and attributes from unknown namespaces. This is useful if you want to prevent unknown extensions.
--strict
Disallow elements and attributes from namespaces that aren't explicitly defined by the schemas imported based on the version attribute.
--allow NAMESPACE
When using strict validation, explicitly allow elements and attributes from the namespace NAMESPACE in places where any external-namespace nodes would normally be allowed. You can pass the --allow option multiple times to provide multiple namespaces that should be allowed.
For DocBook 4, yelp-check validate uses the DTD set by the DOCTYPE. If a document appears to be DocBook 4 but does not contain a DOCTYPE, the 4.5 DTD is used.
For DocBook 5, yelp-check validate selects an RNG schema based on the version attribute.