Subject: Re: bug#68453: closed (Re: bug#68453: [PATCH] doc: Improve VNC Services section.)

From: Rostislav Svoboda <[email-masked]>
Date: Sat, 8 Feb 2025 15:38:31 +0100

Hello Maxim,

Thank you for reopening the issue.

> > I meant that at one place we have (display-number 10), and then about
> > 15 lines below, we have (display-number 5). That’s inconsistent!
> > The same applies to the port numbers: 5910 vs. 5905.
>
> Is it a problem to show the use of different ports between examples?  My
> intent was to showcase the relationship between the display number used
> and the corresponding port, without going through the gnarly details of
> 'man vncviewer'.

It's not a problem in the sense that "it won't work," but it is an
inconsistency.

Using different values makes the reader wonder: Why are they
different? It creates unnecessary cognitive load. It's like reading a
math paper where a variable is suddenly renamed for no clear reason -
it forces extra effort to check if the change matters or not.

Keeping the values consistent avoids this distraction and helps
readers focus on the actual concept.

------

Regarding the example:

Trivial, easy-to-read examples are, of course, preferred. However,
this principle becomes counterproductive if the example (for some
reason) doesn't work or leaves the reader confused.

Virtual Network Computing isn't trivial, and SSH tunneling even less
so. There's plenty of room for confusion, especially for users
unfamiliar with SSH tunneling. Someone unfamiliar with SSH tunneling
will likely ask: "Why is ssh here?". The surrounding description
provides no context.

Such a user might then spend over an hour trying to grasp SSH
tunneling, stumbling across various visual guides and memory aids
like:
  https://iximiuz.com/en/posts/ssh-tunnels/
  https://hackertarget.com/ssh-examples-tunnels/

My extension to the example addresses this issue. Here, using
different port numbers _has_ a purpose - it clarifies what is "local"
and what is "remote," helping the reader form a clear mental model.
See for yourself:

Definitions:
```
# SSH (t)unnel (i)nterface on the (r)emote machine.
tri=localhost
# SSH (t)unnel (r)emote (p)ort.
trp=$[$default_vnc_port + $display_port]
# SSH (t)unnel (l)ocal (p)ort.
tlp=$[$trp + 1]
```

Usage:
```
ssh -L$tlp:$tri:$trp ...

guix shell tigervnc-client -- vncviewer localhost:$tlp
```

Cheers,
Bost