docbook-samples project

About

This is a simple project with just sample technical documentation files created and maintained by the author.

The aim is to provide real life technical documentation samples for other author's projects:

• foponts - configuration file for Apache FOP to produce PDFs with a predictable layout result { why it is important ) using OFL-licensed fonts. Highly recommended if source documents are in Docbook/XML format, written in Russian language or include any of Cyrillic characters within. Though, usage is not limited to the Russian language - it can be used for documents written in any language that used fonts support;
• docbook pretty playout - DocBook XSL customization layer above the stock ones to produce nice pretty print-related output (mostly PDFs) for any technical documentation authored in DocBook/XML 5.1 format;

NOTE: docbook pretty playout - is a long-running project, so for now only basic customization over the stock Docbook XSL stylesheets has been made.

The structure of this project

The project consists of a source .xml files (one or many) and other supporting files (images, image sources, etc.).

The overall structure of the project:

docbook-samples
  |
  /<software_name> - the name of a component or software the included documentation is related to.
  |  |
  |  |- readme.txt - readme file with a information about documentation within current directory. May include any specific or last-minute information concerning the current project.
  |  |- *.xml - source .xml files in DocBook/XML 5.1 format.
  |  |- *.fo - .fo files, generated by using docbook-pretty-playout project.
  |  |
  |  /img - directory with image files.
  |  |  |
  |  |  |- *.svg, *.png, ... - image files used within documents to illustrate software features, design, etc.
  |  |
  |  /img-src - directory with sources of image files (see above).
  |     |
  |     |- *.dia, ... - source files for image files above (i.e. diagram sources, etc)

Due to Github is designed for and targeted mostly to source files storage rather than a binary ones, all latter ones are stored separately within the author's website. If any of these files (i.e. generated PDFs) exist for the current software/component documentation set, a download links are provided within a related readme.txt file.

The project is used as a git submodule for foponts and docbook pretty playout projects.

FAQ

See FAQ.

Roadmap

Any enhancement of this project will be dictated solely by needs of other projects (i.e. including new DocBook element to create some new formatting customization layer to an output PDFs) or any other hidden author's thoughts :)

Contributing

In general this project was created solely by the author and for an author's goals. But, anyway, we are on Github now, so if you found a bug or have any amazing RFE - just create an issue.

Authors

• Eduard Tibet eduardtibet - initial work.

License

This project is distributed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License - see the LICENSE for more details.