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

Tue Dec 19 19:30:17 UTC 2017

On 12/19/17 11:06, Jonathan Gibbons wrote:
> Mostly OK/approved.   I found one line that needs to be fixed.
>
> Reading
>
> http://cr.openjdk.java.net/~rfield/8179858v1.webrev/
>
> In l10n.properties, two "a the".
>
>  570         a the jshell tool command, or, in some cases, a the 
> jshell tool command argument,\n\t\t\

Oops! Fixed

>
>
> Stylistically, for a future edit, unless you are doing specific custom 
> processing on the resource strings for tabs after newlines, I would 
> suggest using the convention of a slash at the beginning of a line, as in
>
> OLD:
>
> property.name=property value\n\t\
>     indented value
>
>
> NEW:
>
> property.name=property value\n\
> \    indented value
>
> The leading slash character "protects the spaces that follow.

Yes, that would be more readable.  Will migrate to that in future revs.

Do you want another review cycle?

Thanks,
Robert

>
> -- Jon
>
>
> On 12/19/2017 10:08 AM, Dan Smith wrote:
>> 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
>>>
>>>
>>>
>