Missing spaces at single hard returns in PDFs

[hillaryfraley]

When we generate offline PDFs according to the process described in #1779, the process seems to delete single hard returns without adding a space after terminal punctuation.

For example, if the markdown text is:
This is sentence one.
This is sentence two.

In the PDF, this text will appear as:
This is sentence one.This is sentence two.

The PDF also shows a gray box around the first letter of the second sentence at points where this happens.

This is an issue with:

• Bug (site functionality or styling)
• Errata (fix needed for doc content)
• New content (guide wanted)
• Update (Add missing or refresh existing content)
• Enhancement (add new site functionality)

Expected Behavior

The PDF conversion process should interpret single hard returns as a space between sentences. This should not apply to text that is formatted into bulleted or numbered lists.

To use the same example, if the markdown text is:
This is sentence one.
This is sentence two.

In the PDF, this text should appear as:
This is sentence one. This is sentence two.

Current Behavior

If the markdown text is:
This is sentence one.
This is sentence two.

In the PDF, this text currently appears as:
This is sentence one.This is sentence two.
...with a light gray box around the T in the second instance of "This"

Screenshots (if appropriate):

[rnevius]

@hillaryfraley this may be an Adobe Acrobat bug. The generated HTML is correct...As you noticed, it looks like Acrobat is interpreting \n newline characters incorrectly. Unless we look for an alternate option to using Acrobat (started in https://github.com/sensu/sensu-docs/compare/update/ebook), we may need to manually join these lines in a text editor before generating PDFs. 😕

[hillaryfraley]

@rnevius thank you for investigating. I will test to see how onerous it is to manually rip and replace all the newlines with a space.

[hillaryfraley]

@rnevius Is https://wkhtmltopdf.org/ still a viable option for automating PDF generation for the docs site? It looks like the newline thing isn't an issue in wkhtmltopdf.

[rnevius]

@hillaryfraley wkhtmltopdf isn't a good fit (as far as I can tell)...I did some tests and internal links / Table of Contents are completely broken. There are also some weird rendering bugs (different than the ones pointed out in this issue and others).

I also did some testing a few weeks ago with an automated PDF build script using Puppeteer. Using Puppeteer would be awesome, as it builds offline docs exactly how they appear in Chrome (using the offline layouts). But like wkhtmltopdf, Puppeteer also has issues with the internal links, so this script isn't useful at the moment.

It may be possible to rewrite the offline docs layouts so that the site would act like a single-page template/site. In other words, all content for a given Sensu version would appear on one "page". If that's possible (I'd have to investigate), we could use Puppeteer to automate the PDF builds...

Thoughts about all of this?

[cwjohnston]

@rnevius thanks for the update. Can you provide a time estimate on a spike for this approach with Puppeteer?

I would like to improve this offering for offline use but for the time being would prefer to live with the current limitations rather than invest much more than a few hours in investigating an alternative technology.