docbook_file is a free utility that helps with checking larger DocBook writing or documentation projects. The larger DocBook projects tend to consist of multiple DocBook XML files (the parts, chapters …) and lots of accompanying files for media, code and examples.

It is hard to keep track where which file is included or referenced. Here docbook_files comes to help! It

  • lists and checks included files (XInclude)
  • lists and checks referenced files (media files and others, specified by fileref)
  • shows errors, e.g. not existing files
  • provides a detailed listing of all related files
  • is easy to integrate with other tools by using YAML or JSON output

Usage

docbook_files is a command line application, so just type: docbook_files myproject.xml, where myproject.xml is the main file of your DocBook project. The application will respond with an overview of the file hierarchy. To get additonal details for the files, add the —details option, like in docbook_files --details myproject.xml. That might result in an output screen like this one:

docbook_files: File hierarchy and details

docbook_files checks the main file for included (inc_) or referenced (_ref) files and lists them in a hierarchy. That way it is easy to see where which file comes into play. The type tells you how the file is used, followed by the file size.

If a file is mentioned but could not be found, it is marked, so that the error can be fixed easily:

docbook_files: problem files are marked

The types mentioned mean:

inc

The inc type means that the file was included. docbook_files supports inclusion via XInclude, like in this example:

 <book xmlns="http://docbook.org/ns/docbook"
       xmlns:xi="http://www.w3.org/2001/XInclude"
       version="5.0">
   <title>My book</title>
   ...
   <xi:include href="chapter2.xml"/>

Inclusion means here that the file mentioned is included into the main file during XML processing. See the the DocBook documentation for details.

ref

The ref type means that the file in question is only referenced in a fileref attribute. That attribute is typically part of DocBook elements dealing with external files. Examples are:

Example:

  ...
  <mediaobject> 
    <imageobject>
      <imagedata fileref="img/pic.png" format="PNG"/> 
    </imageobject>
  ...

Since modern publications tend to use a lot of media files, it is quite useful to check which files are used where, and if they are where they should be.

main

The main DocBook file of your documentation project.

The details

When used with the —details option, the application adds a file listing to the hierarchy. The hierarchy display follows the flow of inclusions and references, so a file can apperar there multiple times, wherever it is included or referenced. In the details listing there is only one entry per file used.

The details include (empty values might not be displayed):

  • file – file name
  • includes – files that are included by this file
  • included by – files that include this file
  • references – files that are referenced by this file
  • referenced by – files that reference this file
  • file size
  • DocBook version and start tag
  • MIME type
  • Last modified time
  • SHA1 checksum
  • Error message – if the file was not found or a processing error occured

The includes and references make it easy to see which impact the removal or change of a file in the DocBook project might have.

Integration

If you don’t like the screen output or want to integrate docbook_file into a certain workflow, just use the YAML or JSON output format instead. The option —outputformat lets you specify a different output format, for example:

docbook_files —outputformat=yaml myproject.xml

The result is printed to STDOUT. The structure returned is equivalent to the normal terminal output, except that you always get the details.

  • hierarchy – an array of entries for each step in the file hierarchy
    • type – file type (main, inc-luded, or ref-erenced)
    • name – file name
    • path – path relative to the main file
    • status – error status: 0 = ok, 1 = file not found, 2 = processing error (see error_string)
    • size – file size in bytes
    • level – the level in the file hierarchy, starting with 0
  • details – an array of entries for each file used in the hierarchy
    • name – file name
    • path – path relative to the main file
    • status – error status: 0 = ok, 1 = file not found, 2 = processing error (see error_string)
    • error_string – contains an error message, if status > 0
    • namespace – XML namespace, if applicable
    • version – XML version attribute, if applicable
    • docbook – true for DocBook 5 files, else false
    • tag – start tag for XML files (chapter, book, article …)
    • ts – file modification time
    • size – file size in byte
    • checksum – SHA1 checksum
    • mime – MIME type
    • includes – files that are included by this file, an array of file names
    • included_by – files that include this file, an array of file names
    • references – files that are referenced by this file, an array of file names
    • referenced_by – files that reference this file, an array of file names

Software

Installation

docbook_files is distributed as a Ruby Gem. To install it simply type

sudo gem install docbook_files

Requirements

  • libxml2
  • json (optional, install the gem if you want JSON output for Ruby 1.8)
  • win32console (optional, install the gem if you want color support on MS Windows)

Further actions