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
