From 7126ef077b4b3ec1bacf51bf27ab543f172a92a3 Mon Sep 17 00:00:00 2001 From: Zoltan Hawryluk Date: Mon, 27 Jan 2025 13:48:57 -0500 Subject: [PATCH 1/2] Changed meta information for the PDF generation page. --- templates/data/meta-info.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/templates/data/meta-info.json b/templates/data/meta-info.json index 2c469e75..98498c81 100644 --- a/templates/data/meta-info.json +++ b/templates/data/meta-info.json @@ -705,7 +705,7 @@ }, "accessible-pdf-generation.php": { "sectionPages": [ { "content": "Static Content" }], - "title": "Generating Accessible PDFs", - "desc": "Step-by-step guide to generate accessible PDFs with Open HTML to PDF and SpringBoot." + "title": "Converting Accessible PDFs from HTML", + "desc": "Many websites generate PDFs dynamically, like invoices, that look nice but are not accessible. This page is a step-by-step guide on how to generate accessible PDFs with Open HTML to PDF and SpringBoot." } } From 236bb4c217be30f037dea47114c5de41f3571e97 Mon Sep 17 00:00:00 2001 From: Zoltan Hawryluk Date: Mon, 27 Jan 2025 16:18:58 -0500 Subject: [PATCH 2/2] Updated copy. --- content/body/accessible-pdf-generation.php | 41 +++++++++++++++++----- content/head/accessible-pdf-generation.php | 1 + css/definition-term.css | 3 ++ less/definition-term.less | 3 ++ 4 files changed, 40 insertions(+), 8 deletions(-) create mode 100644 content/head/accessible-pdf-generation.php diff --git a/content/body/accessible-pdf-generation.php b/content/body/accessible-pdf-generation.php index 0a2ce852..c44c2c9c 100644 --- a/content/body/accessible-pdf-generation.php +++ b/content/body/accessible-pdf-generation.php @@ -324,13 +324,38 @@ function saveByteArray(reportName, byte) {

Feedback from a Screen Reader User

-

Vishnu Ramchandani, an experienced screen reader user, was kind enough to help us test the PDFs that we generated with Open HTML to PDF. He confirmed that he was able to read the information in the generated PDFs, but added some UX feedback to see if we can incorporate them in our PDF reports. Here is his feedback, along with what actions we took.

+

Vishnu Ramchandani, an experienced screen reader user, was kind enough to help us test the PDFs that we generated with Open HTML to PDF. Vishnu confirmed that the generated PDFs were accessible for screen reader users but provided valuable UX feedback to improve the user experience. Below is his feedback and the actions we took to address the issues:

+
    -
  1. Page title: To ensure consistency and clarity, the document title and the filename should both be same and should be meaningful. -
    • We remedied this issue by changing the title to be the same as the filename. This is definitely something you should think about when implenting your own solution, since it is not default behavior for the library.
    2. -
  2. Reading behavior of lengthy paragraphs in tables: Screen reader users experience line breaks when reading lengthy paragraphs in table columns using arrow keys. A paragraph is read in a broken manner, making it hard to follow. It is best to ensure that lengthy paragraphs are presented in a linear, single-column format when possible. This helps screen readers read the content in a logical order without breaking lines. -
    • Unfortunately, this seems to be a limitation of PDF technology. We recommend keeping lines short in table rows to remedy this situation. If you know of any other work arounds for this, please contact us with the details and we'll update our recommendations here.
    3. -
  3. Issue with Splitting URLs/Links: A single URL or link splits into multiple lines, making screen reader users think there are multiple links instead of a single one. To prevent links from splitting across multiple lines, consider the following approaches: Use non-breaking spaces ( ) between words in the link text to prevent line breaks. Apply CSS to ensure the link text does not break into multiple lines. For example, using white-space: nowrap; can help keep the link text on a single line. -
    • This also seems like a limitation in PDFs, as many PDF authoring tools like InDesign seem to have this multiline link issue as well. We recommend keeping link labels short (while still having appropriate and descriptive link text). Again, if you know of any other workarounds for this, email us. We'd love to hear from you.
    4. +
  4. Page Title Consistency +
    +
    Feedback:
    +
    The document title and filename should be consistent and meaningful to ensure clarity for users.
    +
    Action Taken:
    +
    We updated the title of the PDF to match the filename. This adjustment improves consistency and makes the document more user-friendly. When implementing your own solution, remember that this is not a default behavior in the Open HTML to PDF library and should be explicitly configured.
    +
    +
    5. +
  5. Reading Behavior of Lengthy Paragraphs in Tables + +
    +
    Feedback:
    +
    Screen readers encounter issues when lengthy paragraphs within table columns are broken into lines. This disrupts the reading flow, making it difficult for users to follow the content. To address this, lengthy paragraphs should ideally be displayed in a linear, single-column format.
    +
    Action Taken:
    +
    Unfortunately, this behavior seems to be a limitation of PDF technology. While we cannot fully resolve this issue, we recommend keeping table row text concise and avoiding lengthy paragraphs. If you are aware of any workaround to mitigate this issue, please share your insights with us, and we will update our recommendations accordingly.
    +
    +
    6. +
  6. Issues with Splitting URLs and Links + +
    +
    Feedback:
    +
    When URLs or links break across multiple lines in the PDF, screen readers interpret them as multiple links, leading to confusion. To prevent this: +
      +
    1. Use non-breaking spaces ( ) in link text to avoid line breaks.
      2. +
    2. Apply CSS styles such as white-space: nowrap; to keep links on a single line.
      3. +
    +
    +
    Action Taken:
    +
    This issue also appears to be a limitation inherent to PDF technology, as even advanced tools like Adobe InDesign exhibit this behavior. As a best practice, we recommend keeping link labels concise but descriptive to minimize splitting. If you have additional solutions or tools to address this, please reach out to us — we are eager to incorporate any new strategies.
    +
    +
- diff --git a/content/head/accessible-pdf-generation.php b/content/head/accessible-pdf-generation.php new file mode 100644 index 00000000..a4db5508 --- /dev/null +++ b/content/head/accessible-pdf-generation.php @@ -0,0 +1 @@ + diff --git a/css/definition-term.css b/css/definition-term.css index 39ab8d35..cde10186 100644 --- a/css/definition-term.css +++ b/css/definition-term.css @@ -39,4 +39,7 @@ dl [role="definition"]::after, display: block; height: 1rem; } +ol dl { + margin-top: 20px; +} /*# sourceMappingURL=definition-term.css.map */ \ No newline at end of file diff --git a/less/definition-term.less b/less/definition-term.less index a7fb7f80..f11d70dc 100755 --- a/less/definition-term.less +++ b/less/definition-term.less @@ -26,3 +26,6 @@ dl, } } } +ol dl { + margin-top: 20px; +} \ No newline at end of file