From: Sandra Loosemore <sandra@codesourcery.com>
To: "Martin Liška" <mliska@suse.cz>,
"GCC Patches" <gcc-patches@gcc.gnu.org>,
"GCC Development" <gcc@gcc.gnu.org>
Cc: "Joseph S. Myers" <joseph@codesourcery.com>,
Gerald Pfeifer <gerald@pfeifer.com>
Subject: Re: Announcement: Porting the Docs to Sphinx - 9. November 2022
Date: Wed, 19 Oct 2022 10:30:18 -0600 [thread overview]
Message-ID: <510eaf27-1b33-11fc-0315-dbf8e901430f@codesourcery.com> (raw)
In-Reply-To: <a78fc235-9d79-5391-9590-cad62712962d@suse.cz>
On 10/19/22 05:09, Martin Liška wrote:
> On 10/18/22 00:26, Sandra Loosemore wrote:
>> On 10/17/22 07:28, Martin Liška wrote:
>>> Hello.
>>>
>>> Based on the very positive feedback I was given at the Cauldron Sphinx Documentation BoF,
>>> I'm planning migrating the documentation on 9th November. There are still some minor comments
>>> from Sandra when it comes to the PDF output, but we can address that once the conversion is done.
>>
>> My main complaint about the PDF is that the blue color used for link text is so light it interferes with readability. Few people are going to print the document on paper any more, but I did try printing a sample page on a grayscale printer and the blue link text came out so faint that it was barely visible at all.
>
> Sure, I've just added support for monochromatic PDF output where one needs to use
> MONOCHROMATIC=1 make latexpdf ...
>
> and I linked the file here:
> https://splichal.eu/scripts/sphinx/gcc/_build/latexmonochromatic/gcc.pdf
>
> right now I build only one PDF in this mode and it's mentioned here:
> https://splichal.eu/scripts/sphinx/
>
> What do you think about it now?
Hmmm, removing *all* visual cues that something is a link does not seem
so great either, especially since the new format has changed the link
text for @xref to remove the page and section information. E.g. we used
to get "See Section 3.4 [Options Controlling C Dialect], page 44." and
now it just reads "See Options Controlling C Dialect."
I realize there is a can of worms here involving philosophical issues
about whether the PDF manual is intended to be formatted for reading as
a book or is just a handy way to repackage the hyperlinked web
presentation for offline reference. Also there is another can of worms
involving making the documentation accessible to people who have visual
disabilities, specifically color blindness issues. Just speaking for
myself, I'd be happy if the PDF just used a darker blue color for links
that is both distinguishing and higher contrast with the background than
the current light blue, but I think it is one of the principles of
accessible design that color really shouldn't be the *only* indication
of something that initiates an action. Maybe underlining, or a little
link glyph, or restoring the section/page info to the link text?
>
>> An E-ink reader device would probably have similar problems.
>
> There ePUB would be likely better output format. What do you think?
Ooof, a lot of problems there. I looked at your new generated .epub in
both the "ebook-viewer" utility on my laptop and on my Kobo Forma. The
Kobo uses the default proportionally-spaced font for everything; even
the code examples fail to come out in a fixed-width font. ebook-viewer
shows fixed-width fonts for code examples and inline references to e.g.
command line options, but the names of options in the option tables
sections are in the proportional body font. Also in both viewers I see
hyperlinks to https://splicha.eu/... in place of internal links in some
references to command-line options and the like, and the formatting of
the option summary tables really sucks, with lines breaking at hyphens
in the middle of option names.
I suggest we try to focus our efforts on the currently-supported formats
before adding EPUB as a new format.
-Sandra
next prev parent reply other threads:[~2022-10-19 16:30 UTC|newest]
Thread overview: 42+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-01-31 14:06 Porting the Docs to Sphinx - project status Martin Liška
2022-02-04 13:40 ` Matthias Klose
2022-03-08 15:59 ` Martin Liška
2022-08-02 12:48 ` Martin Liška
2022-10-17 13:28 ` Announcement: Porting the Docs to Sphinx - 9. November 2022 Martin Liška
2022-10-17 14:16 ` Paul Iannetta
2022-10-19 7:24 ` Martin Liška
2022-10-19 8:13 ` Paul Iannetta
2022-10-19 9:22 ` Martin Liška
2022-10-19 16:42 ` Joseph Myers
2022-10-20 11:13 ` Martin Liška
2022-10-17 22:26 ` Sandra Loosemore
2022-10-19 11:09 ` Martin Liška
2022-10-19 12:45 ` Martin Liška
2022-10-19 16:30 ` Sandra Loosemore [this message]
2022-10-20 11:26 ` Martin Liška
2022-10-20 2:26 ` Xi Ruoyao
2022-10-20 11:27 ` Martin Liška
2022-10-20 11:49 ` Xi Ruoyao
2022-10-20 11:53 ` Martin Liška
2022-10-20 11:55 ` Xi Ruoyao
2022-10-20 12:26 ` Martin Liška
2022-10-20 15:35 ` Joseph Myers
2022-10-20 15:50 ` Martin Liška
2022-10-20 16:43 ` Joseph Myers
2022-10-20 16:47 ` Jakub Jelinek
2022-11-08 13:55 ` Announcement: Porting the Docs to Sphinx - tomorrow Martin Liška
2022-11-08 18:44 ` Sam James
2022-11-09 0:00 ` Joseph Myers
2022-11-09 0:06 ` Sam James
2022-11-09 7:49 ` Richard Biener
2022-11-09 10:18 ` Mark Wielaard
2022-11-09 17:11 ` Joseph Myers
2022-11-09 17:16 ` Richard Biener
2022-11-11 20:52 ` Gerald Pfeifer
2022-11-11 21:10 ` Sandra Loosemore
2022-11-13 15:44 ` Martin Liška
2022-11-09 14:45 ` Announcement: Porting the Docs to Sphinx - 9. November 2022 Martin Liška
2022-11-09 17:14 ` Joseph Myers
2022-11-10 13:05 ` Martin Liška
2022-11-10 13:50 ` Richard Biener
2022-11-11 23:05 ` David Malcolm
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=510eaf27-1b33-11fc-0315-dbf8e901430f@codesourcery.com \
--to=sandra@codesourcery.com \
--cc=gcc-patches@gcc.gnu.org \
--cc=gcc@gcc.gnu.org \
--cc=gerald@pfeifer.com \
--cc=joseph@codesourcery.com \
--cc=mliska@suse.cz \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).