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
