[Django] #35855: Add a disclaimer about PDF accessibility issues in docs

[Django]

#35855: Add a disclaimer about PDF accessibility issues in docs
-------------------------------------+-------------------------------------
Reporter: Thibaud Colas | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: 5.0 | Severity: Normal
Keywords: accessibility, | Triage Stage:
djangonaut space, pdf | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
In the Django docs, we have [https://docs.djangoproject.com/en/5.1/howto
/outputting-pdf/ How to create PDF files]. This page needs a disclaimer
explaining fundamental accessibility issues with PDFs as a format,
similarly to how other areas of the docs warn users against likely
performance and security issues.

For example, something along the lines of:

> Warning: There are known accessibility issues with PDF files. Consider
whether your use case could be achieved with a more accessible format, and
make sure to provide alternatives for users.
--
Ticket URL: <https://code.djangoproject.com/ticket/35855>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35855: Add a disclaimer about PDF accessibility issues in docs
-------------------------------------+-------------------------------------

Reporter: Thibaud Colas | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: accessibility, | Triage Stage:
djangonaut space, pdf | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* version: 5.0 => dev

Comment:

Thank you Thibaud, would you have a reference from a known site about how
PDF have accessibility issues? This is news to me and I would like to know
more.
--
Ticket URL: <https://code.djangoproject.com/ticket/35855#comment:1>

[Django]

#35855: Add a disclaimer about PDF accessibility issues in docs
-------------------------------------+-------------------------------------
Reporter: Thibaud Colas | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage:
djangonaut space, pdf | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Claude Paroz):

I'm not certain that it's our responsibility to educate users about format
accessibility. IMHO it's out of scope for the Django docs.
--
Ticket URL: <https://code.djangoproject.com/ticket/35855#comment:2>

[Django]

#35855: Add a disclaimer about PDF accessibility issues in docs
-------------------------------------+-------------------------------------
Reporter: Thibaud Colas | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage:
djangonaut space, pdf | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Sarah Boyce):

The link to the ReportLab docs has it's own [https://docs.reportlab.com
/pdf-accessibility/ page on accessibility], quite prominently in their
docs.
We could in our example do a couple of the things mentioned in that (like
set a title, language and tag the "Hello world") to draw more attention to
it.
We already have a note that ReportLab is not thread-safe. I think we could
have a note to encourage folks to follow the accessibility guidelines
--
Ticket URL: <https://code.djangoproject.com/ticket/35855#comment:3>

[Django]

#35855: Add a disclaimer about PDF accessibility issues in docs
-------------------------------------+-------------------------------------
Reporter: Thibaud Colas | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: accessibility, | Triage Stage:
djangonaut space, pdf | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Thibaud Colas):

I didn’t know about that page in the ReportLab docs! I’m baffled to read
their tagged PDF support is [https://docs.reportlab.com/pdf-
accessibility/#availability only available for paid users], not sure what
to make of that information. There’s no way a PDF with any kind of
formatting in it would be considered good enough for an organization that
has to follow accessibility standards.

@Natalia PDFs have accessibility issues like any other content, but
they’re even more prevalent because a lot of software out there requires
extra steps to produce accessible PDFs. The page shared by Sarah is a good
overview of things that are often missing and can be resolved (in
particular tagging). Additionally I would recommend reading:

- [https://en.wikipedia.org/wiki/PDF/UA PDF/UA], the standard for PDF
files’ accessibility. The first requirement "Complete tagging" is what’s
only available in the paid version of ReportLab (…).
- [https://gds.blog.gov.uk/2018/07/16/why-gov-uk-content-should-be-
published-in-html-and-not-pdf/ Why GOV.UK content should be published in
HTML and not PDF]. This is a good authoritative overview of fundamental
accessibility issues with the format (such as lack of responsive resizing
and reflow, lack of text resizing, and color theming).

@Claude we want Django sites to be accessible.That means the framework,
including docs, certainly should encourage good practices for
accessibility. As is the case for security, performance, etc. A warning
seems commensurate with the size of the footgun.
--
Ticket URL: <https://code.djangoproject.com/ticket/35855#comment:4>

[Django]

#35855: Add a disclaimer about PDF accessibility issues in docs
-------------------------------------+-------------------------------------
Reporter: Thibaud Colas | Owner: (none)

Type: | Status: closed

Cleanup/optimization |
Component: Documentation | Version: dev

Severity: Normal | Resolution: wontfix

Keywords: accessibility, | Triage Stage:
djangonaut space, pdf | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* resolution: => wontfix
* status: new => closed

Comment:

> I’m baffled to read their tagged PDF support is ​only available for paid
users, not sure what to make of that information. Without tags, there’s no

way a PDF with any kind of formatting in it would be considered good
enough for an organization that has to follow accessibility standards.

I agree this is concerning, perhaps we should recommend
[https://doc.courtbouillon.org/weasyprint/stable/ WeasyPrint]. This looks
like you format it in html and you opt to convert it to a pdf (with tags)

It looks like this How-to guide was added in 2005 - do we think this guide
needed at all? It uses a [https://docs.djangoproject.com/en/5.1/ref
/request-response/#fileresponse-objects FileResponse] maybe these docs are
already enough?
Perhaps this how-to, which relies on an external package (possibly
commercialized in the past 20 years), doesn't belong in the docs.

These are the options I see:
1. Remove this How-to
2. Move away from ReportLab
3. Add a warning to the docs
4. Do nothing

To decide a route forward, can you start a discussion on the
[https://forum.djangoproject.com/c/internals/5 forum] and get more input
from other folks? If there's a consensus for any of the options 1-3 please
come back here, link the discussion and reopen the ticket
--
Ticket URL: <https://code.djangoproject.com/ticket/35855#comment:5>

[Django]

#35855: Add a disclaimer about PDF accessibility issues in docs
-------------------------------------+-------------------------------------
Reporter: Thibaud Colas | Owner: (none)
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution: wontfix
Keywords: accessibility, | Triage Stage:
djangonaut space, pdf | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Claude Paroz):

Replying to [comment:4 Thibaud Colas]:

> @Claude we want Django sites to be accessible.That means the framework,
including docs, certainly should encourage good practices for
accessibility. As is the case for security, performance, etc. A warning
seems commensurate with the size of the footgun.

To be clear, I'm all for accessibility as far as Django itself is
concerned. But for me, the choice of a PDF output is not something we
should interfere with. We have to put limits in what we document, and for
me, this is out of scope (but legitimate by itself, of course).

And yes, I also find ReportLab limitations saddening, but this is related
to the business model of the company behind it. It's not a community-
driven project.
--
Ticket URL: <https://code.djangoproject.com/ticket/35855#comment:6>