(copy editors) RFR 8179858: jshell tool: sync nomenclature from reference to online /help
Jonathan Gibbons
jonathan.gibbons at oracle.com
Tue Dec 19 19:39:17 UTC 2017
Thumbs up.
-- Jon
On 12/19/2017 11:30 AM, Robert Field wrote:
>
> 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?
No.
>
> 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
>>>>
>>>>
>>>>
>>
>
More information about the kulla-dev
mailing list