Re: Lua 5.4.0 manual

[Francisco Olarte <folarte@...>]

Lorenzo:

On Sat, Jul 11, 2020 at 10:50 PM Lorenzo Donati
<lorenzodonatibz@tiscali.it> wrote:
...
> >> Moreover, correctly typeset PDF documents are easier to read and they
> >> are less eye-straining.
> > This depends a bit on fonts and hardware. While (good) HTML pages
> > typically use screen-optimized fonts and layouts PDFs sometimes use
...
> The big problem here is not just the fonts. Web pages which are
> carefully designed for optimum reading usually don't contain a lot of
> text (i.e compared to an average scientific paper, technical review or
> let alone a book).
>
> Whereas, most text-filled web pages are not a creation of a good web
> designer, but a text-dump with a few formatting. There's usually little
> layout and CSS is rarely used to constrain it for optimum viewing.

Fonts give problems. Let's take as example the ( excellent work )PDF
which more or less started this,
https://zeitkraut.com/docs/lua-5.4-manual.pdf posted by Albert
Krewinkle and compare it with it HTML counterpart
https://www.lua.org/manual/5.4/manual.html., ignoring the function
index at https://www.lua.org/manual/5.4/ for a nicer conversation.

With the PDF version I can have the TOC open in the sidebar, or
whatever your reader has, and it's got a clickable TOC built in, which
is a definite plus. TOC is, IMNSHO, worse than the html index page
because I cannot discover it is clickable until I hover on it (
suspecting that I specifically did it before writing this ). I much
prefer the HTML style of the TOC because it is clearly marked where I
can click ( and it also has a function index, but that's cheating ).

PDF is certainly faster, no doubt there.

On my screen 25 of the 37 cm of text ( y did tape measure that ) are
useful text ( on page 136, to be exact ). OTOH the HTML version
manages to use all my screen real estate.

PDF is using a times variant for text, courier for code. Using page
zoom, 37cm, about 125% physical size of an A4, I can read it, but it's
not that comfortable. I blame this on the times font, at zoom levels
of 80% physical the layout is nice, but font is not well rendered,
readable but not comfortable ( I'm on a 4k monitor ). At the 125% zoom
where fonts begin to be well rendered, layout is bit ugly. I've worked
a bit on the printing business, not much, and I've read a lot, and IMO
times fonts still do not cut it for screens, they are designed to have
300 dpi resolution minimum, so they can be clearly rendered at small
sizes. And also, due to how paper and screens differ, I've always
found they look much better on the paper.

OTOH the HTML uses nearly all the vertical screen real estate, and is
using some variant of helvetica, I suspect one of the screen optimized
ones, which reads much better, among other things because at high text
density sans serif read better and probably because it's a
constant-width-stroke font.

Disclaimer: I really like the lua manual page, I would say it is one
of the main reasons for me starting using Lua.

> So, in my experience, documents that in PDF format would take several
> pages (let's say more than 4 pages, A4 format, about 70 rows per page,
> 10pt to 12pt font, one or two columns), tend to be much more readable
> when in PDF form. I rarely see such documents rendered as a good,
> readable web-page.

Problem is you normally do not see both, but when a proper style is
used, as in the lua doc, web pages can, IMO, be made much better to
read ON SCREEN than PDFs, among other things because HTML is designed
for screen and PS for paper.

...

> I'm also not so young (50yo) and my sight's not really the best, but I
> enjoy reading PDFs both on PC screens and on tablets. On these latter
> devices, most text-crammed web pages tend to look ugly and poorly designed.

Yes. I normally do not use anything thinner than a laptop screen, but
unless a lot of care is taken html needs good browsers and minimal
screen width.

> I think the main issue is that usually people that bother to write long
> documents tend to create a well laid-out PDFs, whereas not the same care
> is given to analogous text-filled web pages.

Yep. Normally good pages are made from something like asciidoc,
markdown, some simple input format and then just rendered to whatever
format you need. It also depends on the kind of content, lua manual
and similar things are easy to format, some others are a pain.

> Moreover, nowadays PDFs are often laid-out in a format that is suitable
> for on-screen reading (and still looks good if printed).

Well, my reader can zoom to content and jump by page, but you still
notice the content is laid out for paper.

> I guess making a good looking text-filled web page that gives the same
> high-quality user-experience regardless of the user hardware/software
> setup requires quite a lot of CSS wizardry.

Normally it needs a few well chosen things, minimal. The problem I
normally encounter is CSS abuse, too much effects. Just peek a couple
of fonts and let the renderer do its stuff. If you look at the lua
manual it renders well and fast because, among other things, it has a
simple css and not too much markup.

> But these are only guesses, as I said, to explain what's my long
> experience with technical documents in electronic form.

I've generally found PDF tends to have a minimal standard higher than
html, but you occasionally find things like Lua, or say, postgres,
which are well designed for the web, and this are normally easier to
read.

FOS