Publish PDF version of User Guide

[sbrannen]

Overview

The User Guide is currently published in HTML; however, it would be beneficial to provide a PDF download as well.

Related Issues

• Use Rouge syntax highlighting in User Guide #777
• Update Asciidoctor PDF backend of the user-guide #1099

Deliverables

• Configure Gradle build to generate PDF version of the User Guide.
• Use the rouge syntax highlighting support for PDFs.
  • Since rouge is not yet supported for the html5 backend, we would need to have separate configurations for HTML and PDF; see Support multiple docs asciidoctor/asciidoctor-gradle-plugin#28 (comment)
  • Will be addressed in Use Rouge syntax highlighting in User Guide #777.
• Use the rouge syntax highlighting support for HTML.
  • Will be addressed in Use Rouge syntax highlighting in User Guide #777.
• Determine why component-diagram.svg is not embedded in the generated PDF.
  • See Generated images not found when srcdir != destdir asciidoctor/asciidoctor-pdf#271.
• Ensure that component-diagram.svg gets embedded in the generated PDF.
  • See Generated images not found when srcdir != destdir asciidoctor/asciidoctor-pdf#271 (comment) for details.
• Construct links to JavaDoc API as absolute URLs instead of the relative links used in the HTML version of the User Guide.
• Determine if special characters (e.g., emoji from custom display names and glyphs used with unicode mode for the ConsoleLauncher) can be displayed in the generated PDF.
  • See discussion in Emoji support asciidoctor/asciidoctor-pdf#323.
  • Will be addressed in User Guide PDF should support special characters #2315.
• Publish PDF version of the User Guide alongside the HTML version.
  • Currently published as http://junit.org/junit5/docs/snapshot/user-guide/index.pdf
  • Rename the generated index.pdf file to something like junit-user-guide-5.0.0-M5.pdf. Done in Give PDF user guide a better name #2314.

[sbrannen]

in progress