Provide zipped javadoc archive from make

[Erik Joelsson]

Hello Jiri,

I can't seem to find your name on the OCA list [1], have you signed it? 
Otherwise we cannot accept patches from you.

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.

That said, your patch is mostly reasonable but there are a few things 
that needs changing.

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.

In Javadock.gmk.
* Please use := instead of = for variable declarations. This particular 
file unfortunately has many bad examples of where = is misused.
* The file should be named jdk-$(FULL_VERSION)-docs.zip
* The file should be created in $(OUTPUT_ROOT)/bundles
* 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.
* 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.
* --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.

/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.
>>>>>
>>>>
>>>
>>
>