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

[Sandra Loosemore]

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.  An E-ink reader device would 
probably have similar problems.

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