RFR [15] 8239487: Better links generation for system properties found in HTML files

[Pavel Rappo]

Hello,

Please review the change for https://bugs.openjdk.java.net/browse/JDK-8239487:

  http://cr.openjdk.java.net/~prappo/8239487/webrev.00/

This change addresses 2 closely related issues on the "System Properties Page":

    8239485: Define behavior of the System Properties page when no system properties are available
    8239487: Better links generation for system properties found in HTML files

This change does NOT affect the (somewhat related) representation of search
results in the Interactive Search or the looks of the Index pages in any way.

The net effect of JDK-8239487 can be seen when comparing the outputs.
(For practical reasons the below two links contain only bare-bones versions
of the system properties page out of all the documentation.)

Before:

  http://cr.openjdk.java.net/~prappo/8239487/before/system-properties.html

After:

  http://cr.openjdk.java.net/~prappo/8239487/webrev.00/after/system-properties.html

  ***

For convenience I split this change into 4 changesets, called phase-{1, 4},
which are applied in this particular order.

phase-{1, 2} are intermediate, but somewhat necessary, refactorings.
phase-{3, 4} are the core of the change.

* phase-1 splits Category.SEARCH_TAGS into two separate categories, Category.INDEX
and Category.SYSTEM_PROPERTY. The reason is that more often than not, items of
those categories are consumed separately. This also allows to remove the hacky
systemProperty flag from SearchIndexItem.

There are still a few cases left where items of those categories are consumed
as if they were of a single category. In these cases careful attention is
required. For example, since INDEX and SYSTEM_PROPERTY items are no longer
sorted as a whole, a use-site sorting is applied where necessary.

There are changes to make the SearchIndexItems container work with the Stream
API rather than with Collections. I'm not 100% sure if the Stream API is the
right abstraction here, but for now, it seems to fit better than the alternatives.
That said, in some places Streams API had to be shoehorned (for now) by using
stream.iterator() "escape hatch".

Signatures of the query methods in SearchIndexItems have also been fixed to
accommodate for the change, described above, in Category. There's a top-level
@apiNote in SearchIndexItems describing the details.

On a related note. If that (required, optional...) signature pattern proves
useful, we could move SearchIndexItems.concat to Utils for reuse.

* phase-2 is a small cleanup that leverages Stream API from SearchIndexItems
where practical.

* phase-3 is the meat of the change. The DocFilesHandlerImpl.getWindowTitle
method is extracted and moved to Utils. A String field "referrer" is introduced
in SearchIndexItem to hold a description (title) of a non-program elements, such
as HTML files. The System Properties Page is no longer generated if there are no
system properties. Links to program elements are displayed in a monospace font,
whereas non-program elements are displayed in a proportional font. "Overview"
file is treated specially (it's not of kind DOCFILE, neither is it a program
element) as it should be displayed in a proportional font.

Some tests are adapted to reflect that the System Properties Page is now
generated conditionally. "system-properties.html" has been excluded from the
"standardExpectFiles" set in APITest. A single {@systemProperty} tag is injected
into TestMetadata.java. TestSystemPropertyPage is updated. Fixed some typos
along the way.

* By phase-4 it became apparent that search item needs to store richer context
than that of provided by a bunch of string fields. So the anemic String referrer
field is swapped for the DocletElement element field. A cache of HTML titles is
moved to the use site. Once again updated the TestSystemPropertyPage test.

Changed presentation in the SystemPropertiesWriter.createLink. Non-program
elements are rendered with an extra bit of context: the enclosing package. If a
non-program element has no <title>, the code falls back to the file name. This
is done in a more reliable way than it used to be (the code that relied on
"doc-files" substring was pretty brittle).

Notes
=====

1. I must say that it is unsettling to see how much of the presentation detail
spills over into the Java code :( This is something to think about while working
on HTML and CSS.

2. I do believe that this change addresses most of the concerns raised when the
System Properties page was introduced:

  https://mail.openjdk.java.net/pipermail/javadoc-dev/2019-December/001234.html

That said, there is a lot more that can be done here. For example, even the
current, improved, page might look untidy and cluttered should there appear system
properties linked from both doc files and program elements. Have a look at the
following, contrived, example (this is the actual output of the TestSystemPropertyPage test):

  http://cr.openjdk.java.net/~prappo/8239487/webrev.00/test-output/system-properties.html

This suggests some visual improvements are required. One way it could be done is
by using description lists (<dd>) instead of plain comma-separated lists.
(A note to self. Should the way <dl>s are rendered depend on the used locale?
Are those subject to the same localization concerns as comma-separated lists?)

-Pavel