Re: [screen-devel] description of -S and -p semantics in man page seems wrong

[Britton Kerin]

On Sat, May 26, 2012 at 4:07 PM, Chris Jones <address@hidden> wrote:
> On Sat, May 26, 2012 at 06:32:03PM EDT, Britton Kerin wrote:
>
>> I wanted to create a screen socket with a specific name, and
>> later be able to kill that particular window.  I create the window like
>> this:
>>
>>      screen -S arduino /dev/ttyACM0
>>
>> I expected to be able to kill it like this:
>>
>>      screen -p arduino -X kill
>>
>> But this doesn't work, all that happens is I get an inverted text
>> message at the bottom of the window like this:
>>
>>      -X: kill: window required
>>
>> After some google I find that this works:
>>
>>      screen -S arduino -X kill
>
>> Here is the description of the -S option in the man page:
>>
>>        -S sessionname
>>
>>           When  creating a new session, this option can be
>>           used to specify a meaningful name for the session. This name
>>           identifies the  session for  "screen  -list"  and  "screen -r"
>>           actions. It substitutes the default [tty.host] suffix.
>
>> Here is the description of the -p option:
>>
>>        -p number_or_name
>
>>           Preselect a window. This is useful when you
>>           want to reattach to  a specific  window or you want to send
>>           a command via the "-X" option to a specific window. As with
>>           screens select command, "-" selects the  blank  window.  As
>>           a special case for reattach, "=" brings up the windowlist on
>>           the blank window.
>
>> So you can see why I want to use -p, not -S.  I think its still worth
>> keeping the man page up to date despite google.  I don't know how git
>> works for this project or what the true semantics of -S and -p options
>> are or I could do this myself.  If anyone wants to tell me what these
>> option descriptions should be I'll try to get them into git.
>
> First you create a session named ‘arduino’ (the -S flag) and then you
> issue a screen command specifying the session name and using the -p and
> -X flags, which the manual indicates are meant for _a specific window_
> within a screen session, not the session.
>
> From the above commands I can see you created a session named arduino.
>
> Since screen would start up by default with one window (window zero) and
> keeping in mind that screen exits when the last window is killed, you
> could try:
>
> | % screen -S arduino -p 0 -X kill
>
> My understanding is that in the manual screen's terminology regarding
> windows and sessions is that you can create one or more ‘sessions’
> (~screen processes as seen by the OS), each one with one or more
> screen ‘windows’ (or panes.. viewports.. etc.)

You seem to be correct.  The -S man page documentation still needs a fix
though.  It begins "When creating a new session,... " which is very
misleading.  I notice that the Screen User's Manual has this:

‘-S sessionname’
    Set the name of the new session to sessionname. This option can be used
    to specify a meaningful name for the session in place of the default
    tty.host suffix. This name identifies the session for the screen -list
    and screen -r commands. This option is equivalent to the sessionname
    command (see Session Name).

Which is different text but wrong in the same way.  The -S option has semantic
significance that has nothing to do with the creation of new sessions.
It applies in that case but also in others.

I just spent some time trying to figure out how to get a list of all the
windows in a session, to be sure and send the commant to the correct one.
But I couldn't figure it out.  I'm using the 'screen /serial/port/dev'
form of the screen command, which doesn't seem to support the n argument
that lets you specify the window number explicitly.  'screen -list' says it
lists sessions, and indeed its output doesn't seem to show window numbers.
I think a general cleanup of the description of the options controlling and
specifying sessions and windows would be worthwhile.

Britton