XslTNG: Generating & Customizing List Of Figures In Articles

Are you struggling to generate a list of figures in your DocBook articles using xslTNG? Do you need to customize the location of this list within your document? You're not alone! This article explores the challenges of creating lists of figures in DocBook articles using xslTNG and provides a comprehensive guide to achieving your desired results. We'll delve into the limitations of the default xslTNG behavior, discuss the need for customization, and offer solutions for generating and positioning your list of figures effectively. By the end of this article, you'll have a clear understanding of how to implement this functionality and enhance the structure of your DocBook articles.

The Challenge: List of Figures in DocBook Articles

The core issue lies in the default behavior of xslTNG. As the documentation suggests, even with the $lists-of-figures parameter set to true (which is the default), a list of figures is not automatically generated for DocBook documents that use <article> as the root element. This is in contrast to <book> and <set> documents, where lists of figures are readily created. This inconsistency presents a significant challenge for authors who prefer the <article> document structure for their work. Understanding this limitation is the first step in finding a solution. We need to explore why this discrepancy exists and how we can overcome it to achieve the desired output for our articles.

Why Articles Are Different

The reason behind this difference likely stems from the intended use cases of each DocBook root element. <book> and <set> are designed for larger, more complex documents, where a comprehensive list of figures is often considered essential for navigation and reference. <article>, on the other hand, is typically used for shorter, self-contained pieces, where the need for a dedicated list of figures might be perceived as less critical. However, this assumption doesn't hold true in all cases. Many articles, particularly those of significant length or technical complexity, benefit greatly from having a well-organized list of figures. This allows readers to quickly locate specific visuals and understand the overall structure of the document more effectively. Therefore, the ability to generate a list of figures for articles is a crucial feature for many DocBook authors.

The Desire for Customization

Furthermore, the requirement goes beyond simply generating a list of figures. Many authors have specific preferences regarding the location of this list within their document. The default behavior in xslTNG for <book> and <set> documents might not align with these preferences. In the scenario described, the author wants the list of figures to appear after all <section> elements but before the <bibliography> element. This level of control over the document structure is essential for maintaining consistency and adhering to specific publishing guidelines. The ability to customize the location of the list of figures is not just a matter of aesthetics; it's a critical aspect of professional document creation.

The Problem with Standard Solutions

The immediate solution that comes to mind is to customize the xslTNG transformation process. This involves hooking into the m:lists-of-figures mode and implementing the desired functionality directly. While this approach works, it introduces a significant portability issue. The customized XSLT stylesheet becomes an integral part of the document, meaning it must be distributed along with the XML file. This defeats one of the key advantages of DocBook: the ability to transform a single XML source into various output formats using standard tools. The author's concern about portability is valid. Requiring a custom xslTNG setup for a specific document reduces its accessibility and increases the complexity of the publishing workflow. A more standardized and flexible solution is needed.

The Portability Dilemma

Portability is a cornerstone of DocBook's design. The idea is that a DocBook XML document should be transformable into various formats (HTML, PDF, etc.) using standard XSLT stylesheets. This allows authors to focus on content creation without being tied to a specific output format or toolchain. By introducing a custom XSLT stylesheet, we break this portability. Anyone wanting to transform the document would need to have the specific customization installed, making the process less straightforward and potentially limiting the document's reach. The goal is to find a solution that integrates seamlessly with existing xslTNG installations and doesn't require additional configuration or dependencies.

The Ideal Solution: Built-in Flexibility

The ideal solution would be one that offers built-in flexibility within xslTNG itself. This would mean that the ability to generate a list of figures for <article> documents is included as a standard feature, controlled by a parameter or option. Furthermore, the location of the list of figures should be configurable, allowing authors to specify where it appears in the output document. This approach would maintain portability and simplify the publishing process. The request for these features stems from a desire to leverage the full power of DocBook and xslTNG without sacrificing flexibility or standardization.

A Feature Request: Enhancing xslTNG for Articles

Based on these challenges and limitations, the request for enhancements to xslTNG is entirely reasonable. Specifically, the author proposes two key improvements:

1. List of Figures for Articles

The first and most crucial request is to make lists of figures available for <article> documents in a natural way, just as they are for <book> and <set> documents. This means that setting the $lists-of-figures parameter to true should automatically generate a list of figures for articles as well. This would eliminate the need for custom XSLT stylesheets and ensure consistent behavior across different DocBook document types. Implementing this feature would significantly improve the usability of xslTNG for authors working with articles, especially those dealing with technical or visually rich content.

Making this change would align xslTNG's behavior with the expectations of many DocBook users. It would also simplify the process of creating professional-looking articles with a clear and organized structure. The inclusion of a list of figures enhances the reader's experience by providing a quick overview of the visuals and their context within the document. This is particularly important for articles that are intended for reference or in-depth study.

2. Configurable Location of the List of Figures

The second request is to make the location of the list of figures configurable in the output document. This would allow authors to specify exactly where the list should appear, providing greater control over the final layout and presentation. The current implementation might place the list in a location that doesn't suit every author's needs or publishing requirements. Providing a configuration option would address this limitation and make xslTNG more adaptable to diverse document structures and stylistic preferences.

This configurability could be achieved through a new parameter or option that allows authors to specify an insertion point for the list of figures. This could be based on element names (e.g., after <section>, before <bibliography>) or other criteria. The key is to provide a flexible mechanism that allows authors to position the list of figures according to their specific requirements. This would greatly enhance the overall flexibility and usability of xslTNG.

Potential Solutions and Workarounds

While waiting for these features to be implemented in xslTNG, there are some potential workarounds that authors can use. These solutions might involve custom XSLT stylesheets or adjustments to the document structure. However, it's important to remember that these are temporary measures and the ideal solution remains the integration of these features directly into xslTNG.

Custom XSLT Stylesheet

The most direct workaround is to create a custom XSLT stylesheet that handles the generation and placement of the list of figures. This involves hooking into the m:lists-of-figures mode and implementing the desired logic. While this provides full control over the process, it comes with the portability limitations discussed earlier. However, if portability is not a primary concern, this can be a viable option.

When creating a custom stylesheet, it's important to carefully consider the specific requirements for the list of figures. This includes the formatting, the level of detail (e.g., including captions or descriptions), and the placement within the document. The stylesheet should be designed to be robust and handle different types of figures and document structures. It's also crucial to thoroughly test the stylesheet to ensure that it produces the desired output in all cases.

Document Structure Adjustments

Another workaround is to adjust the document structure to mimic a <book> or <set> document. This might involve wrapping the <article> content within a <book> element temporarily during the transformation process. This would trigger the default list of figures generation in xslTNG. However, this approach can be cumbersome and might require significant changes to the document structure. It's also not a particularly elegant solution, as it involves bending the document structure to fit the tool rather than the other way around.

If this approach is used, it's important to ensure that the changes to the document structure are reversible. This might involve using XSLT to wrap and unwrap the content as part of the transformation process. However, this adds complexity to the transformation and can make it more difficult to maintain. Overall, this workaround is best avoided if possible.

Conclusion: The Need for Enhanced Flexibility

In conclusion, the ability to generate and customize the location of a list of figures in DocBook articles using xslTNG is a crucial feature for many authors. The current limitations of xslTNG in this area necessitate workarounds that compromise portability and flexibility. The feature requests outlined in this article – to make lists of figures available for articles and to allow configurable placement – are reasonable and would significantly enhance the usability of xslTNG. By addressing these issues, xslTNG can become an even more powerful and versatile tool for DocBook authors. We hope that the xslTNG development team will consider these requests and incorporate them into future releases.

For more information on DocBook and XSLT, consider exploring resources like OASIS DocBook.