opensuse / daps

DocBook Authoring and Publishing Suite (DAPS)

DocBook Authoring and Publishing Suite (DAPS)

A complete environment to build HTML, PDF, EPUB and other formats from DocBook XML. See https://github.com/openSUSE/daps for more information. Documentation is available from https://opensuse.github.io/daps/doc/index.html. DAPS is released under the GPL (version 2 or 3 at your choice).

1. Installing DAPS

DAPS packages are available for openSUSE and SUSE Linux Enterprise. It has also been successfully tested on Debian, Fedora, Linux Mint, and Ubuntu. See INSTALL.adoc for installation instructions.

The latest DAPS version.

2. Forum

Use the GitHub Discussions of this repository.

3. Reporting Bugs

To report bugs, use the bug tracker of this repository: https://github.com/openSUSE/daps/issues/new?template=bug.md.

4. Contributing

If you would like to contribute to the project, do the following:

1. Fork this project.

2. Clone the project:

   git clone [email protected]:YOUR_USERNAME/daps.git

3. Create a new branch from the main branch.

   git branch <BRANCH_NAME> main

4. Make your changes.

5. Send a pull request. Note that we will only accept pull requests against the main branch.

daps's Issues

Check EPUBs with epubcheck [sf#11]

Reported by tom_schr on 2011-12-16 12:31 UTC
Check our generated EPUB files with epubcheck (see http://code.google.com/p/epubcheck/)

SUSE branding: Hyphenation of URLs (Zero Width Space) [sf#33]

Reported by tom_schr on 2012-02-03 14:50 UTC
The parameter ulink.hyphenate is used to allow URLs to be hyphenated automatically. Usually it is set Zero Width Space (ZWS, U+200B). This ZWS is included in certain positions (like before '/' or '-') to mark a hyphenation possibility. The complete URL is set to hyphenate=false to avoid breaking it in the middle of a word.

However, it does not work for FOP as advertised. It is creates overly long spaces like this:

 | The quick brown fox jumps over the lazy dog. See /usr/share/doc/ |
 | packages/lazy-dog/README.                              for more  |
 | information.

For the time being, ulink.hyphenate is set to '' for FOP. Other formatters get their ZWS.
Marking this ticket as 'pending'. It "works", but it looks not nice. Maybe future versions of FOP can improve this situation.

See also https://bugzilla.novell.com/show_bug.cgi?id=706452

SUSE branding: Revamp stylesheets [sf#19]

Reported by tom_schr on 2011-12-16 13:01 UTC
The current stylesheets contain some code pieces which should be removed.

Rename DISTVER [sf#25]

Reported by fsundermeyer on 2012-01-19 13:38 UTC
Rename variable DISTVER to PRODUCTVERSION

stylesheets: trouble with xrefstyle="select:nopage" in HTML Output [sf#44]

Reported by taroth21 on 2012-02-17 10:15 UTC
xrefstyle="select:nopage" does not display correctly in HTML output:

code snippet:
Specify the resource template as you would specify a primitive. Follow , starting with .

HTML output:
Specify the resource template as you would specify a primitive.
Follow , starting with Step 4.b.
^^^^^^
missing contents: Procedure 6.4, Adding Primitive Resources”

daps: Do not check for an ENV file if not needed [sf#5]

Reported by tom_schr on 2011-12-16 12:05 UTC
Some targets such as clean do not need an ENVfile to be specified do not check for an ENVfile with these targets

Insert Documentation Header in XSLT Stylesheets [sf#31]

Reported by tom_schr on 2012-01-31 08:56 UTC
Each XSLT stylesheet needs a header to document its purpose.

:::XML
<!--
   Purpose:
     What does the stylesheet does?

   Parameters:
     What parameters are available and what values are allowed?

   Input:
     What XML source is expected?

   Output:
     What output format is created?

-->

daps init not working smoothly [sf#32]

Reported by taroth21 on 2012-02-02 15:15 UTC
With daps-0.9.2-12.1.noarch:

When running daps init, it gave me the following messages:

daps --basedir=/local/test init

sed: couldn't edit /local/test//: not a regular file
/usr/share/daps/lib/daps_functions: line 1082: setup_builddir: command not found

However, daps init nevertheless created the directory structure including an ENV file (ENV-file.template) and the MAIN file (MAIN-.xml). So far, so good.

But trying to build the example doc project failed in the first run, because ENV-file.template refers §§MAIN§§, not the MAIN file created with daps init (MAIN-.xml). Therefore generating output will fail unless the ENV is edited by the user.

daps: Support DocBook 5 in Admin Stylesheets [sf#28]

Reported by tom_schr on 2012-01-26 19:49 UTC
We have some stylesheets which extracts different information (like image paths, document structure, etc.). These "administrative" stylesheets currently supports DocBook 4 only.

These stylesheets has to be improved to also match for DocBook 5 elements.

SUSE branding: Image locations in FO stylesheets [sf#40]

Reported by fsundermeyer on 2012-02-08 15:08 UTC
The fo stylesheets (at least for flyer and maybe pocket) create links to the Novell/SUSE Logos. With the move to suse-xsl-stylesheet they no longer point to the correct locations.

##>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
XEP_CONFIG_FILE=/etc/daps/xep/xep-daps.xml /usr/share/daps/lib/daps-xep \
  -q /local_data/svns/suse/doc/branches/SLE_110/books/en/build/.tmp/book.sle.admin-xep_en.fo /local_data/svns/suse/doc/branches/SLE_110/books/en/build/SLES-admin/book.sle.admin_en.pdf 
##<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
[error] Failed to create image file:/usr/share/daps//xslt/images/svg/suse-logo.svg of type null
[error] java.io.FileNotFoundException: /usr/share/daps/xslt/images/svg/suse-logo.svg (No such file or directory)

Invent general URI for SUSE XSLT Stylesheets [sf#39]

Reported by tom_schr on 2012-02-08 13:18 UTC
The DocBook stylesheets have a general URI to reference their files. For example, the main stylesheet for a single XHTML output is http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl.

We need a similar URI for our stylesheets, in case developers wants to customize our stylesheets. We could follow the same structure for DocBook, slightly adapted:

   http://daps.sourceforge.net/release/xsl/current/xhtml/docbook.xsl

Or even better with a "suse" prefix:

   http://daps.sourceforge.net/release/suse-xsl/current/xhtml/docbook.xsl

We need the following things:

1. A file /etc/xml/for-catalog-suse-xsl-stylesheets-XXX.xml:

\<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"\>
  \<group id="suse-xsl-stylesheets"\>
  \<delegateSystem systemIdStartString="http://daps.sourceforge.net/release/suse-xsl/" catalog="file:///etc/xml/suse-xsl-stylesheets.xml"/\>
  \</group\>
\</catalog\>

1. A file /etc/xml/suse-xsl-stylesheets.xml.

\<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"\>
  \<rewriteSystem systemIdStartString="http://daps.sourceforge.net/release/suse-xsl/current" rewritePrefix="file:///usr/share/xml/docbook/stylesheet/suse/"/\>
\</catalog>

Documentation: Create flow chars [sf#17]

Reported by tom_schr on 2011-12-16 12:51 UTC
Create flow charts of Makefile mechanic [2011-04-06, fs] and include it into the documentation (see [ticket#1]).

docmanager: move xmlformat from daps to docmanager [sf#43]

Reported by fsundermeyer on 2012-02-14 09:03 UTC
xmlformat is not used by daps itself, but rather by daps-docmanager.

Make xmlformat a dependency of daps-docmanager, move bin/daps-xmlformat to docmanager/bin/daps-xmlformat and take care of packaging this new binary.

docmanager: Improve speed [sf#14]

Reported by tom_schr on 2011-12-16 12:47 UTC
improve speed by:

• reducing the svn calls to a minimum
• using Python svn bindings

daps: Create full or relative path [sf#6]

Reported by tom_schr on 2011-12-16 12:07 UTC
full or realtive path to ENV-file instead of --basedir

daps: Improver Performance of certain targets [sf#47]

Reported by fsundermeyer on 2012-02-20 08:57 UTC
Computing SETFILES, SRCFILES, DOCFILES and USED is the most time cosuming operation when sourcing the makefiles. However, It is not necessary to always set these variables - the *-name or the clean targets do not make use of them.

Setting them conditionally (and providing sane defaults) will speed up Makefile sourcing for these targets. lib/daps_functions could set something like NEED_ALL_FILES depending on the target.

Autgenerate $MAIN [sf#8]

Reported by tom_schr on 2011-12-16 12:16 UTC
Should $MAIN autogenerated?

Auto detect $MAIN [sf#9]

Reported by tom_schr on 2011-12-16 12:27 UTC
Should we autodetect $MAIN?

Typo in Error Message [sf#41]

Reported by taroth21 on 2012-02-09 15:00 UTC
ERROR: DOCCONF_DEFAULT "ENV-SLE-all" not found in current directory.
Check you config file at ~/.daps/config.
^^^^
your

daps: Improve DocBook XSLT stylesheets [sf#22]

Reported by tom_schr on 2011-12-16 13:20 UTC
Add compatibility between 1.75 and 1.76. Known bugs:

• <keycap function="alt"/> does not work
• bookmarks (TOC) in PDF does not work

Documentation: Create documentation for DAPS [sf#1]

Reported by tom_schr on 2011-12-16 11:46 UTC
Create documentation for DAPS:

• Quick Start
  • Add metadata information into Quick Starts as well (mainly doc:status and doc:maintainer) [taroth 2010-12-22]
• User Guide

daps: Investigate Autoconf Mechanism [sf#29]

Reported by tom_schr on 2012-01-26 19:57 UTC
It would be beneficial to investigate some time for a good autoconf mechanism. A simple configure, make, and make install should just work as expected.

This makes it easier to support different Linux distributions (or, in a far future, maybe also Cygwin).

Some useful links:

• http://www.gnu.org/software/autoconf/manual/autoconf.html
• http://sourceware.org/autobook/autobook/autobook_toc.html
• http://mij.oltrelinux.com/devel/autoconf-automake/
• http://fsmsh.com/2753
• http://devernay.free.fr/cours/IHM/automake/autoconf_tutorial.pdf
• http://www.lugod.org/presentations/autotools/presentation/autotools.pdf

daps: Generate SPEC files with daps [sf#12]

Reported by tom_schr on 2011-12-16 12:34 UTC
Generate spec files with daps via spec file template and book specific information in the ENV files. DEF file content should go into the set ENV-file. Create spec file with package-src target.

daps: Improve FOP support [sf#18]

Reported by tom_schr on 2011-12-16 13:00 UTC
The stylesheets are currently optimized for XEP, but not for FOP. Make sure, attributes which are not supported by FOP are "filtered out".

SUSE branding: Improve CSS Stylesheet [sf#23]

Reported by tom_schr on 2011-12-16 13:21 UTC
The CSS stylesheet needs some love and dedication. Fix also some CSS issues in tables that contain images/annotations (example: Storage Guide)

daps: Allow subdirectories in $BASE_DIR/xml [sf#26]

Reported by fsundermeyer on 2012-01-19 13:46 UTC
Currently all xml files have to reside in a single xml/ directory with no subdirectories. Enabling subdirectories would make large projects much clearer.

$MAIN could prove as a problem - this probably needs to be directly under xml ...

Provide DocBook XSL Stylesheets Update (1.77.x) [sf#36]

Reported by tom_schr on 2012-02-06 18:21 UTC
According to the docbook-apps mailinglist, David Cramer said:
»There will soon be a 1.77.0 (followed by a more stable 1.77.1) [...]«

We soon should switch to a newer versions of the DB XSL stylesheets as the HTML, XHTML, and Webhelp output has been updated considerably.

See also the snapshots at http://snapshots.docbook.org/.

Replace Obsolete PI Mechanism for product names and numbers [sf#48]

Reported by tom_schr on 2012-02-20 11:30 UTC
In our old days, we used processing instructions (PIs) to create consistent product name and numbers. This was needed to use a documentation for different products without renaming the entity names all the time.

Invent a new mechanism without processing instructions.

Make commandline Usage of --xsltparam easier [sf#3]

Reported by tom_schr on 2011-12-16 11:57 UTC
Should be easier to pass parameter through --xsltparam without the hassle of correct quoting due to shell issues.

daps: Consider XSLT 2.0 [sf#20]

Reported by tom_schr on 2011-12-16 13:07 UTC
We should have a deep look into XSLT2, maybe it could be integrated into daps somehow.

Add a "halt on all errors" option [sf#24]

Reported by fsundermeyer on 2011-12-20 12:10 UTC
When generating packages, daps should exit when an images conversion fails or when graphics are missing.
However, when writing/maintaining a document, displaying a warning rather than exiting is the preferred behavior.

Create a general switch/config option which enables an "halt on errors mode". Add conditional exit statements to the make files.

Halt on errors needs to be explicitly enabled, default should be to only issue warnings.

Fix variable declarations in bin/daps [sf#30]

Reported by fsundermeyer on 2012-01-27 23:39 UTC
There are two types of variables that need to be properly declared/set in bin/daps:

1. Variables local to the script such as *_CMDL
   These need to be declared as local
2. Global Variables that need to be exported for further use in the Makefiles
   These need to be added to the VARLIST array

bin/daps also contains an "UNSETLIST". This should not be necessary when properly declaring local variables. Also check the makefiles - "ifndef" should only be used on variables that get exported from bin/daps!

dsprelim wants to set doc:prelim=no (expected: yes) [sf#38]

Reported by taroth21 on 2012-02-07 15:25 UTC
Output of dm dsprelim:
Should I set the properties: [...] doc:prelim=no?

From a usability POV I would expect just the opposite:
dm dsprelim should set doc:prelim=yes.

What do you think?

Check included Makefiles [sf#16]

Reported by tom_schr on 2011-12-16 12:49 UTC
Check, if obb.mk, variables.mk, help.mk are needed

SUSE branding: epub stylesheets rely on role="html" attribute of imageobject [sf#49]

Reported by fsundermeyer on 2012-02-21 11:42 UTC
When imageobject does not contain a role="html" attribute, the image search path for the epub stylesheets is

$DAPSROOT/build/.tmp/$NAME/<IMAGE>

Correct would be

$DAPSROOT/build/.tmp/$NAME/images/<IMAGE>

Callout Numbers Not Showing Up [sf#42]

Reported by taroth21 on 2012-02-09 16:50 UTC
After moving to DAPS "pre1.0", the callout images no longer appear in the PDF (for example, DAPS User Guide, see attachment). According to Frank, this may be related to
https://sourceforge.net/p/daps/tickets/40/

daps: Retain Entities during Profiling [sf#13]

Reported by tom_schr on 2011-12-16 12:43 UTC
When writing profiled sources a new Doctype Header is written rather than using the Doctype header of the original file. Therefore file-specific entities, for example, are deleted during profiling.

This needs fixing:

• extracting the original doctype header (the hard part)

    => function getFirstEntity from
        $DTDROOT/lib/getentityname.py may be helpful but contains errors!!
    => perhaps lxml has got a solution: http://lxml.de/parsing.html

• passing the header to the profiling stylesheet as stringparam (the easy part)

SUSE branding: Fix Bugzilla bugs [sf#21]

Reported by tom_schr on 2011-12-16 13:18 UTC
Fix bnc#702276 from Bugzilla

daps: Generate TAB completion [sf#10]

Reported by tom_schr on 2011-12-16 12:28 UTC
Create completion script for options and subcommands

Here are some links:

• http://www.caliban.org/bash/
• http://www.debian-administration.org/articles/316
• http://www.debian-administration.org/articles/317
• http://www.linuxjournal.com/content/more-using-bash-complete-command

SUSE branding: Provide Webhelp output? [sf#35]

Reported by tom_schr on 2012-02-06 16:17 UTC
The DocBook stylesheets provides a new output format, the so called "Webhelp".

It create pages with search functionality which could be used for our doc server. However, it needs some (more) time and effort to provide a seamless integration with daps.

Further information:

• See http://wiki.docbook.org/WebHelp for some example pages (very nice!). It needs also good CSS styling.
• Documentation about Webhelp can be found here: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/content/ch01.html
• As Webhelp is Ant-based, it needs to rewrite to our Makefile approach. See the useful thread in the docbook-apps mailinglist here: http://lists.oasis-open.org/archives/docbook-apps/201202/msg00022.html

Allow Custom Stylesheets [sf#2]

Reported by tom_schr on 2011-12-16 11:54 UTC
Allow switching between stylesheet sets easily.

Sanitize paths [sf#27]

Reported by fsundermeyer on 2012-01-23 13:57 UTC
All paths must not end with a trailing slash.
Write a global function that checks and, if needed, sanitizes paths ending with a slash.

daps: Replace "turn on" only switches [sf#7]

Reported by tom_schr on 2011-12-16 12:08 UTC
replace turn on only switches -cdr with turn on/off switches

Update Manpage [sf#15]

Reported by tom_schr on 2011-12-16 12:48 UTC
Update, man page and new name for trunkcopy.sh

daps: Generate Manpages directly [sf#4]

Reported by tom_schr on 2011-12-16 12:03 UTC
Generate man pages via ENVfile and daps instead of calling a stylesheet directly (daps makefile)

daps: Expand Tilde (~) in Config Files? [sf#46]

Reported by tom_schr on 2012-02-17 15:59 UTC
Consider the following line in the DAPS configuration file:

DAPSROOT="~/daps/"

The tilde cannot be expaned. DAPS complains with the following error message:

ERROR: dtdroot ~/daps/ is no valid directory

According to Frank, make does not like (or do not know) how to expand the tilde. Maybe we can support make by either providing an expansion mechanism (through sed or similar) or we declare it as "not supported". :)

SUSE branding: Document Stylesheet Parameters [sf#37]

Reported by tom_schr on 2012-02-07 09:42 UTC
The original DocBook XSL stylesheets have been documented through a Literate Programming mechanism. Investigate how this can be used to improve developer documentation.

Useful links:

• http://nwalsh.com/docs/articles/dbdesign/#litprog
• http://docbook.sourceforge.net/release/litprog/current/html/ldocbook.xml

SUSE branding: Stylesheets produce invalid HTML 4.01 Transitional [sf#34]

Reported by tom_schr on 2012-02-06 16:03 UTC
(Original from https://bugzilla.novell.com/show_bug.cgi?id=708637):

»Generate a htmlsingle document and check it with http://validator.w3.org/check.«

The generated HTML output is pretty awkward as some obscure HTML constructs are being used. DocBook XSL provides these HTML output formats:

• HTML: this is the old format
• XHTML: these stylesheets are automatically generated from the HTML. They create XHTML 1.0 Transitional files
• XHTML 1.1: same as XHTML, but generates XHTML 1.1 files
• (X)HTML5: New, but partly autogenerated and based on the XHTML stylesheets. Creates HTML5 files.

XHTML, XHTML 1.1, and (X)HTML5 can be improved by a cleanup stylesheet, if needed. Such a solution was implemented in my DoCookBook project (see https://sourceforge.net/p/doccookbook/code/ci/1d81f4c4b7fe5be07e26375afd577afea721eff9/tree/frameworks/xslt/misc/html2cleanhtml.xsl?format=raw).

Although we talked about this, maybe we should reiterate it which option is feasible and useful (also in the light of future things like XSLT2.0).

daps: Integrate diffmk into daps to enable Changebars [sf#50]

Reported by tom_schr on 2012-03-02 08:05 UTC
We need to package Norman Walsh's diffmk package to enable changebars.

Actually there are two diffmk's. There is one on our OBS Repo, but it is the Perl version. Norman rewrote this version to Java.

What we need to do is:

1. Package the Java version
2. Integrate it somehow in daps (be it directly or indirectly integrated)
3. Build the book

The general procedure is also documented in Bob Stayton's DocBook XSL book. Currently, only XEP and AntennaHouse supports changebars in PDF. There is a customization layer which is available on the DeltaXML homepage. Other tools for comparing are available on the DocBook Diff page.

daps: Display of admonitions differs in HTMl and single-HTML [sf#45]

Reported by taroth21 on 2012-02-17 10:57 UTC
single-HTML is lacking the icons for the boxes showing "note" and "important" elements, they are displayed like this:

[Important] Product Registration And Updates
[Note] Package Dependencies

I didn't stumble across any warning or tips yet, but I guess the same is true for them.