tomschr / dbcookbook

Cookbook for DocBook and DocBook XSL stylesheets

Welcome to "The DoCookBook"

Info:	See https://github.com/tomschr/dbcookbook
Author:	Thomas Schraitle <tom_schr AT web DOT de>
Description:	Cookbook for DocBook and DocBook XSL stylesheets
HTML:	http://doccookbook.sourceforge.net

License

The book is licensed as Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany License (CC by-nc-sa 3.0 DE) See http://creativecommons.org/licenses/by-nc-sa/3.0/de/

Mission

The DoCookBook project aims to create an open source book about DocBook and the DocBook XSL stylesheets written in a cookbook-style manner and released under a Creative Commons license.

Concept

This book is written in a "cookbook" style. The book contains "topics" which are divided into a problem, the corresponding solution, some discussions, and optional related information. It is very easy just to go to the table of contents and see if there is something useful that fits to your problem. Solutions are usually written in a procedural style which contain several steps.

Target Group

It is assumed you have a decent knowledge about XML and DocBook. It doesn't hurt if you know CSS and XSLT. As such, it is aimed more at DocBook developers than writers.

Structure of the Book and Organization

The main file is "en/xml/DocBook-Cookbook.xml". It contains xi:include elements which refer to chapters, appendices and other second level elements.

# Structure of Book with Main Chapters
en/xml/DocBook-Cookbook.xml
|
+-- 5.1/        # (1)
|
+-- common/     # (2)
|
+-- db/         # (3)
|
+-- epub/       # (4)
|
+-- fo/         # (5)
|
+-- html/       # (6)
|
+-- structure/ # (7)

(1) Contains the DocBook Schema and possible customizations
(2) Contains topics to common customizations
(3) Contains topics to DocBook's markup
(4) Planned: will contain customizations to EPUB output format
(5) Contains topics to FO customizations
(6) Contains topics to HTML, XHTML, and other customizations based on HTML
(7) Contains topics how to manipulate DocBook's structure

Some topics contain directories which store XSLT, XML, or other example files. In some cases these are incorporated into the XML source, sometimes they are just lying around for testing purposes.

Each topic is a self-contained matter of a specific problem and its solution with discussion. Use the skeleton file "en/xml/topic.empty.xml" as a starting point. It contains the basic structure and you just need to add the flesh of your topic.

Contribute

Do you miss anything? Have you discovered an error? Have an idea about how to improve the book? Great! If you want to contribute to the book, you can do it in different ways:

• Write me a mail to <tom_schr (AT) web.de> and send me your comments
• Extend the tickets (Ideas for New Topics) at http://github/tomschr/dbcookbook/issues
• Clone this repository and send me patches

This repository uses git flow from https://github.com/petervanderdoes/gitflow-avh see Vincent Driessen Git branching model

How to build the book

Currently, building the book works but it's not as nice as I would like to see it.

• Building chunked HTML: use ./bin/dbsaxon
• Building single HTML: use bin/dbsaxon9

At the moment, it is a mixture of XSLT 1.0 and XSLT 2.0 stylesheets. To avoid maintaing two different CSS files (one for the XSLT 1.0 output, the other for 2.0), the HTML files coming from XSLT 1.0 are "cleaned up". This cleanup step makes the structure compatible to the XSLT 2.0 output.

How you can help

• Find typos, grammar problems, inconsistencies, or plain errors
• Send me patches
• Write your own topic

dbcookbook's Issues

Add topics about how to use and preserve entities

Is your feature request related to a problem? Please describe.
How to use and preserve entities are not described.

Describe the solution you'd like
Add topics about how to use and how to preserve entities

Additional context
Should be added to "Manipulating DocBook Document Structure" chapter.

Related to #8

Idea: Reusable content with XML Database (e.g. CouchDB, BaseX, eXist)

Idea

How to use database driven reusable content in a Docbook article/book?

Expected Behaviour

• Show how to use Xquery to add database content to an Docbook article or book
• Maybe how to store Docbook contents in an XML database

[HTML] Control the Chunking process

Is your feature request related to a problem? Please describe.
Describe the HTML parameters for chunking

Additional context
HTML, related to #10

Contribute

I would like to contribute to your cookbook as well as helping you to get it published. I have a relationship with Apress Books and I could have the manuscript submitted for publication. I am interested in anything I can contribute including existing and new content. I have a special interest in using open source tools to transform DocBook into content like pdf, html, and other open formats.

Currently I am finishing my second book with Apress and I will be available shortly to work on content for your book. I only ask to be considered a co-author should my contributions be considered good enough.

I look forward to hearing from you and providing new content for your book.

Thank you,
W. David Ashley
[email protected]
512.289.7506
Austin, Texas

Rename Book/Project Title

Problem

The project and book name is a bit cheasy.

Solution

Rename it to "DocBook Style Guide: Best Practices for Authors and Developers"

Checklist

• move project to the new domain
• adapt URLs in the document itself
• adapt URL(s) in/for Travis
• correct README
• something else...?

Create a GitHub Domain?

Problem

Maybe it's worth to think about creating a specific GitHub domain dedicated to this project.

Related to #19

Solution

With a domain, it could be easier to separate tools, result HTML, and source code.

• redirect pages from SourceForge to GitHub
• fix all old links
• separate build mechanics from source code

Updates DocBook XSL URL

Problem

You are using the URL "http://docbook.sourceforge.net/release/xsl-ns/current/fo/docbook.xsl" in various programlistings. For example in the "Print Customization" chapter: "http://doccookbook.sourceforge.net/html/en/dbc.fo.design-titlepages.html"

Expected Behaviour

As far as I know this is an old URL to version 1.78.x. From my opinion this should be "https://cdn.docbook.org/release/xsl/current/fo/docbook.xsl", which is 1.79.2 or newer.

Provide HTML, EPUB, and PDF Output

Moved from https://sourceforge.net/p/doccookbook/tickets/16/
Reported by Michael Wiedmann

---

Please create an EPUB version of the source files.
A first try using the ruby script dbtoepub (which is part of the DocBook-XSL distribution) without any customization already gives very promising output!

Make HTML and PDF also available as downloads.

Create Infrastructure for Comments

Problem

User would like to leave a comment for a specific page.

Possible Solutions

• Create infrastructure to enable users to insert comments for each paragraphs, similar to the Mercurial book (see http://hgbook.red-bean.com/)

• Another idea: Probably a link to the GH issue page should be enough.

• Use https://commento.io/

Add Index

Problem

The book needs a decent index, maybe created semi-automatically.

Solution

The book contains an index with the following properties:

• primary indexterm about (stylesheet) parameters
• primary indexterm about commands
• primary indexterm about options
• primary indexterm about DocBook elements

Ideas: Print Customizations

Moved from https://sourceforge.net/p/doccookbook/tickets/22/

---

These are some of the ideas about print customizations. The list is no guarantee that all will be implemented.

• Restarting page number on each chapter
• Designing Title Pages
• Designing Pages for Novels
• Designing Pages for Lexicons, Referene Book and Catalogs
• Designing Pages for Magazines and News Papers
• Designing Pages for Technical Books
• Adapting Chapter and Sections Titles
• Make Font Sizes Consistent / Standardizing Font Sizes (Le Corbusier)
• Index
• Designing TOCs
• Colorizing Table Rows
• Adding Graphics in Title Page
• Adding Logos in Header or Footer
• Adding Current Time and Date Information
• Separating Chapter Number from Title
• Footnotes
• Marginalia
• Endnotes
• Adorning Paragraphs with Initials (Openings)
• Formatting Titles
• Numbering Titles
• Choosing Open Source Fonts
• Adding Change Bars
• Initials/Drop Caps
• Influence Leading in Flow Text (=line-height in paras)
• Hyphenating in Verbatim Environments (long lines in screen, programlisting)
• Showing Cropmarks
  http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/examples/fo/advanced/bleed-and-crop-marks.fo?view=markup&pathrev=800143
• Barcode
• Add Typographical Superiors and Inferiors
• Adding Fonts to FO Formatter
• Creating Page Definitions with Inkscape
• Styling Labels Differently than Titles (Separating Labels and Titles)
• Using Text Figures http://en.wikipedia.org/wiki/Text_figures
• Using MathML in Formulas
• Influencing the TOC Bookmark Levels in PDF
• Finding the correct Font Name
• Hyphenating URLs

Ideas: (X)HTML Customizations

Moved from https://sourceforge.net/p/doccookbook/tickets/23/

---

These are some of the ideas about (X)HTML customizations. The list is no guarantee that all will be implemented.

• Attaching CSS (to your HTML) (explain different methods)
• Alt Text for Images
• Creating Callouts
• Syntax Highlighting
• Implementing Clickable TOCs
• Deciding where to put Customizations (CSS or XSLT)
• Integrating Google's Web Fonts
• Combining DocBook and Web Frameworks (Twitter Bootstrap, Bulma, Foundation, etc)
• Separating Label and Title in Headings
• Customize chunking process
• Document dbhtml PI
• Control chunking
• Adding Permalinks
• Creating Breadcrumbs (simple, sophisticated)

Create Issue Templates

Problem

We need an issue template.

Expected Behaviour

Whenever someone opens a new issue, the user should see a basic structure.

See Also

• https://help.github.com/articles/creating-an-issue-template-for-your-repository/

Ideas: Common Customizations

Moved from https://sourceforge.net/p/doccookbook/tickets/20/

---

These are some of the ideas about common customizations. The list is no guarantee that all will be implemented.

• Getting to Know Available DocBook XSL Stylesheets
• Getting an Overview -> maybe before any of the topics?
• Taking Advantage of Common Bibliography
• Taking Advantage of Common Glossary
• Colorising Profiled Text
  http://lists.oasis-open.org/archives/docbook-apps/201108/msg00100.html
• Creating Unit Test with XSpec
• Inserting Missing Glyphs in a Font
• Sharing text (entities)
• Extracting Information from Processing Instructions
• Getting Documentation Title
• Designing Title Pages
• Extending Language Files with your Own Text
• DocBook customization (through parameters or customization layers)
• Outputing Time and Dates
• Printing XPath from Stylesheet

Use Travis to create HTML archive

Problem

The "Release" link in GitHub misses a HTML (or PDF) file which is automatically created by Travis CI.

Expected Behaviour

After a new release, Travis builds the HTML (or PDF) and uploads it to the "Release" page.

See also

• https://docs.travis-ci.com/user/deployment/releases/

Use GitHub Actions to create GitHub Pages

Problem

Currently, all HTML pages are stored at SourceForge. It would be nice to have it all under one roof.

Expected Behaviour

• All HTML pages can be accessed from tomschr.github.io/dbcookbook.
• redirect pages from SourceForge to GitHub

See Also

• https://docs.travis-ci.com/user/deployment/pages/
• related issue #25

Implement Syntax Highlighting

Moved from https://sourceforge.net/p/doccookbook/tickets/29/

---

Implement syntax highlighting in online output for screen or programlisting.

Useful links:

• http://alexgorbatchev.com/SyntaxHighlighter/
• http://softwaremaniacs.org/soft/highlight/en/
• http://code.google.com/p/google-code-prettify/

Address problem of large horizontal scroll bar in html output

Moved from https://sourceforge.net/p/doccookbook/tickets/17/
Reported by David Cramer.

---

Certain programlistings contain very long lines:

http://doccookbook.sf.net/html/en/DoCookBook.html#dbc.structure.remove-blocks-in-para

As a result, the entire html page has a huge horizontal scroll bar. Perhaps put a box with a scroll bar (if necessary) around each programlisting?

Improve CSS for HTML

Is your feature request related to a problem? Please describe.

The current look of my HTML pages are a bit... boring. Furthermore, it should be readable on smartphones and desktop PCs.

• improve CSS
• take into account smartphones
• use grid(s) to describe the layout
• use alternative stylesheets?

Describe the solution you'd like

• https://gridbyexample.com/examples/
• https://developer.mozilla.org/en-US/docs/Web/CSS/Alternative_style_sheets

Typo

Chapter 1, section 1.2 Selecting the Right Top Level Element, Discussion section

There a many more possible root elements, not only book.

It looks like a grammar error.
I think that it should be written as "There are many more possible root elements, not only book.
"

Write a Colophon

Moved from https://sourceforge.net/p/doccookbook/tickets/26/

---

Write a colophon explaining how this book is/was produced; which tools, fonts, etc. are used

Add sitemap.xml

Is your feature request related to a problem? Please describe.
Missing sitemap.xml to improve Google SEO results.

Describe the solution you'd like
Add a sitemap.xml.

Additional context

• To split big sitemaps into smaller ones, use this URL: https://support.google.com/webmasters/answer/75712?visit_id=0-636655319635101674-843455639&rd=1

• Sitemap Schema: https://www.sitemaps.org/schemas/sitemap/0.9/

Adding Fonts to FO Formatter (Apache FOP)

Feature Description

A book should contain a topic concerning configuring and using fonts with FO-formatter. This topic will be Apache FOP related only.

Expected Wishlist

1. How to configuring fonts (in general).
2. What is autodetect and how it influence a look of the document.
3. How someone should deal with the ##### signs instead of characters while rendering PDF file from DocBook document containing non-Latin character.

Relations

Not know yet.

Ideas: Markup

Moved from https://sourceforge.net/p/doccookbook/tickets/19/

---

These are some of the ideas about markup. Most is probably already mentioned in "The Definitive Guide" so not all can/will be implemented.

• Knowing the Differences Between DocBook's Version 4 and Version 5

• Modularize your Document with Assemblies

• Differentiate DocBook Elements (Divisions, Block, Inline)

• Writing Topics with DocBook

• Using Tables

• Writing a Glossary

• Writing a Reference

• Writing Bibliographies

• Inserting Indexterms

• Adding Images

• Adding Codelistings

• Utilize Extended XLinks
  http://www.balisage.net/Proceedings/vol7/html/Vlist01/BalisageVol7-Vlist01.html

• Knowing DocBook Derivates: Simple DocBook, Publishers Schema

• Using Manpage Notation

  <citerefentry>
    <refentrytitle>foo</refentrytitle><manvolnum>1</manvolnum>
  </citerefentry>
  

• Knowing the Difference of Crossreferences and Links

• Using Lists

• Distinguish Between Section and SectX

• Implementing Cross References

• Inserting Remarks

• Choosing Between Two Link Methods

• Adding Multiple Indices

• Inserting Inline Quotes

• Modularize your Document with XIncludes

Tiny error in stylesheet

Reported from @sknorr via mail (found in http://doccookbook.sf.net/html/en/dbc.structure.move-blocks-in-para.html):

Example:

<para>
     This manual uses the following
     <!-- comment --><phrase>commands</phrase>:
     <screen>foo</screen>
</para>

Output is:

<para>
     This manual uses the following
</para>
<screen>foo</screen>

Patch:

diff --git i/en/xml/structure/remove-blocks-in-para/move-blocks-outof-para.xsl w/en/xml/structure/remove-blocks-in-para/move-blocks-outof-para.xsl
index 5f87f64..5ed971e 100644
--- i/en/xml/structure/remove-blocks-in-para/move-blocks-outof-para.xsl
+++ w/en/xml/structure/remove-blocks-in-para/move-blocks-outof-para.xsl
@@ -33,7 +33,7 @@
       select="following-sibling::*[&dbselfblocks;][1]"/>
   </xsl:template>
 
-  <xsl:template match="d:para/*|d:para/text()" mode="copy">
+  <xsl:template match="d:para/node()" mode="copy">

Investigate Assemblies

Problem

As a showcase, use assemblies in the future

Expected behaviour

• The main file is an assembly file
• The tool chain is adapted to produce the result from the assembly file

Ideas: Manipulating DocBook Document Structure

Moved from https://sourceforge.net/p/doccookbook/tickets/21/

---

These are some of the ideas about manipulating the DocBook document structure. The list is no guarantee that all will be implemented.

• (Combining two DocBook documents with XSLT)
• Modularizing DocBook Documents with Assemblies
• Creating a RevHistory from RSS and Atom
• Resolving XInclude Elements
• Autogenerate indexterm ranges
• Renaming Image Filenames
• Checking Style Guide Issues with XSLT
• Using other Placeholders (PIs, XIncludes, phrase...)
• Using Entities as Placeholders
• Preserving Entities #43

Ideas: Create Infrastructure Topic

Problem

Although DocBook does not enforce how you create your project, it could be helpful to give some information about the "things around DocBook".

Solution

Some ideas that could be integrated under this topic. The list is no guarantee that all will be implemented:

• Creating a Structure for your DocBook Projects
• Using the xmllint Shell to test XPath expressions
• Managing your XML Catalogs
• Managing your Workflow Tools
• Using XML Parsers
• Using a XSLT Processors
• Using an XProc Processor
• Choosing a XML Editor
• Configuring FOP

Related issue: #11

Old link from code.google.com

Problem

The code pretty printer from Google has changed its link:

Old link: http://code.google.com/p/google-code-prettify/
New link: https://github.com/google/code-prettify

http://doccookbook.sourceforge.net/html/en/dbc.html.sh.google-code-prettifiy.html

Reported by Peter Schmelzer

Expected Behaviour

Change link to new link.

Ideas: Investigate new Chapter about DocBook Toolchains

Moved from https://sourceforge.net/p/doccookbook/tickets/25/

---

It seems, there is an interested in a chapter about [a] DocBook toolchain(s). The chapter could explain what software/tools you need, how to install it, and how to use it.

Unfortunately, this is a (very?) broad topic. Requirements, operating systems, and steps differ a lot. As such, DocBook does not have an "official" toolchain.

Currently, it's not of high priority for me, although it would be probably very beneficial. If someone wants to take this over, please go ahead! :-)

Create a Chapter About EPUB Customizations

Moved from https://sourceforge.net/p/doccookbook/tickets/18/

---

There is a chapter missing about EPUB customizations

[HTML] Document dbhtml PI

Is your feature request related to a problem? Please describe.
Describe the <?dbhtml?> processing instruction for chunking.

Additional context
HTML, related to #10