From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from esa4.mentor.iphmx.com (esa4.mentor.iphmx.com [68.232.137.252]) by sourceware.org (Postfix) with ESMTPS id 2163F3858D3C; Wed, 19 Oct 2022 16:30:27 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 2163F3858D3C Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com X-IronPort-AV: E=Sophos;i="5.95,196,1661846400"; d="scan'208";a="85046685" Received: from orw-gwy-02-in.mentorg.com ([192.94.38.167]) by esa4.mentor.iphmx.com with ESMTP; 19 Oct 2022 08:30:24 -0800 IronPort-SDR: cgxjjKdx2UAE9yGiYSZlY/AgqnUVUOzgQoXwv1eT70EmO4sq9+oTWyI0QHdckG/EbEFFey1+RX DFIl8C8t8qh5J1Xcha75vRCL26tXWzd//qKfNS+vx4+9CTU1Lnn/gC3zxvMw4ZQ53a09LcHV8T 76l6JwUP0TUYEO8meWWRlFCGyB6V7yKj7APyXOGptkdoL0nuDSipzxgIL4hZc8sVRF0qXyhv4X D8wIVD2lwA3RFBHFl5saifnD5McOBC/6sgdMaTu0dXNwJQhXqghZHo3ygUXQDYhwsDjqkcA2pE 9BI= Message-ID: <510eaf27-1b33-11fc-0315-dbf8e901430f@codesourcery.com> Date: Wed, 19 Oct 2022 10:30:18 -0600 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.11.0 Subject: Re: Announcement: Porting the Docs to Sphinx - 9. November 2022 Content-Language: en-US To: =?UTF-8?Q?Martin_Li=c5=a1ka?= , GCC Patches , GCC Development CC: "Joseph S. Myers" , Gerald Pfeifer References: <9975b774-46d7-8870-fd92-498f5ec50ab4@suse.cz> <9ea57a95-fefe-81a3-848e-ede0893f5b61@suse.cz> <8198573b-89e2-a232-3e33-0e5c4153c112@suse.cz> <5088118f-ae16-c746-2889-71ae6a4e2c3a@codesourcery.com> From: Sandra Loosemore In-Reply-To: Content-Type: text/plain; charset="UTF-8"; format=flowed Content-Transfer-Encoding: 8bit X-ClientProxiedBy: svr-orw-mbx-15.mgc.mentorg.com (147.34.90.215) To svr-orw-mbx-13.mgc.mentorg.com (147.34.90.213) X-Spam-Status: No, score=-3.7 required=5.0 tests=BAYES_00,HEADER_FROM_DIFFERENT_DOMAINS,KAM_DMARC_STATUS,KAM_EU,NICE_REPLY_A,SPF_HELO_PASS,SPF_PASS,TXREP autolearn=no autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: 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