Improvements to Emacs documentation accessibility

Improvements to Emacs documentation accessibility

[John Haman]

I noticed while browsing the Emacs manuals on my mobile phone that the 
accessibility is very poor. The text is very small which makes it hard 
to read without zooming and scrolling.

The layout of the texinfo html is classic, but would the community would 
be open to making the docs more readable on small devices? (like mobile 
phones and tablets)

I'm not a web developer, but I believe the solution would involve some 
improvements to the CSS of the documentation to add word-wrapping and 
maybe increase the font size.

I'm happy to help.

-John

Re: Improvements to Emacs documentation accessibility

[Po Lu]

John Haman <mail@johnhaman.org> writes:

> I noticed while browsing the Emacs manuals on my mobile phone that the
> accessibility is very poor. The text is very small which makes it hard
> to read without zooming and scrolling.
>
> The layout of the texinfo html is classic, but would the community
> would be open to making the docs more readable on small devices? (like
> mobile phones and tablets)
>
> I'm not a web developer, but I believe the solution would involve some
> improvements to the CSS of the documentation to add word-wrapping and
> maybe increase the font size.
>
> I'm happy to help.

AFAIU that means you somehow landed on an outdated page, since the
latest ones have been generated to work well on mobile browsers as well.

At least that's the conclusion last bug report about this led to.  Feel
free to correct me if I'm wrong.

Re: Improvements to Emacs documentation accessibility

[John Haman]

[-- Attachment #1: Type: text/plain, Size: 1122 bytes --]

 > AFAIU that means you somehow landed on an outdated page

I don't think it is outdated. Attaching an image that shows an example.

To me, it does not look like a mobile website.

On 10/12/22 9:44 AM, Po Lu wrote:
> John Haman <mail@johnhaman.org> writes:
>
>> I noticed while browsing the Emacs manuals on my mobile phone that the
>> accessibility is very poor. The text is very small which makes it hard
>> to read without zooming and scrolling.
>>
>> The layout of the texinfo html is classic, but would the community
>> would be open to making the docs more readable on small devices? (like
>> mobile phones and tablets)
>>
>> I'm not a web developer, but I believe the solution would involve some
>> improvements to the CSS of the documentation to add word-wrapping and
>> maybe increase the font size.
>>
>> I'm happy to help.
> AFAIU that means you somehow landed on an outdated page, since the
> latest ones have been generated to work well on mobile browsers as well.
>
> At least that's the conclusion last bug report about this led to.  Feel
> free to correct me if I'm wrong.

-- 
Dr. John Haman
Bethesda, MD

[-- Attachment #2: Sequences Arrays Vectors (GNU Emacs Lisp Reference Manual).png --]
[-- Type: image/png, Size: 180186 bytes --]

Re: Improvements to Emacs documentation accessibility

[Philip Kaludercic]

[-- Attachment #1: Type: text/plain, Size: 1711 bytes --]

John Haman <mail@johnhaman.org> writes:

>> AFAIU that means you somehow landed on an outdated page
>
> I don't think it is outdated. Attaching an image that shows an example.
>
> To me, it does not look like a mobile website.

I just tried it out in Firefox using the "Responsive Design Mode" (that
allows you to preview how a page looks like on a mobile device).
Interestingly enough the page did at first appear just like in your
screenshot, but when I slightly resized the frame it did appear like a
regular "mobile site" (hopefully attached below).

The site is missing a viewport-meta tag which is regretfully necessary
for normal pages to behave like normal pages on mobile screens.  Adding
that ought to help, but that should be done by the texinfo/makeinfo
maintainers.

> On 10/12/22 9:44 AM, Po Lu wrote:
>> John Haman <mail@johnhaman.org> writes:
>>
>>> I noticed while browsing the Emacs manuals on my mobile phone that the
>>> accessibility is very poor. The text is very small which makes it hard
>>> to read without zooming and scrolling.
>>>
>>> The layout of the texinfo html is classic, but would the community
>>> would be open to making the docs more readable on small devices? (like
>>> mobile phones and tablets)
>>>
>>> I'm not a web developer, but I believe the solution would involve some
>>> improvements to the CSS of the documentation to add word-wrapping and
>>> maybe increase the font size.
>>>
>>> I'm happy to help.
>> AFAIU that means you somehow landed on an outdated page, since the
>> latest ones have been generated to work well on mobile browsers as well.
>>
>> At least that's the conclusion last bug report about this led to.  Feel
>> free to correct me if I'm wrong.


[-- Attachment #2: Type: image/png, Size: 249127 bytes --]

Re: Improvements to Emacs documentation accessibility

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: Po Lu <luangruo@yahoo.com>,  emacs-devel@gnu.org
> Date: Wed, 12 Oct 2022 17:17:21 +0000
> 
> The site is missing a viewport-meta tag which is regretfully necessary
> for normal pages to behave like normal pages on mobile screens.  Adding
> that ought to help, but that should be done by the texinfo/makeinfo
> maintainers.

Texinfo 6.8 already adds that tag.  As I wrote, the scripts we use to
adapt the HTML docs to the GNU Web site used to remove that tag, but
that was supposed to be fixed months ago.  In any case, this is our
problem, not Texinfo's.

Re: Improvements to Emacs documentation accessibility

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: Po Lu <luangruo@yahoo.com>,  emacs-devel@gnu.org
>> Date: Wed, 12 Oct 2022 17:17:21 +0000
>> 
>> The site is missing a viewport-meta tag which is regretfully necessary
>> for normal pages to behave like normal pages on mobile screens.  Adding
>> that ought to help, but that should be done by the texinfo/makeinfo
>> maintainers.
>
> Texinfo 6.8 already adds that tag.  As I wrote, the scripts we use to
> adapt the HTML docs to the GNU Web site used to remove that tag, but
> that was supposed to be fixed months ago.  In any case, this is our
> problem, not Texinfo's.

Even better then.  Do you know why the tag was removed?

Re: Improvements to Emacs documentation accessibility

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: mail@johnhaman.org,  luangruo@yahoo.com,  emacs-devel@gnu.org
> Date: Wed, 12 Oct 2022 18:20:33 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Philip Kaludercic <philipk@posteo.net>
> >> Cc: Po Lu <luangruo@yahoo.com>,  emacs-devel@gnu.org
> >> Date: Wed, 12 Oct 2022 17:17:21 +0000
> >> 
> >> The site is missing a viewport-meta tag which is regretfully necessary
> >> for normal pages to behave like normal pages on mobile screens.  Adding
> >> that ought to help, but that should be done by the texinfo/makeinfo
> >> maintainers.
> >
> > Texinfo 6.8 already adds that tag.  As I wrote, the scripts we use to
> > adapt the HTML docs to the GNU Web site used to remove that tag, but
> > that was supposed to be fixed months ago.  In any case, this is our
> > problem, not Texinfo's.
> 
> Even better then.  Do you know why the tag was removed?

Originally, inadvertently, by scripts that were written to handle
older Texinfo-produced HTML docs.  But when we found out about the
removal of viewport tag, we fixed that (AFAIR).  Which is why I'm
surprised it isn't there.

If worse comes to worst, we can add it manually.

Re: Improvements to Emacs documentation accessibility

[Eli Zaretskii]

> Date: Wed, 12 Oct 2022 08:37:56 -0400
> From: John Haman <mail@johnhaman.org>
> 
> I noticed while browsing the Emacs manuals on my mobile phone that the 
> accessibility is very poor. The text is very small which makes it hard 
> to read without zooming and scrolling.

AFAIU, the following is missing from the HTML manuals:

  <meta name="viewport" content="width=device-width, initial-scale=1" />

This is strange, since I think the previous version did include that
heading.  Texinfo does produce it, but AFAIR the script that edits the
HTML for the Web site was originally removing that line.  That should
have been fixed several months ago.

Stefan, can you please look into this?

Re: Improvements to Emacs documentation accessibility

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> AFAIU, the following is missing from the HTML manuals:
>
>   <meta name="viewport" content="width=device-width, initial-scale=1" />
>
> This is strange, since I think the previous version did include that
> heading.  Texinfo does produce it, but AFAIR the script that edits the
> HTML for the Web site was originally removing that line.  That should
> have been fixed several months ago.
>
> Stefan, can you please look into this?

This should now be fixed.

I had to regenerate the HTML files using the makeinfo version from
Debian testing/bookworm, instead of the one from stable/bullseye that I
used previously.

Re: Improvements to Emacs documentation accessibility

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Wed, 12 Oct 2022 20:31:41 -0700
> Cc: emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > AFAIU, the following is missing from the HTML manuals:
> >
> >   <meta name="viewport" content="width=device-width, initial-scale=1" />
> >
> > This is strange, since I think the previous version did include that
> > heading.  Texinfo does produce it, but AFAIR the script that edits the
> > HTML for the Web site was originally removing that line.  That should
> > have been fixed several months ago.
> >
> > Stefan, can you please look into this?
> 
> This should now be fixed.
> 
> I had to regenerate the HTML files using the makeinfo version from
> Debian testing/bookworm, instead of the one from stable/bullseye that I
> used previously.

Thanks.

I think the conclusion here is that we should use the latest released
Texinfo version when generating the manuals.  Maybe it's something to
be said in make-tarball.txt.  (I always build my own Texinfo from
sources on systems where I need to generate Emacs manuals, FWIW.  It's
not hard to build it.)

Re: Improvements to Emacs documentation accessibility

[Bastien]

Eli Zaretskii <eliz@gnu.org> writes:

> I think the conclusion here is that we should use the latest released
> Texinfo version when generating the manuals.

Thanks for catching this!

I've also updated the Org-mode manual and guide here:

https://orgmode.org/manual/
https://orgmode.org/guide/

-- 
 Bastien

Re: Improvements to Emacs documentation accessibility

[John Haman]

On 10/12/22 11:31 PM, Stefan Kangas wrote:
> This should now be fixed.

It is ! Thanks for acting quickly.

-- 
Dr. John Haman
Bethesda, MD