Lua 5.4.0 manual

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

Lua 5.4.0 manual

TonyMc
Hi,

many thanks for Lua 5.4.0!

Will there be a PDF version of the reference manual for this version?  I
find a PDF easier to read than a web page.

Best, Tony

Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Luiz Henrique de Figueiredo
> Will there be a PDF version of the reference manual for this version?  I
> find a PDF easier to read than a web page.

If you mean, typeset as a book, then no.
We only did that for Lua 5.1, wayback in 2006.
Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Albert Krewinkel
In reply to this post by TonyMc

TonyMc writes:

> Will there be a PDF version of the reference manual for this version?  I
> find a PDF easier to read than a web page.

With pandoc and LaTeX installed, you can do

    pandoc --pdf-engine=xelatex -o lua5.4.pdf https://lua.org/manual/5.4/manual.html

--
Albert Krewinkel
GPG: 8eed e3e2 e8c5 6f18 81fe  e836 388d c0b2 1f63 1124
Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Gisle Vanem
Albert Krewinkel wrote:

> With pandoc and LaTeX installed, you can do
>
>      pandoc --pdf-engine=xelatex -o lua5.4.pdf https://lua.org/manual/5.4/manual.html

I'm getting:
   pandoc: unrecognized option `--pdf-engine=xelatex'

Maybe you mean:
   pandoc --latex-engine=xelatex -o lua5.4.pdf https://lua.org/manual/5.4/manual.html

But this ends in:
   ! Missing number, treated as zero.
   <to be read again>
                      \protect
   l.2557 ...ter}\rule{0.5\linewidth}{\linethickness}

What Pandoc do you have?

--
--gv
Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Albert Krewinkel

Gisle Vanem writes:

> Albert Krewinkel wrote:
>
>> With pandoc and LaTeX installed, you can do
>>
>>      pandoc --pdf-engine=xelatex -o lua5.4.pdf https://lua.org/manual/5.4/manual.html
>
> I'm getting:
>   pandoc: unrecognized option `--pdf-engine=xelatex'
>
> Maybe you mean:
>   pandoc --latex-engine=xelatex -o lua5.4.pdf https://lua.org/manual/5.4/manual.html
>
> But this ends in:
>   ! Missing number, treated as zero.
>   <to be read again>
>                      \protect
>   l.2557 ...ter}\rule{0.5\linewidth}{\linethickness}
>
> What Pandoc do you have?

I'm using the latest version (pandoc 2.10). `--latex-engine` was the
name of the `--pdf-engine` option in pandoc 1.* (support for other,
non-LaTeX, pdf engines was added in version 2.0, such as the HTML based
WeasyPrint and wkhtmltopdf engines).

There are also docker images, which might be simpler in some cases. But
the command is a mouthful:

    docker run --rm -v "$PWD":/data -u $(id -u) pandoc/latex \
        --pdf-engine=xelatex -o lua5.4.pdf \
        https://lua.org/manual/5.4/manual.html

BTW, pandoc allows document modifications via Lua:
<https://pandoc.org/lua-filters.html>


--
Albert Krewinkel
GPG: 8eed e3e2 e8c5 6f18 81fe  e836 388d c0b2 1f63 1124
Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Alexander Walz
In reply to this post by TonyMc
Hello,

I agree to Tony.

Alex, Rhineland.

TonyMc wrote:

> Hi,
>
> many thanks for Lua 5.4.0!
>
> Will there be a PDF version of the reference manual for this version?  I
> find a PDF easier to read than a web page.
>
> Best, Tony
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Jairo A. del Rio
The following gives a nice result too, provided a TeX Live distribution is installed:

pandoc --pdf-engine=context -o lua5.4.pdf https://lua.org/manual/5.4/manual.html

Incidentally, ConTeXt, based on TeX, uses Lua as an scripting language.

Regards,

Jairo

El vie., 10 de jul. de 2020 a la(s) 16:19, Alexander Walz ([hidden email]) escribió:
Hello,

I agree to Tony.

Alex, Rhineland.

TonyMc wrote:
> Hi,
>
> many thanks for Lua 5.4.0!
>
> Will there be a PDF version of the reference manual for this version?  I
> find a PDF easier to read than a web page.
>
> Best, Tony
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Paul E. Merrell, J.D.
On Fri, Jul 10, 2020 at 7:57 PM Jairo A. del Rio
<[hidden email]> wrote:

> Incidentally, ConTeXt, based on TeX, uses Lua as an scripting language.

Yes. See <https://wiki.contextgarden.net/Programming_in_LuaTeX>

Best regards,

Paul

--
[Notice not included in the above original message:  The U.S. National
Security Agency neither confirms nor denies that it intercepted this
message.]
                                                ¯\_(ツ)_/¯
Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Albert Krewinkel
In reply to this post by Albert Krewinkel
For a cleaned-up version which comes with a table of contents, see
https://zeitkraut.com/docs/lua-5.4-manual.pdf and
https://zeitkraut.com/docs/lua-5.4-manual.epub (ePUB 3).

The code used to produce these is here:
https://gist.github.com/tarleb/c34c396b21208b91164a8722b7aca2c2

Cheers,
Albert

Albert Krewinkel writes:

> Gisle Vanem writes:
>
>> Albert Krewinkel wrote:
>>
>>> With pandoc and LaTeX installed, you can do
>>>
>>>      pandoc --pdf-engine=xelatex -o lua5.4.pdf https://lua.org/manual/5.4/manual.html
>>
>> I'm getting:
>>   pandoc: unrecognized option `--pdf-engine=xelatex'
>>
>> Maybe you mean:
>>   pandoc --latex-engine=xelatex -o lua5.4.pdf https://lua.org/manual/5.4/manual.html
>>
>> But this ends in:
>>   ! Missing number, treated as zero.
>>   <to be read again>
>>                      \protect
>>   l.2557 ...ter}\rule{0.5\linewidth}{\linethickness}
>>
>> What Pandoc do you have?
>
> I'm using the latest version (pandoc 2.10). `--latex-engine` was the
> name of the `--pdf-engine` option in pandoc 1.* (support for other,
> non-LaTeX, pdf engines was added in version 2.0, such as the HTML based
> WeasyPrint and wkhtmltopdf engines).
>
> There are also docker images, which might be simpler in some cases. But
> the command is a mouthful:
>
>     docker run --rm -v "$PWD":/data -u $(id -u) pandoc/latex \
>         --pdf-engine=xelatex -o lua5.4.pdf \
>         https://lua.org/manual/5.4/manual.html
>
> BTW, pandoc allows document modifications via Lua:
> <https://pandoc.org/lua-filters.html>


--
Albert Krewinkel
GPG: 8eed e3e2 e8c5 6f18 81fe  e836 388d c0b2 1f63 1124
Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Lorenzo Donati-3
In reply to this post by TonyMc
On 10/07/2020 19:06, TonyMc wrote:

> Hi,
>
> many thanks for Lua 5.4.0!
>
> Will there be a PDF version of the reference manual for this version?  I
> find a PDF easier to read than a web page.
>
> Best, Tony
>
>

I also prefer PDF documentation. Nowadays ever more, since Web browsers
are big juggernauts who take forever do display a page with all that
HTML5 stuff.

I don't really care whether the PDF is laid out for actual printing or
not. I'm almost not printing anything these days. The viewing format is
just better for reading when there are no multimedia stuff embedded in
the doc, but just text+images.

With PDF you have some distinct advantages, IMO.

There are very lightweight readers which can open a doc in a breeze (I
use SumatraPDF on Windows, for example). If I already have one instance
of SumatraPDF open, opening another is almost instantaneous (on an old
i5 Windows 7 64 bit machine), even if there are dozens of docs already
open. And even if it's the first time you fire up SumatraPDF, it takes a
fraction of a second if the machine is not too loaded.

OTOH, if I have Firefox open (with the usual mess of dozen of tabs
already there) opening even a very simple page like Lua refman's it
takes at least a couple of seconds. More if the other tabs are busy
doing something. Moreover, if Firefox has not been started yet, it takes
many seconds to display the page (i.e. forever when there are cached
tabs that have to be reloaded). This is quite annoying.

Another advantage of PDFs is searchability. Especially compared with
HTML docs split on several linked pages. Not only all the information is
there, so you can fire up the search dialog and do a single scan, but
the fixed layout helps your brain to remember where some information is
placed, like a paper book. If you use a document for long enough you end
up remembering where some info is, and it's simple to use scrollbars to
get there (like you were rapidly sifting through the pages of a real book).

With web pages usually you don't have such advantage, since the layout
of the "screen pages" heavily depends on the zoom factor, window size
and other settings of the browser.

Still another advantage, especially with lightweight readers, is that
you can easily fit different windows with different docs side by side,
because these readers have a very simple GUI.

Sometimes I have a 20-30 small PDF open (typically electronic components
datasheet and application notes) plus a couple big PDF docs, and
everything runs smooth and manageable through the OS GUI.

Try that with a browser! It's a nightmare getting UI elements out of the
way when trying to fit two windows side by side. If you need a third,
just get another monitor! Otherwise you may need to have different
setups for when you use your browser for local docs browsing and another
for when you surf the web. This is largely impractical, if not
impossible with some browsers. Especially if you want to do both
activities at the same time.

The fact is that nowadays browsers are not meant to share space on the
desktop with any other windows any longer. They are meant to be the
/ultimate and sole/ UI to the whole world (even more with all that cloud
BS). They are not meant to be used as "text document" readers anymore
because most people just don't read "plain text" anymore. And browsers
development is mostly mass-market driven.

Moreover, correctly typeset PDF documents are easier to read and they
are less eye-straining. This for me is quite important when reading
dozens of pages or scanning trough a big book-like doc. As TeX/LaTeX
people know, typesetting practices have evolved in centuries to make the
text reading process efficient and the least tiring as possible.
Web pages are almost always not built that way. Although Lua's refman is
exceptionally good for an HTML-based text document.

So, all in all, when given the choice, I always download PDF docs for
anything. I think there is a reason why many vendors and projects still
make PDFs available for their products (e.g. GCC, gnu-make,
semiconductor vendors etc.), instead of providing just a bunch of HTML
pages.

I would really appreciate if Lua refman were provided also as a PDF file.

My 2 EUROCENT. :-)


-- Lorenzo

Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Francisco Olarte
Lorenzo:

On Sat, Jul 11, 2020 at 12:50 PM Lorenzo Donati
<[hidden email]> 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
paper optimized ones. Fine if you have a medium-big HiDPI monitor, a
PiTA (i.e., the one IO'm using now, 31.5", 4K, that should be...
3840/(31.5*16/sqrt(16^2+9^2)) = 139.867 dpi
and change, and a full page fits nicely in vertical, but the other one
I  use, 24" 1920*1280, is
1920/(24*16/sqrt(16^2+10^2)) = 94.339 dpi
if my math is right. As I'm getting old, and even having glasses
especifically made for working with the computer ( a little farther
than reading glasses ), in many PDF documents I have to choose between
cutting the page OR  having eye strain due to small printer fonts.

Francisco Olarte.
Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Lorenzo Donati-3
On 11/07/2020 13:13, Francisco Olarte wrote:

> Lorenzo:
>
> On Sat, Jul 11, 2020 at 12:50 PM Lorenzo Donati
> <[hidden email]> 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
> paper optimized ones. Fine if you have a medium-big HiDPI monitor, a
> PiTA (i.e., the one IO'm using now, 31.5", 4K, that should be...
> 3840/(31.5*16/sqrt(16^2+9^2)) = 139.867 dpi
> and change, and a full page fits nicely in vertical, but the other one
> I  use, 24" 1920*1280, is
> 1920/(24*16/sqrt(16^2+10^2)) = 94.339 dpi
> if my math is right. As I'm getting old, and even having glasses
> especifically made for working with the computer ( a little farther
> than reading glasses ), in many PDF documents I have to choose between
> cutting the page OR  having eye strain due to small printer fonts.
>
> Francisco Olarte.
>

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.

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.

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.

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.

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


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.

OTOH, maybe, technical writers are more accustomed to create good
layouts using WYSYWIG word processors or maybe TeX/LaTeX.

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

Cheers!

-- Lorenzo


Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Francisco Olarte
Lorenzo:

On Sat, Jul 11, 2020 at 10:50 PM Lorenzo Donati
<[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Paul E. Merrell, J.D.
On Sun, Jul 12, 2020 at 3:25 AM Francisco Olarte <[hidden email]> wrote:
> PDF is using a times variant for text, courier for code.

From one who was a typographer for 20+ years before a career change,
then retirement:

Your issues with the fonts are real. Times variants are all designed
for newspaper use in narrow columns. They look horrible in longer
measure columns. Courier (a typewriter font) has not been widely
available since the onset of the daisy-wheel printer. You're
undoubtedly looking at something like Courier New, which was
introduced at that time. The original Courier was quite a bit bolder
than Courier New. The thinner replacement was necessary because
daisy-wheel printers could not supply sufficient impact to print the
bolder original Courier crisply.

Courier New is a font that should have died when the daisy-wheel
printer did, but survives largely because Microsoft wooden-headedly
persists in shipping it with Windows. And people without a
typographical eye persist in using both CG Times and Courier New
inappropriately.

There are fonts that are versatile enough to be used in a wide variety
of situations, e.g., for a serif font, GeoSlab Medium BT.
<https://www.download-free-fonts.com/details/86286/geometric-slabserif-703-medium-bt>.
But until such time as Microsoft decides to ship one of them, we'll
undoubtedly have to view an overwhelmingly  inappropriate use of
typefaces.

Best regards,

Paul
--
[Notice not included in the above original message:  The U.S. National
Security Agency neither confirms nor denies that it intercepted this
message.]
                                                ¯\_(ツ)_/¯
Reply | Threaded
Open this post in threaded view
|

Re: Lua 5.4.0 manual

Ericson Carlos
In reply to this post by Lorenzo Donati-3
On Sat, Jul 11, 2020 at 6:50 PM Lorenzo Donati <[hidden email]> wrote:
OTOH, if I have Firefox open (with the usual mess of dozen of tabs
already there) opening even a very simple page like Lua refman's it
takes at least a couple of seconds. More if the other tabs are busy
doing something. Moreover, if Firefox has not been started yet, it takes
many seconds to display the page (i.e. forever when there are cached
tabs that have to be reloaded). This is quite annoying.

...

This is why I keep an old version of Opera (9.0.1) running on my PC all the time. It eats miniscule (by today's standards) amount of RAM with several tabs open. I use it as a document reader for HTML manuals.

I've modified the Lua HTML refman to have two frames: TOC on the left.
Works well for me.