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

From: Maxim Cournoyer <[email-masked]>
Date: Sat, 08 Feb 2025 21:32:40 +0900

reopen 68453
quit

+CC guix-devel to sollicit more input

Hi,

Rostislav Svoboda <[email-masked]> writes:

> Hello Maxim,
>
>> > * doc/guix.texi (VNC Services): Don't change the value of
>> > `display-number`.
>>
>> Do you mean 5905 is supposed to be the default value?  It's not (the
>> default display number is 0), or at least that's the convention to have
>> the VNC server listen on the usual 5900 port.

> 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'.

>> > Refine and improve the `xclock` and `vncviewer` invocation
>> > examples.
>>
>> I've looked at the modified examples, but I think your proposed changes
>> make things look more complicated, which is beside the point of
>> providing easy to read/trivial examples.
>
> You may not find my examples useful, but that doesn't convince me that
> the existing ones are easy to read or trivial.
>
> The reason I took the time to modify this part of documentation and
> submit a patch is precisely because I found the current examples not
> easy to understand.
>
>> I'll now close this issue.
>
> Could you please reopen this issue? I believe the inconsistency and
> readability concerns I raised are still unresolved.

OK.  Perhaps I acted too quickly.  I'm also biased as I wrote these very
examples.  But in my opinion, turning these small, directly
copy/pastable command snippets into a more complex shell script means
the users have more to read and understand, on topics related but not
meant to be the focus of these examples (SSH tunneling).

I'll reopen and give it a week or two for guix-devel neutral readers to
provide feedback on the change.

At any rate, thank you for your efforts trying to improve our
documentation.

-- 
Thanks,
Maxim