Disabling listening #3

khinsen commented 2026年02月12日 15:16:00 +01:00

de6ec05bf2

If I understand this patch correctly, it adds code to serve-hyperbooks that actually disables the whole function if environment variable HYPERDOC_DISABLE_LISTEN is set to one of four values that humans might interpret as "yes!". But:

1. The function serve-hyperbooks is a library function to be used in many contexts. Testing for environment variables makes sense only for a program intended to be run from a Unix shell. It's that program that should test for environment variables, not the library function (which might run on a system that doesn't even have environment variables).
2. Adding behavior to a function without also adapting the docstring creates confusion.
3. I don't see the point of configuring host via an environment variable either. In fact, I don't quite understand what the host argument to clog:initialize is intended for. In the current CLOG code, it is ignored.

https://codeberg.org/rgb/hyperdoc/commit/de6ec05bf2721640a83d1d0a3415b882b0353bc1 If I understand this patch correctly, it adds code to `serve-hyperbooks` that actually disables the whole function if environment variable `HYPERDOC_DISABLE_LISTEN` is set to one of four values that humans might interpret as "yes!". But: 1. The function `serve-hyperbooks` is a library function to be used in many contexts. Testing for environment variables makes sense only for a program intended to be run from a Unix shell. It's that program that should test for environment variables, not the library function (which might run on a system that doesn't even have environment variables). 2. Adding behavior to a function without also adapting the docstring creates confusion. 3. I don't see the point of configuring `host` via an environment variable either. In fact, I don't quite understand what the `host` argument to `clog:initialize` is intended for. In the current CLOG code, it is ignored.

khinsen commented 2026年02月12日 15:19:34 +01:00

f6557fc3e6

I did indeed forget to update the README - good catch!

But... "For sandboxed/CI environments where opening listening sockets is not permitted, set HYPERDOC_DISABLE_LISTEN=1 to run the same entry point without starting the network listener." The whole point of the command line given in this section of the README is to run a server. If that's not what you want to do... then don't do it!!!

https://codeberg.org/rgb/hyperdoc/commit/f6557fc3e69e560951c93d3e40014c997ee933e3 I did indeed forget to update the README - good catch! But... "For sandboxed/CI environments where opening listening sockets is not permitted, set `HYPERDOC_DISABLE_LISTEN=1` to run the same entry point without starting the network listener." The whole point of the command line given in this section of the README is to run a server. If that's not what you want to do... then don't do it!!!

khinsen commented 2026年02月12日 15:27:11 +01:00

8006d5d59d

"If your environment uses Quicklisp, load it before asdf:load-system, for example via an environment variable handled in an extra --eval."

For people using Quicklisp, this advice is not necessary. They would already have loaded HyperDoc using Quicklisp. For people not using Quicklisp, this advice is not necessary either. So...

Replacing (hyperbook/server:serve-catalog) by (uiop:symbol-call :hyperbook/server (quote #:serve-catalog)) is nothing but code obfuscation.

Calling asdf:initialize-source-registry is not something I'd recommend to anyone who is not a Lisp expert. It is necessary only for complex Lisp installations.

Calling asdf:load-asd is almost never a good idea. ASDF finds and loads .asd files on its own.

https://codeberg.org/rgb/hyperdoc/commit/8006d5d59d72ebeaeb32d56a9b836f0073e57974 "If your environment uses Quicklisp, load it before `asdf:load-system`, for example via an environment variable handled in an extra `--eval`." For people using Quicklisp, this advice is not necessary. They would already have loaded HyperDoc using Quicklisp. For people not using Quicklisp, this advice is not necessary either. So... Replacing `(hyperbook/server:serve-catalog)` by `(uiop:symbol-call :hyperbook/server (quote #:serve-catalog))` is nothing but code obfuscation. Calling `asdf:initialize-source-registry` is not something I'd recommend to anyone who is not a Lisp expert. It is necessary only for complex Lisp installations. Calling `asdf:load-asd` is almost never a good idea. ASDF finds and loads `.asd` files on its own.

rgb commented 2026年02月12日 19:01:14 +01:00

@khinsen wrote in #3 (comment):

I did indeed forget to update the README - good catch!

Thanks Konrad, see 0bb67e5f0c

@khinsen wrote in https://codeberg.org/rgb/hyperdoc/issues/3#issuecomment-10539486: > I did indeed forget to update the README - good catch! Thanks Konrad, see https://codeberg.org/rgb/hyperdoc/commit/0bb67e5f0c27199462709c15a75f55c187a47a5f