dita4publishers/org.dita4publishers.html5

Generate complete HTML5-based Web sites from DITA files. Releases are in main dita4publishers project.

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

org.dita4publishers.html5's Issues

Block elements with content in subelements loses whitespace

Given this markup:

<p><b>Bug:</b> <ph>IMPALA-377</ph></p>

The result loses the space between the b and the ph:

Bug:IMPALA-377

Feature request: (navigation) footer activation boolean

Having an option of including or not including the navigational footers (as distinct from the screen reader ones normally at the top right) via the available parameters would be good. That way one could just set something like args.footer.active to "no" to get rid of it (assuming current default behaviour would be "yes").

Having the parameter as args.footer.active, aside from being fairly obvious, would also allow for future footer customisation by specifying footer specific CSS files or whatever else.

Obviously the other major advantage of doing it this way is the parameters can be specified for every transtype used with the plugin, which covers quite a lot of them.

As a side note, once this is active I can demonstrate a non-FOP based method of using one of the existing output formats to generate PDFs utilising either OpenDocument templates or Microsoft Word templates ... thus catering to the end user demand of wanting their favourite theme/style to be used in the output. Unlike all the other methods this one doesn't cost thousands of dollars to deploy either (actually it costs nothing).

Remove @name

Deprecated in HTML5:
http://www.w3.org/TR/html5/obsolete.html#obsolete-but-conforming-features

add support for hdf, hdr, and ftr parameters to the HTML5 transtype

Add table wrap content

Table ID generation is not correct: missing topic ID

The table IDs in the generated HTML do not reflect the topic IDs. Need to use setid named template to set the @id value.

Previous and Next links on chunked content

@drmacro Need your help with that one!

The Previous and Next links resolution on this file
https://github.com/dita4publishers/org.dita4publishers.html5/blob/master/xsl/reltable.xsl

Do not work, because it does not check if a topiref is a result of a chunk

Also there are different kind of chunk, but I am far to have understand all aspects of @chunk, which I find personally complex to understand.

In the code, for example, on line 227, we have:

$topicref/preceding::*[df:isTopicRef(.)][1] | $topicref/ancestor::*[df:isTopicRef(.)][1])[last()]

Do you think the expression should be something like:

$topicref/preceding::*[df:isTopicRef(.)][not(@chunk)][1] | $topicref/ancestor::*[df:isTopicRef(.)][not(@chunk)][1])[last()]

Also the templates are used in jsAndCss.xsl to pass the info to the javascript d4p object.

I used your great example of chunking content in the test directory.

Add optional ajax navigation

This is to reduce documentation size for big documentation.

Language code for Simplified Chinese is wrong in strings.xml

Is zn-ch, should be zh-cn

Possible issue with topic-href-fixup code

I think I found an issue with the href-fixup.

I have topicref to a glossentry, with a @keys="def-event". The @href point to a file in a parent directory (outer).

Then later, I use the abbreviated-form @keyref="def-event"

The resulting code with the d4p-html5 transtype has the wrong reference, but when i use the xhtml one, it is correct.

I think, once the abbreviated-form is rendered as an xref, the change is not retained since it is processed after the href-fixup hook is used.

The template in cause seems to be in ~/DITA-OT1.8.5/plugins/org.dita.xhtml/xsl/xslhtml/dita2htmlImpl.xsl, line 4170:

 <!-- Function to look up a target in the keyref file -->
  <xsl:template match="*" mode="find-keyref-target">
    <xsl:param name="keys" select="@keyref"/>
    <xsl:param name="target">
      <xsl:value-of select="$keydefs//*[@keys = $keys]/@href"/>
    </xsl:param>
    <xsl:choose>
      <xsl:when test="contains($target, '://')">
        <xsl:value-of select="$target"/>
      </xsl:when>
      <!-- edited  on 2010-12-17 for keyref bug:3114411 start-->
      <xsl:when test="contains($target, '#')">
        <xsl:value-of select="concat($PATH2PROJ, substring-before(substring-before($target, '#'), '.'), $OUTEXT, '#', substring-after($target, '#'))"/>
      </xsl:when>
      <xsl:when test="$target = ''">
        <xsl:value-of select="$OUTEXT"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="concat($PATH2PROJ, substring-before($target, '.'), $OUTEXT)"/>
      </xsl:otherwise>
      <!-- edited  on 2010-12-17 for keyref bug:3114411 end-->
    </xsl:choose>
  </xsl:template>

Need to take copy-to into account when determining result filenames

dita4publishers/org.dita4publishers.common.html#4

Specifying max navigation depth

I've been trying to override the max navigation depth of 5, by passing -Dd4p.max.nav.depth=12 -Dd4p.max.toc.depth=12 to ant, and adding them both to the transform properties in Oxygen, but I can't see that the properties are taking effect all. I have topics that are at a depth of 6 or 7 (it's hard to tell which) and they are not showing up in the navigation. I've been trying to figure this out for a couple days, and not finding much on Google. Also, if I wanted to change the defaults for these (once I figure out exactly what to pass), would I add them to the parameters.xsl in the plugin?

What is the best way to debug from the front end?

I'd like to contribute a few fixes to the css that powers the default theme, but I can't seem to figure out where the proper code to edit it is. Since I am going to be styling the a custom HTML5 transform soon, it'd be nice for me to figure out what the best way to debug the front end is.

I currently have some test guides that I work with, so I build them with the HTML5 transform, then put the output in a web server and view it in the browser. I like to do my debugging in the browser, as that makes the most sense, but using the YUI compressor makes it impossible to track down anything.

Is there a way to turn off YUI compressor? How are you debugging the front end?

I suspect as this plugin gets more and more into the wild, this is a question that will come up frequently.

Integrate datatable javascript library into default themes

http://www.datatables.net

Fix active trail

Active trail os broken with latest change in the code

Navigation reflects resource-only topics

Using the test documents in the dita-community project org.dita-community.indirectortopic.doctypes, the topics that are linked as resource-only topics are included in the navigation ToC and in prev/next links. They should not be.

I think the issue is with the relationship table, which is relating resource-only topics to non-resource-only topics. This is not something you would normally do, but the result should be that the resource-only topics are not included in navigation (and the links should not be instantiated).

Unresolvable topicref causes avoidable failure in reltable.xsl

Code needs to check that it actually gets a topic from the topicref when constructing next link (prev link already makes the check)

Factor out requirement for math plugins

The HTML5 plugin should not have a hard requirement on the math plugins.

Nav generation does not ignore peer-scope topicrefs

Implements search engine

Consider using lunrjs, reference provided by Mica,

Whitespace squeezing code squeezes too much

The clean-linebreaks mode results in the removal of space between elements when it should not. It is also not sufficiently aggressive in collapsing collapsable whitespace.

Infinite loop from search index generation for maps with submaps

Note sure of the exact configuration of maps or topicrefs that causes the problem, but maps with submaps and key definitions result in what appears to be an infinite loop over the "Generating search index" process. This would happen if one or more map documents get templates applied to them in that mode.

Workaround is (should be) to set the generateSearchEngine Ant and XSLT parameter to "false"

dfn and abbr

There a is need to render html5 abbr element and dfn as well.

Generate HTML5 HTML files

The generated files should conform to HTML5 as much as Saxon 9.1 is able to.

This means using method "html" and ensuring that the result document does not have the xhtml namespace. If both of these conditions are met then the HTML files will reflect HTML5 requirements. In particular, empty ("void") elements will be serialized as only start tags and literal markup within style elements will not be escaped.

Implements theme versionning

Add translation for index in TOC

Charcter Map

Should we put this stylesheet in the html5 plugin:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xd="http://www.oxygenxml.com/ns/doc/xsl"
  exclude-result-prefixes="xs xd"
  version="2.0">

 <xsl:character-map name="chars-127to160">
    <!-- Map characters 127 to 160, which are invalid HTML characters
         but valid (but non-printing Unicode characters). Characters in this
         range seem to be a side effect of differences between Windows codepage
         1252 and ISO-8859-1 (see http://stackoverflow.com/questions/631406/what-is-the-difference-between-em-dash-151-and-8212)
       -->
    <xsl:output-character character="&#128;" string="&#x20AC;"/><!-- € x80 -->
    <xsl:output-character character="&#130;" string="&#x201A;"/><!-- ‚ x82 -->
    <xsl:output-character character="&#131;" string="&#x0192;"/><!-- ƒ x83 -->
    <xsl:output-character character="&#132;" string="&#x201E;"/><!-- „ x84 -->
    <xsl:output-character character="&#133;" string="&#x2026;"/><!-- … x85 -->
    <xsl:output-character character="&#134;" string="&#x2020;"/><!-- † x86 -->
    <xsl:output-character character="&#135;" string="&#x2021;"/><!-- ‡ x87 -->
    <xsl:output-character character="&#136;" string="&#x02C6;"/><!-- ˆ x88 -->
    <xsl:output-character character="&#137;" string="&#x2030;"/><!-- ‰ x89 -->
    <xsl:output-character character="&#138;" string="&#x0160;"/><!-- Š x8A -->
    <xsl:output-character character="&#139;" string="&#x2039;"/><!-- ‹ x8B -->
    <xsl:output-character character="&#140;" string="&#x0152;"/><!-- Πx8C -->
    <xsl:output-character character="&#142;" string="&#x017D;"/><!-- Ž x8E -->
    <xsl:output-character character="&#145;" string="&#x2018;"/><!-- ‘ x91 -->
    <xsl:output-character character="&#146;" string="&#x2019;"/><!-- ’ x92 -->
    <xsl:output-character character="&#147;" string="&#x201C;"/><!-- “ x93 -->
    <xsl:output-character character="&#148;" string="&#x201D;"/><!-- ” x94 -->
    <xsl:output-character character="&#149;" string="&#x2022;"/><!-- • x95-->
    <xsl:output-character character="&#150;" string="&#x2013;"/><!-- – x96 -->
    <xsl:output-character character="&#151;" string="&#x2014;"/><!-- — x97 -->
    <xsl:output-character character="&#152;" string="&#x02DC;"/><!-- ˜ x98 -->
    <xsl:output-character character="&#153;" string="&#x2122;"/><!-- ™ x99 -->
    <xsl:output-character character="&#154;" string="&#x0161;"/><!-- š x9A -->
    <xsl:output-character character="&#155;" string="&#x203A;"/><!-- › x9B -->
    <xsl:output-character character="&#156;" string="&#x0153;"/><!-- œ x9C -->
    <xsl:output-character character="&#158;" string="&#x017E;"/><!-- ž x9E -->
    <xsl:output-character character="&#159;" string="&#x0178;"/><!-- Ÿ x9F -->
  </xsl:character-map>


</xsl:stylesheet>

Implements way to add script on multiple regions

args.debug=no prevent theme to be builded

Update yui compressor to 2.4.9

The 2.4.8 version was broken, bug fixed here: https://github.com/yui/yuicompressor/releases

Create a full featured responsive theme for the html5 plugin

Static site search for HTML5

I mentioned this to Bertrand, but I did some research and felt like lunr.js would fit the bill pretty well. There are few other static-site javascript based search engines, but I liked this one the best. If you want the other few, let me know.

Map-level chunk="to-content" may not work

Oracle reports that map-level chunking does not work with HTML5 but does for EPUB.

Ideas and notes for version 2

Placeholder for discussion for version 2

Disable search engine when page are served locally

Finish the mobile theme, add toggle option for the menu.

XSLT Coding error for index processing: no @tunnel="yes" for parentId, topicid

dita.map.html5:
     [xslt] Transforming into /Users/ekimber/workspace/cloudera/tomcat/apache-tomcat-7.0.55/webapps/cloudera/cloudera
     [xslt] Processing /Users/ekimber/workspace/cloudera/from-client/docs/temp/html5/cloudera.ditamap to /Users/ekimber/workspace/cloudera/tomcat/apache-tomcat-7.0.55/webapps/cloudera/cloudera/index.html
     [xslt] Loading stylesheet /Applications/oxygen/frameworks/dita/DITA-OT/plugins/com.cloudera.html5/xsl/map2cloudera.xsl
     [xslt] /Applications/oxygen/frameworks/dita/DITA-OT/xsl/common/dita-utilities.xsl:8:80: Warning! Stylesheet module plugin:org.dita.base:xsl/common/dita-utilities.xsl is included or imported more than once. This is permitted, but may lead to errors or unexpected behavior
     [xslt] /Applications/oxygen/frameworks/dita/DITA-OT/plugins/org.dita4publishers.html5/xsl/map2html5Nav.xsl:443:69: Fatal Error! Parameter parentId is not declared in the called template
     [xslt] /Applications/oxygen/frameworks/dita/DITA-OT/plugins/org.dita4publishers.html5/xsl/map2html5Nav.xsl:453:69: Fatal Error! Parameter parentId is not declared in the called template
     [xslt] /Applications/oxygen/frameworks/dita/DITA-OT/plugins/org.dita4publishers.html5/xsl/map2html5Nav.xsl:466:69: Fatal Error! Parameter parentId is not declared in the called template
     [xslt] /Applications/oxygen/frameworks/dita/DITA-OT/plugins/org.dita4publishers.html5/xsl/map2html5Template.xsl:244:61: Fatal Error! Parameter topicref is not declared in the called template
     [xslt] /Applications/oxygen/frameworks/dita/DITA-OT/plugins/org.dita4publishers.html5/xsl/map2html5Template.xsl:250:59: Fatal Error! Parameter topicref is not declared in the called template
     [xslt] /Applications/oxygen/frameworks/dita/DITA-OT/plugins/com.cloudera.html5/xsl/map2clouderaImpl.xsl:283:61: Fatal Error! Parameter topicref is not declared in the called template
     [xslt] /Applications/oxygen/frameworks/dita/DITA-OT/plugins/com.cloudera.html5/xsl/map2clouderaImpl.xsl:288:59: Fatal Error! Parameter topicref is not declared in the called template
     [xslt] Failed to process null

responsive image

Investigate: http://www.cdnconnect.com/docs/foresightjs

Figure are not resolved properly

When referencing a figure with a xref, only the label Figure appear in the reference.

Revisit navigation generation

Related to #23

Requirements to be added

Add a way to add version on theme

Could be a hash, md5...

isActiveTrail does not take @copy-to into account

See this line:

<xsl:variable name="isActiveTrail"  select="descendant::a[ends-with(@href, $resultUriFilename)]"/>

in map2html5Nav.xsl

It is only looking at @href, needs to consider @copy-to when present.

Consider implementing vue.js in the theme

Would allow to make javascript really reusable accross projects

Remove dependency on HTML2 plugin by moving any HTML2-provided code

Either move the code into the HTML5 plugin or into a new common plugin.

Fix relative path in the navigation

href in the navigation use relative path in all situations, like '../concept/topicA.html'.

My understanding is that it's not a big problem, it is not super clean implementation but it is a problem when clients have big documentation (over 100 Mo), because all topics in the same directory will have a longer href value which increase documentation size.

Support translation for javascript variables

In javascript code, the button added by javascript could not be translated:
Example

var navigation = {

 // ...
  // text value
  text: {
    expand: 'Expand All',
    collapse: 'Collapse All',
    close: 'Close Menu'
  },
 // ...
}

Need to add a d4p.locale variable that will hold the translations.

Implement cache manifest

See: https://developer.apple.com/library/safari/documentation/iPhone/Conceptual/SafariJSDatabaseGuide/OfflineApplicationCache/OfflineApplicationCache.html

Issue with theme related Ant parameters

Using the latest release (dita4publishers-0.9.19RC12 and this plugin) with DITA OT 1.7.5, I am trying to run the transform d4p-html5 on the garage example using the following command:

java -jar lib/dost.jar /i:samples/hierarchy.ditamap /transtype:d4p-html5

I see the following in my log:

[echo] html5.site.config=/Users/user/Downloads/DITA-OT1.7.5/plugins/org.dita4publishers.html5-master/${html5.libs.dir}/themes/dita-d4p-classic/config.xml
[echo] html5.site.theme=dita-d4p-classic
[echo] html5.temp.libs.dir=/Users/user/Downloads/DITA-OT1.7.5/temp/${html5.libs.dir}
[echo] html5.temp.theme.dir=/Users/user/Downloads/DITA-OT1.7.5/temp/themes/dita-d4p-classic
[echo] html5.theme.config.dir=/Users/user/Downloads/DITA-OT1.7.5/plugins/org.dita4publishers.html5-master/${html5.libs.dir}/themes
[echo] html5.theme.dir=/Users/user/Downloads/DITA-OT1.7.5/plugins/org.dita4publishers.html5-master/themes/dita-d4p-classic
[echo] html5.theme.file=themes/dita-d4p-classic/css/style-min.css
[echo] html5.theme.output.dir=/Users/user/Downloads/DITA-OT1.7.5/out/themes/dita-d4p-classic
[echo] html5.themes.dir=themes
[echo] html5.themes.output.dir=themes

This transformation fails with the following message:

Extra warnings counted
[echo] Theme dita-d4p-classic not found in /Users/user/Downloads/DITA-OT1.7.5/plugins/org.dita4publishers.html5-master/themes/dita-d4p-classic, building it
...
...
BUILD FAILED
/Users/user/Downloads/DITA-OT1.7.5/build.xml:44: The following error occurred while executing this line:
/Users/user/Downloads/DITA-OT1.7.5/plugins/org.dita4publishers.html5-master/build_transtype-html5.xml:331: The following error occurred while executing this line:
/Users/user/Downloads/DITA-OT1.7.5/plugins/org.dita4publishers.html5-master/build_transtype-html5.xml:692: input file /Users/user/Downloads/DITA-OT1.7.5/plugins/org.dita4publishers.html5-master/${html5.libs.dir}/themes/dita-d4p-classic/config.xml does not exist

The file config.xml is missing in org.dita4publishers.html5-master/html5-themes/themes/dita-d4p-classic
and it is not clear why.

There may be some confusion between use of the parameters html5.theme.dir and html5.theme.config.dir

Error with d4p_video

Using this code:

<d4p_video id="my-video" width="640" height="360">
  <d4p_video_source value="../path/to/my.mp4" type="video/mp4"/>
</d4p_video>

The video is not copied at all.

Example used:
dita4publishers/d4p-sample-data/blob/master/video-example/video-example.ditamap

Strategy to minimize documentation size for big documentation

Few ideas:

• set indendation to no

default would be

<xsl:output name="html5" ...  indent="no" />

with args.draft or args.debug

<xsl:output name="html5" ...  indent="yes" />

• change $newline variable to be empty string on production and a line break with args.draft or args.debug
• change classname in the navigation, ex. sel for selected, but I do not like this one because it makes them less readable. For now we have:
  • has-child
  • selected
  • active
  • collapsible
  • collapsed
• Maybe add theses class by javascript instead of having them in the html. I implemented them like this to make them work without javascript