docbook_files

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

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:

screenshot

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:

screenshot

The types mentioned mean:

inc

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

```xml

My book ... ``` Inclusion means here that the file mentioned is included into the main file during XML processing. See the the [DocBook documentation](http://docbook.org/tdg5/en/html/ch02.html#ch02-physdiv) 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: * [imagedata](http://docbook.org/tdg5/en/html/imagedata.html) for image files * [audiodata](http://docbook.org/tdg5/en/html/audiodata.html) for audio files * [videodata](http://docbook.org/tdg5/en/html/videodata.html) for video files Example: ```xml ``` 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 * [Download](https://rubygems.org/gems/docbook_files) it directly from rubygems * Add an idea or problem to the [issue tracker](https://github.com/rvolz/docbook_files/issues) * Check the [source code](https://github.com/rvolz/docbook_files) * Follow the development at [textmulch.de](http://textmulch.de) (in German)