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

[Dan Smith]

Thumbs up.

> On Dec 13, 2017, at 11:10 PM, Robert Field <robert.field at oracle.com> wrote:
> 
> Here is the updated webrev, based on the discussion below -- please review:
> 
>     http://cr.openjdk.java.net/~rfield/8179858v1.webrev/ <http://cr.openjdk.java.net/~rfield/8179858v1.webrev/>
> 
> Bug:
> 
>     https://bugs.openjdk.java.net/browse/JDK-8179858 <https://bugs.openjdk.java.net/browse/JDK-8179858>
> 
> Thanks,
> Robert
> 
> On 12/12/17 14:26, Dan Smith wrote:
>>> On Dec 4, 2017, at 6:06 PM, Robert Field <robert.field at oracle.com> <mailto: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
> 
> Very helpful.  See questions inline. 
> 
> On 12/04/17 12:11, Dan Smith wrote: 
>> Didn't find any serious problems, but here's a list of minor tweaks. 
>> 
>> —Dan 
>> 
>> ----- 
>> 
>> --class-path, --module-path: I don't understand the purpose of the '*' at the end, but I assume it's intentional. 
> 
> It was a reference to the path note below it.  Clearly didn't work. Will remove. 
> 
>> 
>> "load-file": I'd tend to avoid hyphens in compound nouns and stick to "load file", but apparently conventions vary: 
>> https://en.oxforddictionaries.com/punctuation/hyphen <https://en.oxforddictionaries.com/punctuation/hyphen> 
> 
> I choose hyphen so that in in the syntax "Usage:   jshell <option>... <load-file>..." it is clear that it is one thing, not two.  I'll lean on the varying conventions. 
> 
>> 
>> "command-line": Same 
> 
> Either is fine with me,  I can be consistent with the above, or change it back. 
> 
>> 
>> "For Linux and macOS": are there other supported Unix OSes? For comparison, here's the Javadoc for System.lineSeparator: "On UNIX systems, it returns "\n"; on Microsoft Windows systems it returns "\r\n". 
> 
> Good point, this wording is from the Tools Reference, will discuss with docs team for the Tool Reference.  Don't know if there are other supported OSes. 
> 
> I'd be concerned that many/most macOS users are not aware they are on a Unix platform.  Also, Linux is not technically a Unix(tm) OS. 
> 
> 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. 
> 
>> 
>> "A path is the directories and archives to search" --> "A path **lists** the directories and archives to search" 
> 
> Thanks. 
> 
>> 
>> "module-private package": I don't know my Jigsaw terminology very well, but this may not be a standard term. javac -X says "Specify a package to be considered as exported from its defining module" 
> 
> Indeed best to match.  Unlike javac, the default if <other-module> is unspecified is ALL-UNNAMED which  exports it to JShell code (in fact, that =<other-module> can be specified is undocumented). 
> 
> Simplest is what you suggest: 
> 
>        --add-exports <module>/<package>   Specify a package to be considered as exported from its defining module 
> 
> I like that. 
> 
>> 
>> "Show the snippets, prefaced with the snippet ID": either "each snippet" or "their snippet IDs" 
> 
> Thanks. 
> 
> I like the latter: 
> 
>     Show the snippets, prefaced with their snippet IDs 
> 
>> 
>> /save: inconsistent use of periods (this comment may apply more broadly—should do a quick pass to check) 
> 
> Ah, yes. line 315, and also 383, 461 and all of /set -- will survey 
> 
>> 
>> /types: An enum is a kind of class, so it's not necessary to list it separately (and it makes me think "what about annotation types?"). Just "classes and interfaces" is fine. 
> 
> Newbies may not make that connection, but they should, OK. 
> 
>> 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 
> 
> ??? 
> 
>> 
>> "since jshell was entered, or a /reset, or /reload command was executed" --> "since jshell was entered, or a /reset or /reload command was executed" 
> 
> Right. 
> 
>> 
>> "Errors will display" --> "Errors will be displayed" 
>> 
>> "the snippets will be replayed -- the replay is not shown, however, errors will display" --> "the snippits will be replayed. The replay is not shown, **but any** errors will *be displayed*." 
> 
> I like. 
> 
>> 
>> 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 
> 
> 
>> 
>> "when the jshell is started" "when jshell is restarted" "since this jshell was launched" "debugging of the jshell" "information about jshell": Need to decide is "jshell" refers to the command, or if it's another word for "shell" 
> 
> Will change all to "the jshell tool" 
> 
>> 
>> "These options configure the evaluation context, they can be specified" --> "These options configure the evaluation context. They can be specified" 
> 
> Thanks. 
> 
>> 
>> "A list of directories, each directory is a directory of modules." --> "A list of directories, **where** each directory **contains** modules" 
> 
> Thanks 
> 
>> 
>> "quoted strings printed as input prompts; Both" -- make that a period 
> 
> OK. 
> 
> Looking afresh, seems "quoted strings TO BE printed as input prompts." would be clearer. 
> 
> Thanks much, 
> Robert 
> 
> 
>> 
> 
>