Justified Paragraphs with limited line length

[Topsii]

I find that Haddock produces way too long lines that are not easy to read. The fix for #405 still produces too long lines in my opinion.

Screenshots

 

I would prefer justified paragraphs with limited line width, which increase readability.

Screenshots

 

I have read that some people dislike so much unused white space. Further some function signatures could get too long and there may be other elements than text paragraphs such as images in the documentation. So, this could be a compromise:

Screenshots

 

Also for the screenshots I removed the 0.2em top and bottom padding of the cells in the instances table and I personally prefer it .

Screenshots

That is because most of the time I scroll instead of navigating via the table of contents. The instances list is expanded by default and can be huge for some classes such as Traversable. In base-4.12.0.0 the layout of the instances list did not take as much vertical space.

[gbaz]

When the new haddock design was proposed, the number one complaint was that there was too much white space and people liked their long lines. The compromise reached was to have a max-width, but have it be large. I understand this is not to everyone's taste. However, the current large max-width is very much a conscious choice, and there's no pleasing everyone. I would vote to keep things the way they are, because previous experience suggests far more people would be unhappy than happy with any change such as that proposed.

[Topsii]

I was not aware that this is controversial. I had searched issues and pull requests for 'width' before opening this issue and read some discussion on the new haddock design. The author of the new design @NunoAlexandre wrote in 2018

I tried 70vw but it left almost no space for the left column with the synopsis and table of contents, and the lines became too long to read. I am now on a 1280px screen, therefore the #content has 806px, which seems pretty fine to me. I guess most people will view these pages using a 1920px screen in full or split mode. When split, the viewport will have less than 1280px and it will make more use of the screen, meaning that in most cases the use of space is pretty good.

I am under the impression that he did not account for larger monitors such as the one I have now and he never intended for lines to be that long. The screenshots he posted had short readable lines.

In fact the motivation for the new design was

the current theme is unfriendly. I find it very hard to read content with such a wide #content, and spacing is not great either.

such that

decrease #content width to improve readability

is listed as a notable change.

I don't think someone with a 1280px monitor undertook the effort of implementing a new design because he was bothered by hard to read long lines and a compromise was reached that limited the max-width to 1450px?

Apparently the 'before' screenshot from @NunoAlexandre was not taken on his 1280px monitor because the resolution is 2560x1600. Rather it seems to be from some high dpi display because the font is many more pixels large. This is a good example why the paragraph width should be specified in em instead of the current specification in px and vw. Anyway here is a cutout from the status quo that the new design was supposed to improve: And this is how it looks for me today. As you can tell from the code blocks above, the lines are even longer for me today than what the author of the new design thought needed to be improved.

the number one complaint was that there was too much white space and people liked their long lines.

I read the relevant pull requests (#721, #782, #949) and I did not see anyone complaining about too much whitespace or arguing for long lines. The closest I could find was this

I will point out that your mobile example shows where there is too much negative space. The longest line has 42 characters (may be off by one or two), whereas from my understanding good practice is somewhere between 2-3 runs of the roman alphabet (26*2). The padding for the body text seems like wasted space to me, and hurts readability flow.

But this issue is not about mobile displays and 3 runs of the roman alphabet seems fine

If I have overlooked any complaints, can you link them? I wasn't able to find them.

I think there is a difference between being bothered by empty space and finding something hard to read. Nonetheless I agree that we should strive to utilize empty space. For example I'd like to have a table of links to modules from the same package below the table of contents.