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

[Martin Liška]

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?

>  An E-ink reader device would probably have similar problems.

There ePUB would be likely better output format. What do you think?

Martin

> 
> I'm generally not a fan of the other colors being used for formatting, either.  To me it seems like they all interfere with readability, plus in code samples it seems like random things get highlighted in random colors, instead of focusing on the thing the example is trying to demonstrate.
> 
> I've been preferring to use the PDF form of the GNU manuals because it is easier to search the whole document that way.  The search feature in the new web version doesn't quite cut it....  it gives you a list of web pages and then you have to do a second browser search within each page to find the reference.  So I hope we can continue to support the PDF as a canonical format and better tune it for easy readability, instead of assuming that most people will only care about the online web version.
> 
> -Sandra
> 
> 
> 
>