Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8179858

jshell tool: sync nomenclature from reference to online /help

    Details

    • Subcomponent:
    • Resolved In Build:
      b39

      Backports

        Description

        Nomenclature in the jshell tool reference is been refined through several passes of review and is far better than that in the online /help.

        Examples:
        In jshell --help, and /help /open -- "file" is used, sync to script and create a "script" subject

        One by one compare command descriptions, options descriptions, etc between the two.

        (also, sync the tutorial)
         

          Issue Links

            Activity

            Hide
            rfield Robert Field added a comment -
            Comparison and sync have been done and many changes pulled over (or entered as bugs for the Tool Reference).

            Using "script" would be misleading and was not changed.

            The tutorial is now in the docs domain.


            Show
            rfield Robert Field added a comment - Comparison and sync have been done and many changes pulled over (or entered as bugs for the Tool Reference). Using "script" would be misleading and was not changed. The tutorial is now in the docs domain.
            Hide
            rfield Robert Field added a comment -
            Updated webrev out for review --

            Here is the updated webrev, based on the discussion below -- please review:

                http://cr.openjdk.java.net/~rfield/8179858v1.webrev/

            Bug:

                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@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

            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

            Show
            rfield Robert Field added a comment - Updated webrev out for review -- Here is the updated webrev, based on the discussion below -- please review:      http://cr.openjdk.java.net/~rfield/8179858v1.webrev/ Bug:      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@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 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
            Hide
            hgupdate HG Updates added a comment -
            URL: http://hg.openjdk.java.net/jdk/jdk10/rev/f91345a216c9
            User: rfield
            Date: 2018-01-04 20:29:17 +0000
            Show
            hgupdate HG Updates added a comment - URL: http://hg.openjdk.java.net/jdk/jdk10/rev/f91345a216c9 User: rfield Date: 2018-01-04 20:29:17 +0000

              People

              • Assignee:
                rfield Robert Field
                Reporter:
                rfield Robert Field
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: