(copy editors) RFR 8179858: jshell tool: sync nomenclature from reference to online /help
Jonathan Gibbons
jonathan.gibbons at oracle.com
Tue Dec 19 19:06:58 UTC 2017
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\
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.
-- 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
>>
>>
>>
More information about the kulla-dev
mailing list