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
