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

["Martin Liška" <mliska@suse.cz>]

On 10/19/22 18:30, Sandra Loosemore wrote:
> 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."
> 

Hey.

> 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?

I've just tweaked the monochrom. PDF where dark blue color is used for links. About the links, there are multiple PDF viewers (like Evince) which can do a preview if you hover
over a link. Plus a page number is showed in a toolbar.

What it comes to the philosophical issues of the monochrom. PDF, well, I would recommend discussing that with Sphinx upstream project. I bet
they must have other projects who's readers might request similar needs. Intention of my monochrom. PDF was to show that Sphinx PDF output
can be quite easily adjusted.

> 
>>
>>>    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.

Sure, let's leave it for now and keep it as a might-have thing for the future!

Appreciate the feedback,
Cheers,
Martin

> 
> I suggest we try to focus our efforts on the currently-supported formats before adding EPUB as a new format.
> 
> -Sandra