Provide zipped javadoc archive from make

[Jiri Vanek]

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