Announcement: Porting the Docs to Sphinx - 9. November 2022

[Sandra Loosemore]

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