Provide zipped javadoc archive from make

[Jiri Vanek]

Here we go!
  https://jvanek.fedorapeople.org/oracle/jdk8/webrevs/zip-javadocs/v2/
  https://jvanek.fedorapeople.org/oracle/jdk8/webrevs/zip-javadocs/v2/webrev.zip
>
> I can't seem to find your name on the OCA list [1], have you signed it? Otherwise we cannot accept
> patches from you.

As Andrew wrote down @redhat.com should do the job.
>
> I can comment and review the patch from a build point of view. There is a separate processes for
> approving it for inclusion in an older release, like JDK 8.

I'm aware of it. Once you are happy , I will use the patch in 8's rpms, and rpepare webrev for 9. 
Later, if luck allows, I will ask for backporting to 8.
>
> That said, your patch is mostly reasonable but there are a few things that needs changing.

Thank you very much for review and advices!
>
> In Main.gmk.
> * Please follow the current pattern of declaring both "zip-docs" and "zip-docs-only" and make
> zip-docs depend on docs. Dependencies between top level targets should be handled in the top level
> makefile.

Done. Although Now I'm a bit unsure about the dependencies, as described lower (*).
>
> In Javadock.gmk.
> * Please use := instead of = for variable declarations. This particular file unfortunately has many
> bad examples of where = is misused.

Fixed. I can fix the file as separate changeset for jdk9 if you agree.

> * The file should be named jdk-$(FULL_VERSION)-docs.zip
done

Although now it have date. However not-nice, definitely reasonable.

> * The file should be created in $(OUTPUT_ROOT)/bundles

Done.

> * Having the archive only depend on COREAPI_INDEX_FILE is broken if you also include the other docs.
> Either depend on all and include all or only include the core docs. If you only include the core
> docs, the targets and file names should probably change. Depending on all is currently tricky since
> Javadock.gmk is badly written and uses a lot of phony targets instead of the actual targets for
> dependency management. That would need to be fixed.

Well yes:( (*)

I'm aware of the brokenness of it, but what to depend on?
I wonted to avoid any other configuration, so whatever make docs generates, this target will pack.
But I stumbled over (now clear) bug in Javadock.gmk. - any time make docs (make docs-only seems 
broken) is invoked, it always regenerate all javadocs.

So by calling make zip-docs, with dependencies you recommended, it causes javadoc to be regenerated.


It seems to me out of scope of this patch, but if you feel differently, I will happily elaborate.

> * Please don't use temporary directories outside the build output dir. Such directories always risk
> being left behind by failed builds. We need the build to only create files in the designated output
> dir.

fixed.

> * --display-globaldots is not a good option to use in this context. It won't work well with file
> logging of the build and I doubt it's valid for all platforms we build on.

sure.   Removed.


Thanx!
   J.
>
> /Erik
>
> On 2016-03-29 18:24, Jiri Vanek wrote:
>> Hello Again!
>>
>> Sorry for delay in reply.
>>
>> There is webrev
>>
>> https://jvanek.fedorapeople.org/oracle/jdk8/webrevs/zip-javadocs/v1/
>> https://jvanek.fedorapeople.org/oracle/jdk8/webrevs/zip-javadocs/v1/webrev.zip
>>
>> with patch as was (moreover) agreed in this thread for *jdk8*
>>
>> As I was studying the makefiles, I think I did not violated to much conditions by this hunk of code:)
>> I thought that 8 will be much more simple, but at the end it evolved to same "find all roots" as
>> discussed for 9 and modules.
>>
>> The only thing I don't like in this patch is unsuitability of zip to zip directories with stripped
>> path.
>>
>> I went by pushd/popd  but I had seen you like cd in  make files more.
>>
>>
>> Thanx for any feedback!
>>
>>   J.
>>
>> On 03/08/2016 03:50 PM, Erik Joelsson wrote:
>>> I wouldn't go that far, but I won't have time to look into it for a while yet at least.
>>>
>>> /Erik
>>>
>>> On 2016-03-08 15:34, Jiri Vanek wrote:
>>>> Ping?
>>>>
>>>> Or is this going to be considered closed-wont "fix"?
>>>>
>>>> Thanx!
>>>>
>>>>  J.
>>>> On 02/29/2016 04:24 PM, Jiri Vanek wrote:
>>>>> On 02/26/2016 08:05 PM, Jonathan Gibbons wrote:
>>>>>> On 02/26/2016 03:49 AM, Jiri Vanek wrote:
>>>>>>> On 02/25/2016 06:34 PM, Jonathan Gibbons wrote:
>>>>>>>> On 02/25/2016 09:23 AM, Jiri Vanek wrote:
>>>>>>>>>
>>>>>>>>> I must be missing something. Dozens? Of varius runs of javadoc?
>>>>>>>>>
>>>>>>>>> I thought that javadoc ending at the end in single drectory is one single javadoc for java. If
>>>>>>>>> you are referring to javadoc generated by "per module" then one jjoined zip is enough for me.
>>>>>>>>
>>>>>>>>
>>>>>>>> Jiri,
>>>>>>>>
>>>>>>>> If you accept the premise  that javadoc writes one stylesheet.css file per run of javadoc,
>>>>>>>> take a
>>>>>>>> look at the following list:
>>>>>>>
>>>>>>> Then my goal will be to crate a trget, which takes
>>>>>>>    build/linux-x86_64-normal-server-release/images/docs/
>>>>>>> and pack it to
>>>>>>>  build/linux-x86_64-normal-server-release/images/javadoc.zip
>>>>>>>
>>>>>>> It should contains also the "smaller api" you are mentioning below? If not, then those should
>>>>>>> appear in this zip too.
>>>>>>>>
>>>>>>>> $ find build/linux-x86_64-normal-server-release/images/docs/ -name stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/dynalink/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/attach/spec/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/javac/tree/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/jconsole/spec/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/jpda/jdi/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/javadoc/doclet/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/javadoc/old/doclet/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/javadoc/old/taglet/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/nashorn/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/api/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/nio/sctp/spec/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/plugin/dom/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/security/jaas/spec/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/security/smartcardio/spec/stylesheet.css
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/security/jgss/spec/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/management/extension/stylesheet.css
>>>>>>>>
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/net/httpserver/spec/stylesheet.css
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/net/socketoptions/spec/stylesheet.css
>>>>>>>>
>>>>>>>>
>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/accessibility/jaccess/spec/stylesheet.css
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> The "main"/"Java SE" javadoc bundle that most are aware of is the shortest filename, in the
>>>>>>>> middle
>>>>>>>> of the list, but there are lots of other smaller APIs that get their own doc bundle.  You can
>>>>>>>> get at
>>>>>>>> most of them in released doc sets through the top-level "brick wall" page, or by using your
>>>>>>>> favorite
>>>>>>>> search engine.
>>>>>>>
>>>>>>> Hmm.. Do you have some?  javadoc offline search is quite painful think. (Even with new search in
>>>>>>> 9, which seems to have some troubles on local filesystem). The best search engine I know is
>>>>>>> (unluckily) https://github.com/judovana/JavadocOfflineSearch
>>>>>>
>>>>>> The point of the preceding list was to say that each directory containing stylesheet.css is the
>>>>>> root
>>>>>> of a separate, distinct, javadoc bundle.  So the smaller APIs that get their own bundle are
>>>>>> precisely the ones given in the preceding list, other than the main javadoc bundle.
>>>>>>
>>>>>> The point of the comment about the brick wall and search engines was to indicate how most people
>>>>>> will find these doc bundles in normal use, when they don't have a cheat sheet like the list
>>>>>> above.
>>>>>
>>>>> yes I got that. But Then this compressed shattered javadoc needs more thoughts.
>>>>>
>>>>> What is expected format of distribution?
>>>>> I can imagine: web accessible, unapcked "all docs" and "zipepd "all docs".
>>>>> But never several zips, or several directories.
>>>>>
>>>>> What is what I'm missing behind this effort to deliver javadocs per-module?
>>>>>
>>>>>>
>>>>>> As far as IDEs wanting to access javadoc bundles, I would expect that to make all the docs
>>>>>> available, you would want to zip up *each* directory containing stylesheet.css given in the
>>>>>> preceding list. If you just zip up the top API directory, sure, that will include all the files,
>>>>>> but
>>>>>> the reality is that the IDE will likely not have any way of knowing about the minor doc
>>>>>> bundles in
>>>>>> all jre/ and jdk/ directories and subdirectories.
>>>>>
>>>>> Indeed, when you pack top level javadoc directroy as top level of archive (so javadco will become
>>>>> zipped1.zip!javadoc) then indeed, Netbeasn refuse to load it whole 9just few parts)
>>>>>
>>>>> However when you pack it  that content of javadoc will be the top of the archive
>>>>> (zipped2.zip!{api,jdk,jre,platform}) then NB loads it fine.
>>>>>
>>>>> If even this is wrong, then as last approach is really to restructuralise docs after theirs
>>>>> generation/before zipping to structure where top level directory will the "one with style"
>>>>>
>>>>> dynalink/stylesheet.css
>>>>> spec/stylesheet.css
>>>>> tree/stylesheet.css
>>>>> spec/stylesheet.css
>>>>> jdi/stylesheet.css
>>>>> doclet/stylesheet.css
>>>>> nashorn/stylesheet.css
>>>>> api/stylesheet.css
>>>>> spec/stylesheet.css
>>>>> dom/stylesheet.css
>>>>> spec/stylesheet.css
>>>>> spec/stylesheet.css
>>>>> ...
>>>>>
>>>>> But looking to the occurences of "spec" There is something wrong with those assumptions :)
>>>>>
>>>>>
>>>>> As for indexing and viewing tools - They works fine with both zipepd1 and zipped2 (but there is
>>>>> not
>>>>> much to try)
>>>>>
>>>>> Seeing the impact of packaging, I think it is one more +1 to add this packing target, so JDK's
>>>>> javadoc is pacaked in known, "laodable" way.
>>>>>
>>>>> Thanx!
>>>>>    J.
>>>>>
>>>>>>
>>>>>> -- Jon
>>>>>>
>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>
>>>>>>>
>>>>>>> Thanx a lot!
>>>>>>>   J.
>>>>>>
>>>>>
>>>>
>>>
>>
>