Provide zipped javadoc archive from make

[Jiri Vanek]

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