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

[Robert Field]

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

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


>