dita4publishers/dita4publishers

DITA for Publishers

Version 1.1.0 Under development

Master project for the DITA for Publishers activity. This project includes the toolkit plugins and samples as git submodules. See the wiki for details on how to set up new clones of this project.

NOTE: Issues for specific transformation types (EPUB, HTML5, etc.) are maintained in the project each transformation type. If you're not sure which project an issue applies to, feel free to submit the issue against the dita4publishers project.

News

5 Aug 2021 Release 1.0.0RC28

Many updates. Tested against OT 3.6.1 (see release notes in user guide). Many Word2DITA issues resolved.

24 April 2016: EPUB3 implementation essentially complete with the addition of font embedding and obfuscation.

7 Oct 2014: EPUB3 implementation is under way. See the org.dita4publishers.epub project for details.

Publishing the User Guide

The D4P User Guide is published via GitHub Pages through the separate repo dita4publishers.github.io.

To update the user guide do the following:

1. Using InDesign, update the cover graphic to reflect the latest release and copyright date (docs/D4P Logo and User Guide Cover/D4P_UserGuide_cover Folder/D4P_UserGuide_cover.indd)
2. Export new copies of cover-graphic.png (300PPI) and epub-cover-graphic.png (72PPI) to the user_docs/d4p-users-guide/images directory
3. Run the html5-d4p-user-guide ant target
4. Copy the generated HTML (d4p-users-guide from the build/docs/html5 directory) to the dita4publishers.github.io repo on branch main.
5. Commit updates to dita4publishers.github.io repo and push

dita4publishers's Issues

cloneAll.sh only works if you have commit access

Not sure if this is the intention, but the script cloneAll.sh only works if you have commit access to the repos.

Invalid use of aria-labelledby, target ID is missing

In an EPUB build I'm getting the following ..

  <main role="main">
     <article role="article" aria-labelledby="ariaid-title1">
        <h1 class="title topictitle1"><span class="enumeration_chapter">Chapter 2.</span> Installation</h1>

There is no id="ariaid-title1", so the aria-labelledby="ariaid-title1" is invalid. When I do a straight HTML5 transform, the ID is set on the H1 tag, but for some reason when I do an EPUB build, the ID is gone. This exists in all files, and thus creates a lot of noise with an epubcheck.

Provide runtime options to turn off figure and table numbering for HTML outputs

Provide option to turn off generation of figure and table numbers in HTML outputs (HTML5, EPUB, HTML2)

Reltable links not appearing when args.rellinks is set for PDF output

From D.P. Clark via DITA Users list:

I have added the D4P plugin collection to my environment to allow for enumeration in HTML output. It's working fantastically. However, as a side effect, my custom PDF plugin no longer shows related links generated from relationship tables. The args.rellinks parameter maintains the same value in the log. I also did some testing with the include.rellinks and includerelatedlinkroles variables directly without much luck.

Specifying dc:identifier from map

I'm not finding the documentation on how to specify the OPF dc:identifier value. The concept of a publication ID is mentioned in "EPUB and Kindle Transformation Parameters," but there's no topic (that I've found) that says how to do it. After some digging, I see that the value of bookid/isbn or bookid/booknumber are used for this purpose (perhaps others as well?).
I feel that using the value is never the right choice, since an ISBN is specific to each publication type, unless the map was only used to generate an EPUB, it will be wrong to think it can be used for multiple publication types. is probably not a great choice either since that's probably meant for some other purpose. I would stick with using your custom "opf-metadata" container for this purpose. Perhaps like this ..

<data name="opf-metadata">
    <data datatype="dc:identifier">the-book-id</data>
</data>

Update Word2DITA documentation to reflect latest stuff

Update docs to reflect new features, new style-to-tag map markup, etc.

epub.javascript.file applied to too many files

If the --epub.javascript.file argument is used to set a JS file, it's being applied to all XHTML files, including the TOC (nav.xhtml) and generated index (generated-index.xhtml). I would expect that the scripting would be applied to the "content" files, not the navigation files., and with the NAV, it's likely to be ignored by the reader or possibly mess things up. While the generated index is marked as "scripted" in the OPF manifest, it doesn't actually have the JS file referenced within the HTML, so epubcheck will mark it as an error.

By default, I'd assume there's no scripting in these navigation files, and possibly you could add more parameters to enable it there, but that seems like an edge case to me.

EPUB UTC time conversion half-fixed

As mentioned on dita-users the previous fix to convert localtime to UTC is an odd half-fix. Specifically the time conversion does correctly calculate the difference between the system time which the OT runs on and UTC, including adjusting the date where necessary. However the time is only ever recorded as a 12 hour clock and not a 24 hour clock. So any UTC time between 13:00Z and 23:59Z loses 12 hours.

I am not certain what happens with 00:00Z since I haven't run a transformation at exactly that time. I'm also not certain if this is an issue with XSLT or Java itself. It is, however, less of a worry than the situation prior to the half-fix since it does at least prevent the generation of a timestamp in the future from the point of the transformation which was previously the case for those of us ahead of UTC (i.e. from Europe to Asia and Oceania). It is also not picked up by epubcheck.

Add prefix to "special" files (convenience)

It would be nice to prefix "special" files with an underscore so they float to the top when viewing in Oxygen. In EPUBs with many content files, it's difficult to locate these files.

content.opf 		=> _content.opf
nav.xhtml		=> _nav.xhtml
generated-index.xhtml 	=> _index.xhtml
... ?

Need more robust method for adding metadata to OPF

The method described in the docs, "Creating Arbitrary EPUB OPF Metadata," doesn't do what's needed for adding metadata to the OPF. I want to add the following meta entry ..

<meta property="rendition:flow">scrolled-doc</meta>

The suggested data/name+value doesn't provide what's needed to create this type of metadata, and there are many other types of metadata that can't be created with this structure. How about this ..

<data name="opf-metadata">
    <data datatype="meta" name="property" value="rendition:flow">scrolled-doc</data>
</data>

I originally suggested a more complex structure, which might still be better in the long run, but this allows for 'datatype' to specify the metadata element name (sometimes sometimes not), and if 'datatype' is used, then 'name' and 'value' specify an attribute and its value (not 'name' and 'content' attribute values as your current structure uses. This revision came about after I saw the need for a better way to handle the dc:identifier value. This all may need more thought, but I think it's important to provide a more complete method for defining these values in the dita map.

Insertion of aria-labelledby element in EPUB XHTML (DITA-OT 2.4.x)

As discussed on dita-users, the current develop branch of the EPUB 3 builds running with DITA-OT 2.4 and tested with both 2.4.0 and 2.4.1 inserts the following element in almost all EPUB XHTML files:

<article role="article" aria-labelledby="ariaid-title1">

The resulting EPUBs then produce "Referenced resource could not be found in the EPUB" errors for each of those files.

The article element is only inserted for XHTML files generated from DITA topic files, so it does not appear in files like nav.xhtml.

The @aria-labelledby attribute is lurking in the OT's org.dita.html5 plugin and requires filtering it out during the EPUB cleanup.

Is DITA4 publishers picky about spaces in file folders?

Using DITA-OT1.8.5, the input path to my map had spaces in folder names. When I ran the "java -jar lib/dost.jar" command to generate ePub, all I got was the Help menu.When I replaced spaces with underscores, it worked.

Travis-CI: test does not work on version 1.7.5

I am trying to implements Travis-CI for the project, since we have to test it on at least 3 versions of the OT, plus multiple transforms.

The current test (a simple map build) works on the version 1.8.5 of the OT but failed on 1.7.5.

https://travis-ci.org/dita4publishers/dita4publishers

The error is:

BUILD FAILED
/home/travis/build/dita4publishers/dita4publishers/DITA-OT1.7.5/test/ant/sample_d4p-html5.xml:11: The following error occurred while executing this line:
/home/travis/build/dita4publishers/dita4publishers/DITA-OT1.7.5/build.xml:44: The following error occurred while executing this line:
/home/travis/build/dita4publishers/dita4publishers/DITA-OT1.7.5/plugins/org.dita-community.adjust-copy-to/adjust-copy-to-preprocess.xml:106: Problem: failed to create task or type job-helper
Cause: The name is undefined.
Action: Check the spelling.
Action: Check that any custom tasks/types have been declared.
Action: Check that any <presetdef>/<macrodef> declarations have taken place.

It might be due to the version of ant on Travis, but I am not sure. It is working on the version 1.8.5.

Automatically generate the cover.html page inside the EPUB archive

We have several users complaining that they don't see the cover page in the generated EPUB file. They set the $cover.graphic.file Ant parameter through the oXygen's transformation scenario.

I tested this functionality with Adobe Digital Edition viewer and the cover page cannot be seen.

I've done some research and I've found an interesting article about how to set a cover in EPUB: Best practices in ePub cover images:
https://www.safaribooksonline.com/blog/2009/11/20/best-practices-in-epub-cover-images/

Reading the article I understood that it's good practice to have a cover.html page in the EPUB archive that points to the image file. Something like this:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Cover</title>
    <style type="text/css"> img { max-width: 100%; } </style>
  </head>
  <body>
    <div id="cover-image">
      <img src="the_cover.jpg" alt="Title of this Thing, Second Edition"/>
    </div>
  </body>
</html>

How do you consider this approach? Is it a good idea to automatically generate this HTML page when a cover image was specified using the cover.graphic.file parameter?

epub failing?

Hi there,

I'm trying to get the epub plugin working with OT 1.8.5.

It's currently failing with this error,
Caused by: javax.xml.transform.TransformerException: Malformed URL plugin:org.dita4publishers.common.xslt:xsl/reportParametersBase.xsl(base file:/C:/ProgFiles/Server/publish/DITA-OT185/plugins/org.dita4publishers.epub/xsl/map2epubImpl.xsl)

Any help is appreciated.

Barb

Refactor List of Tables and List of Figures code from EPUB to common.html

Make the LoT and LoF code available to all HTML-based transtypes, integrate with HTML5.

Outline numbering for titled elements, with metadata for retrieval (as in XREFs)

My immediate need is to include numbering for tables and figures in the text of a link.

For example, it is now possible to number and title the fourth table in the third subsection of the second section of the first chapter thus:
"Table 1-2.3.4, Configuration Settings".

However, when linking to the table with an XREF, if the XREF is emtpy, the link is displayed as "Table 4" because the numbering starts over at each topic.

It would be helpful for users if chapters and descendant topics, tables, figures, could be outline numbered as in the PDF2 plugin as in the preceding example.

Currently, collected-data.xml contains titles of topicrefs and titled descendants but the @xtrc restarts numbering at each chapter. To mimic the PDF2 numbering, there needs to be a way to increment the number of each chapter, so that you can include a number similar to those possible in titles of tables and figures.

From digging around in the D4P plugins, looks like a count() could be added when collected-data.xml is created that could number titled elements so that an XREF override could use them.

DITA OT 2.2.2 Duplicated project name

When trying to use d4p with ot 2.2.2 I get the following errors:

Buildfile: dita-ot-2.2.2\build.xml Duplicated project name in import. Project dita2html5 defined first in dita-ot-2.2.2\plugins\org.dita.html5\build_dita2html5.xml and again in dita-ot-2.2.2\plugins\org.dita4publishers.html5\build_transtype-html5.xml

BUILD FAILED
Target "move-links" does not exist in the project "DOST". It is used from target "dc-preprocess".

Are there any plans to make it work with OT 2 ?

Duplicate "TOC" file?

Is there a benefit to creating a toc.xhtml when there's already a nav.xhtml? Fundamentally they are the same thing. Seems redundant. Maybe I'm missing something?

CSS path troubles

Running a default build ..

dita --input=mymap.ditamap --output=out/epub --format=epub

.. results in the references in the HTML to the CSS files to be invalid ..

<link rel="stylesheet" type="text/css" href="css/csscommonltr.css" />

There's an extra "css" tacked on to the CSS filename .. css/csscommonltr.css.

If the CSS path is specified in the command line, it seems to have no effect on the resulting HTML ..

dita --input=mymap.ditamap --output=out/epub --format=epub --args.csspath=zzz

It does look like this is working correctly (in OT 2.4 and later) for HTML5 and XHTML targets, so I think there's something funky in the D4P code that's forcing "css" as the path, and adding the "css" prefix to the filename.

Travis test for DITA_OT 2.0 failed

Even if the Travis return success, which is strange

Calling command DITA-OT2.0/test/bin/test_all.sh...
Running HTML5 transform on complex_map:
Error: Target "move-links" does not exist in the project "DOST". It is used from target "dc-preprocess".
Running EPUB transform on complex_map:
Error: Target "move-links" does not exist in the project "DOST". It is used from target "dc-preprocess".
Done

Coderefs not resolved for HTML2, HTML5, etc.

Given this topic and the corresponding referenced file:

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="topic_iky_4yf_fq">
  <title>Coderef Test 01</title>
  <body>
    <p>The following contains a coderef to code stored in a separate file:</p>
    <fig
      id="fig_wj2_tyf_fq">
      <title>Direct Coderef</title>
      <codeblock>Before coderef
<coderef href="code/code-file-01.java"/>
After coderef</codeblock>
    </fig>
  </body>
</topic>

The coderef is resolved for normal XHTML output but not for HTML2, HTML5, EPUB.

HTML2 transform: @toc="no" does not hide TOC items

I have appendixes that I need in the output, but not in the TOC. If I set @toc to "no", they show up in the output. As an aside, we also use the frameset and not the index.html file.

Create RC13 releases with fixes for Simplified Chinese language code, missing doctypes package

Fix in HTML5 and common.html for Simplified Chinese language code

Include net.sourceforge.dita4publishers.doctypes plugin in release package.

Incorrect 'images' folder name

As of the 1.0.0RC27 release, a default OT 2.5.4 build (no parameters specified other than input, output, and format), the folder in the EPUB that contains images is named "${images.output.dir}" where in previous builds (and as I'd expect) it was "images". The referenced images do still resolve, but this doesn't seem like a good folder name. Setting the "images.output.dir=images" parameter does "fix" the problem, but this shouldn't be needed.

Improve performance of enumerables structure construct ("data collection")

The current process in common.mapdriven takes quite a long time. There are likely inefficiencies in the code. Need to determine what those are and correct where possible. May also be an issue with how the Xerces grammar cache works (different relative paths for DTDs trigger reload of DTDs already in the cache).

Multiple author entries in map causes validation error

Multiple author entries in map topicmeta creates multiple dc:creator nodes with duplicate IDs in the OPF file (resulting in a validation error).

<metadata>
    ...
    <dc:creator id="aut">Joe Friday</dc:creator>
    <dc:creator id="aut">Suzie Q</dc:creator>
    <dc:creator id="aut">Ima Rose Bush</dc:creator>
</metadata>

Perhaps append an incrementing number to the ID value?

(SF Issue 184) Add base XHTML parameter extension point to all HTML transtypes

Add this line to each of the build_template.xml files parallel with the existing plugin-specific extension parameters:

      <dita:extension id="dita.conductor.xhtml.param"
        behavior="org.dita.dost.platform.InsertAction" 
      xmlns:dita="http://dita-ot.sourceforge.net"/>

Add this to each of the plugin.xml files:

   <extension-point id="dita.conductor.xhtml.param" name="XHTML XSLT parameters"/>

External link without format attribute still tries to read file

I'm not sure if this is by design or not, opening just in case because the markup is fairly common even if it doesn't meet the letter of the specification.

The DITA-OT 1.8 docs had a couple of reltable links to external web pages. Both set scope="external" but neither set @format. These are very old links, one even used type="html" which was how we identified HTML links before DITA went to OASIS. The links have been cleaned up in the DITA-OT 2.0 docs.

But - this type of linking is still commonly found in quite a few docs I'm familiar with. When I run it through the epub transform - and I'm not using the latest code - the df:resolveTopicRef function tries to read both of these as DITA topics, resulting in a long hang followed by errors about the content:

<topicref href="http://opensource.org/licenses/cpl1.0.php"
navtitle="Common Public License, version 1.0" type="html" scope="external" />
<topicref href="http://www.apache.org/licenses/LICENSE-2.0" navtitle="Apache License, version 2.0"
scope="external"/>

I went into the df:resolveTopicRef function and added a test for scope=peer or scope=external right after the current test for @format, and that fixed the problem - the code did not try to read the resources, did not generate errors. I think that this is proper even if the links really should set @format, because there are no other spots today where DITA-OT attempts to external resources - they are presumed unavailable or outside the scope of this content.

Extension point xsl.transtype-epub is not declared in plugin.xml

org.dita4publishers.epub/plugins.xsl mentions "xsl.transtype-epub" in line 3:

<extension id="xsl.transtype-epub"/>

I suspect what was meant is something like this:

<extension-point id="xsl.transtype-epub" name="EPUB XSLT import"/>

Build is failing

Hi,

I tried to build dita4publishers with ivy, I usually use Maven but AFAIK Ivy (the Ant-extension) is reusing the Maven repositories.

But already failed getting the dependencies using "ant resolve" from Maven

[ivy:retrieve] ::::::::::::::::::::::::::::::::::::::::::::::
[ivy:retrieve] :: UNRESOLVED DEPENDENCIES ::
[ivy:retrieve] ::::::::::::::::::::::::::::::::::::::::::::::
[ivy:retrieve] :: apache#ant;1.7.1: not found
[ivy:retrieve] :: apache#commons-logging;1.1: not found
[ivy:retrieve] :: apache#commons-io;1.4: not found
[ivy:retrieve] :: apache#commons-cli;1.2: not found
[ivy:retrieve] :: apache#xml-apis;20080213: not found
[ivy:retrieve] :: apache#resolver;1.2: not found
[ivy:retrieve] :: stax#stax-ri;1.0: not found
[ivy:retrieve] :: saxonica#saxon9;9.1.0.7: not found
[ivy:retrieve] :: saxonica#saxon9-dom;9.1.0.7: not found
[ivy:retrieve] :: saxonica#saxon9-xpath;9.1.0.7: not found
[ivy:retrieve] :: saxonica#saxon9-s9api;9.1.0.7: not found
[ivy:retrieve] ::::::::::::::::::::::::::::::::::::::::::::::

My guess most of you developers have a running Eclipse environment as the Eclipse .classpath file indicates with all Jars within a /lib directory which does not exist in the git repro.

Would it not be nice if this project could be able to run out-of-the-box with using
https://github.com/dita4publishers/dita4publishers/blob/develop/ivy.xml

The usual problem was that the artifact prefix was incorrect.
For instance:
[ivy:retrieve] :: apache#commons-cli;1.2: not found
If searched at the Maven repro:
https://mvnrepository.com/artifact/commons-cli/commons-cli
Would be in ivy.xml not

but

As the libraries were quite old, I felt bold and tried to update to the latest version of JARs to see if the sources are still building, but how are the sources being build? ;-)

Especially when looking the Saxon9-HE (home edition - opensource)
http://www.saxonica.com/products/feature-matrix-9-9.xml
seemed to be worth a try to go on the latest work of technology (as well to be able to report issues).

Unfortunately, I realized today that their Maven artefact was broken,
https://saxonica.plan.io/issues/4158
but locally I could fix everything for me and it is now reported.

Still I would love to test the latest JAR on the source to build..
Please find the updated ivy.xml as an experimental draft in the very end of this issue (you need to do the saxon fix of my issue above to make it work)

PS: The Travis builds are not working see
https://travis-ci.org/dita4publishers/dita4publishers/jobs/451400857
as
https://github.com/dita4publishers/dita4publishers/edit/develop/.travis.yml
is using

• oraclejdk7
  while there is only Java 8 on the machine, you might want to try a
• oraclejdk8

------------- draft of version update of ivy.xml -------------

Localize strings in common enumeration code, elsewhere

From Ben Welman:

The hard code text I meant is
"Part", "Chapter" and "Appendix"(in commonHtmlBookmapEnumeration.xsl and commonHtmlEnumeration.xsl. These string names are NOT in the normal HTML localization, strange.
"Figure" and "Table" in commonHtmlEnumeration.xsl. These string names are in the normal HTML localization.