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
