Am 02.12.2019 um 17:32 schrieb Jonathan Gibbons <[email protected]>: > > Woohoo! Awesome! >
:) > -- Jon > > P.S. (Separately) we really should create a library method somewhere to > localize a list. I have an email thread discussing the issue with L10N folk. > The use of "," "and" and "or" in the presentation of a list should all be > localized. If/when we do that, we could update your search examples to > contain multiple matches. > Yes, I thought about that, but it seemed like overkill, unless there are other use cases (which I don’t know about). Thanks Hannes > On 12/2/19 5:54 AM, Hannes Wallnöfer wrote: >> Thanks Jon, I’ve used your suggestion with minor changes listed below. >> >> New webrev: http://cr.openjdk.java.net/~hannesw/8223252/webrev.02/jdk.patch >> Help doc: http://cr.openjdk.java.net/~hannesw/8223252/api.02/help-doc.html >> >> - Instead of "InputStream" and „InputStreamReader“ it just lists >> „InputStream“; the „and“ would be subject to localization, and there are >> several other matches we don’t mention as well. >> - I used „HM.cK“ and matching „java.util.HashMap.containsKey(Object)“ as >> third item since I wanted to add an example of „minimal“ camel-case search >> and one that also covers a member name. >> >> Hannes >> >>> Am 27.11.2019 um 23:46 schrieb Jonathan Gibbons >>> <[email protected]>: >>> >>> Modified suggestion inline: >>> >>> >>> On 11/27/2019 01:40 PM, Jonathan Gibbons wrote: >>>> Hannes, >>>> >>>> It is obviously difficult to abbreviate the full search specification into >>>> a couple of sentences ;-) >>>> >>>> I have a couple of suggestions. >>>> >>>> 1. Restructure the text to give all the rules before any of the examples. >>>> This will make it easier to group and/or add examples. For example: >>>> >>>> 219 doclet.help.search.body=You can search for definitions of modules, >>>> packages, types, fields, methods, \ >>>> 220 system properties and other terms defined in the API, using some >>>> or all of the name, optionally using "camel-case". >>>> For example, >>>> "j.l.obj" will match "java.lang.Object", "InpStr" will match >>>> "InputStream" and "InputStreamReader", >>>> "j.u.HaMa" will match "java.util.HashMap". >>>> Refer to {0} for a full description of search >>>> features. >>>> >>>> 2. (Restructure it even more to separate the examples into individual >>>> resources) >>>> >>>> >>>> 219 doclet.help.search.intro=You can search for definitions of modules, >>>> packages, types, fields, methods, \ >>>> 220 system properties and other terms defined in the API, using some >>>> or all of the name, optionally using "camel-case". >>>> For example: >>>> doclet.help.search.example.1= >>>> "j.l.obj" will match "java.lang.Object", >>>> doclet.help.search.example.2="InpStr" >>>> will match >>>> "InputStream" and "InputStreamReader", >>>> doclet.help.search.example.3="j.u.HaMa" will match >>>> "java.util.HashMap". >>>> doclet.help.search.refer=Refer to {0} for a full description of search >>>> features. >>> Update, we would not expect localizers to localize the examples, so this >>> could be simplified to >>> >>> 219 doclet.help.search.intro=You can search for definitions of modules, >>> packages, types, fields, methods, \ >>> 220 system properties and other terms defined in the API, using some >>> or all of the name, optionally using "camel-case". >>> For example: >>> doclet.help.search.example={0} >>> will match {1} >>> >>> doclet.help.search.refer=Refer to {0} for a full description of search >>> features. >>> >>> ... and the list of examples could be hardwired in the code. That also >>> makes it easier to inject the <code>...</code> >>> around the content of the examples. >>> >>>> >>>> The suggestion is then that the examples are put into a <ul> list. You >>>> could go for a table but that is generally more work. >>>> You could do the examples within a loop until you get some sort of >>>> "resource not found" result. >>>> For bonus points, use a regex to replace instances of "([^"]+)" with >>>> "<code>$1</code>" ... i.e. inject <code>...</code> around the contents of >>>> the quoted string. >>>> >>>> >>>> -- Jon >>>> >>>> >>>> On 11/19/2019 03:43 AM, Hannes Wallnöfer wrote: >>>>> Jon, >>>>> >>>>> I’ve updated the webrev with the comments as suggested. I also update the >>>>> text to hopefully be a bit clearer. It’s also closer to the previous >>>>> text, and just adds the following: >>>>> >>>>> - mention system properties as searchable items >>>>> - add example of „j.l.obj“ matching „java.lang.Object“ >>>>> - Add sentence with reference to search spec >>>>> >>>>> New webrev: >>>>> http://cr.openjdk.java.net/~hannesw/8223252/webrev.01/ >>>>> >>>>> New help page: >>>>> http://cr.openjdk.java.net/~hannesw/8223252/api.01/help-doc.html >>>>> >>>>> >>>>> Hannes >>>>> >>>>> >>>>>> Am 13.11.2019 um 03:00 schrieb Jonathan Gibbons >>>>>> <[email protected]> >>>>>> : >>>>>> >>>>>> Hannes, >>>>>> >>>>>> It is somewhat weird/non-standard to use resources in this way to create >>>>>> links, and the decision to put the word "the" outside the link, away >>>>>> from the content of the link "Javadoc Search Specification" is a bit >>>>>> idiomatic. >>>>>> >>>>>> I'd suggest prefixing the resources with comments describing the values >>>>>> that will be substituted. >>>>>> >>>>>> # {0} will be replaced by a link derived from the url and title for >>>>>> the Javadoc Search Specification >>>>>> 222 doclet.help.search.spec.body=Refer to the {0} for a full >>>>>> description of search features. >>>>>> # The URL for the Javadoc Search Specification. {0} will be >>>>>> replaced by the JDK version number >>>>>> >>>>>> 223 doclet.help.search.spec.url= >>>>>> https://docs.oracle.com/en/java/javase/ >>>>>> >>>>>> {0}/docs/specs/javadoc/javadoc-search-spec.html >>>>>> # The title for the Javadoc Search Specification >>>>>> >>>>>> 224 doclet.help.search.spec.title=Javadoc Search Specification >>>>>> -- Jon >>>>>> >>>>>> On 11/12/19 2:30 AM, Hannes Wallnöfer wrote: >>>>>> >>>>>>> Please review: >>>>>>> >>>>>>> Bug: >>>>>>> >>>>>>> https://bugs.openjdk.java.net/browse/JDK-8223252 >>>>>>> >>>>>>> >>>>>>> Webrev: >>>>>>> >>>>>>> http://cr.openjdk.java.net/~hannesw/8223252/webrev.00/ >>>>>>> >>>>>>> >>>>>>> >>>>>>> >>>>>>> New help page: >>>>>>> >>>>>>> http://cr.openjdk.java.net/~hannesw/8223252/api.00/help-doc.html >>>>>>> >>>>>>> >>>>>>> >>>>>>> Changes in the „search“ section of the help page: >>>>>>> >>>>>>> - mention of searchable system properties >>>>>>> - mention and example of partial matches (in addition to camel-case) >>>>>>> - new paragraph with link to search spec on docs.oracle.com >>>>>>> >>>>>>> Thanks, >>>>>>> Hannes >>>>>>> >>>>>>>
