(copy editors) RFR 8179858: jshell tool: sync nomenclature from reference to online /help

[Dan Smith]

> On Dec 4, 2017, at 6:06 PM, Robert Field <robert.field at oracle.com> wrote:
> 
> Very helpful.  See questions inline.
> 
>> "command-line": Same
> 
> Either is fine with me,  I can be consistent with the above, or change it back.

Whatever you like is fine. Just wanted to draw some attention to it.

> How about:
> 
>  For Unix, Linux and macOS, use a  colon (:) to separate items in the path.  For Windows, use a semicolon (;) to separate items.
> 
> Or just:
> 
>  For Windows, use a semicolon (;) to separate items in the path. On other platforms, use a  colon (:) to separate items.

Yeah, that last one seems the least brittle.

>> I'd also replace "types" with "type declarations" throughout, because "type" is such an overloaded term.
> 
> Good, that will read more clearly too.
> 
> I guess, then, that I should change the summary from:
> 
>  list the declared types
> 
> to:
> 
>  list the type declarations
> 
> ???

I'd lean slightly towards the latter. I'm not so concerned about "declared types", because it's clear you're talking about the subset of types that have declarations. But there's a one-to-many relationship between generic class declarations and class types, and of course you're not claiming to list every parameterization of that generic class.

>> ID ranges: these are listed everywhere as a distinct variant, but help.id suggests that they can appear within a list, interleaved with non-ranges. Which is it? (If the latter, maybe don't mention ranges at all for /vars, etc., and explain elsewhere that an "ID" may be a range of simple IDs. Or, if that's too obscure, try "specified snippet ID or range of snippet IDs" in /vars, etc. Or just give the list variant in /var, etc., more details about ranges.)
> 
> This was an attempt to keep it simple.  But the result is that seven /help descriptions are bloated by having descriptions for singleton id, id list, and id range -- while still not being complete.
> 
> How about, I create a new help subject "id" which will describe what an id is, how to discover them, and discuss ID ranges. Then I can compress the three in each (using /list as the example) from:
> 
>  /list <id>
>       List the snippet with the specified snippet ID
>  /list <id> <id>...
>       List the snippets with the specified snippet IDs
>  /list <id>-<id>
>       List the snippets within the range of snippet IDs
> 
> to just:
> 
>  /list <id>
>       List the snippet with the specified snippet ID.  One or more IDs or ID ranges may used, see /help id

I like that.

—Dan