[PROPOSAL] Distributing source and docs from the repository

[David Garnier <da...@etudier-online.com>]

Hello,

I'm thinking that Maven's repository could be used to distribute source
and documentation along with the binary of a library. For each version
of a library, the repository would contain the source code and the
documentation, in two different .jar files. I browsed the archive and I
don't think this idea surfaced before.

This would enable several interesting features:

* Not having to hunt around for the source or the documentation of a
library when a problem arises. Personally, I try to keep around the
source and the documentation of each library I use in a project. 
Managing this directory is time-consuming compared to Maven's
repository.

* Source-level debugging for libraries: many IDEs allow you to attach a
source archive to a library, so you can debug directly in its source.
Eclipse, JBuilder and Netbeans can do it, so I guess that the others can
do it too. Their respective plugins could be modified to automatically
add the source to their configuration files when they are generated by
Maven. For anyone using the command-line, there are numerous tools that
can mount a jar file as a file system (like Konqueror).

* Pretty-printed version of the source of each library in the web site.
Probably fairly intensive for big projects,but I think that it is worth
it.

Various issues I can think of:

* The definition of what constitues the documentation can vary widly
from project to project. In many cases, the documentation is a set of
webpages, PDFs, .doc files and many other artifacts. Furthermore, the
copyrights of theses pieces aren't always very clear. But there is at
least one piece of documentation that is consistent across projects:
Javadocs, so let starts with that.

* Bigger administrative overhead due to the new files.

* Increases the bandwitdh used at ibiblio.org. I don't know if it's a
big problem or not.

* Adding the files to the existing libraries would be a big job, and
this can hardly be delegated to anyone because of the trust issue.
However, since the files won't be executed, this is a little less of an
issue.

Of course this feature would be optional, activated by an option in the
<dependency> section of each library.

Now if you've read through this entire post, you can probably tell if
this a just a pipe dream for some reason I overlooked, or if it is
possible. 

Best Regards,
-- 
David Garnier <da...@etudier-online.com>

Re: [PROPOSAL] Distributing source and docs from the repository

[Jason van Zyl <ja...@zenplex.com>]

On Thu, 2003-02-13 at 16:47, David Garnier wrote:
> Hello,
> 
> I'm thinking that Maven's repository could be used to distribute source
> and documentation along with the binary of a library. For each version
> of a library, the repository would contain the source code and the
> documentation, in two different .jar files. I browsed the archive and I
> don't think this idea surfaced before.

The repository was not enabled strictly to serve as JAR storage. Any
artifact from a project can be stored in the repository. When the
repository admin application is working projects may choose to store
anything they wish.

> This would enable several interesting features:
> 
> * Not having to hunt around for the source or the documentation of a
> library when a problem arises. Personally, I try to keep around the
> source and the documentation of each library I use in a project. 
> Managing this directory is time-consuming compared to Maven's
> repository.

One of the things we are trying to get populated quickly are the POMs of
each project. With access to this you really have access to anything you
need. But for convenience a plugin could be made to say make the IDE
source bundles you are speaking of and provide a deployment goal for
such a thing. These are exactly the type of things we are looking for:
project artifacts that made development easier.

Once the POMs are globally available I see many amazing things
happening. That's my personal priority.

> * Source-level debugging for libraries: many IDEs allow you to attach a
> source archive to a library, so you can debug directly in its source.
> Eclipse, JBuilder and Netbeans can do it, so I guess that the others can
> do it too. Their respective plugins could be modified to automatically
> add the source to their configuration files when they are generated by
> Maven. For anyone using the command-line, there are numerous tools that
> can mount a jar file as a file system (like Konqueror).

+1

This has been mentioned before but no one has augmented the 'java'
plugin to produce this (or a separate plugin).

> * Pretty-printed version of the source of each library in the web site.
> Probably fairly intensive for big projects,but I think that it is worth
> it.
> 
> Various issues I can think of:
> 
> * The definition of what constitues the documentation can vary widly
> from project to project. In many cases, the documentation is a set of
> webpages, PDFs, .doc files and many other artifacts. Furthermore, the
> copyrights of theses pieces aren't always very clear. But there is at
> least one piece of documentation that is consistent across projects:
> Javadocs, so let starts with that.

Source and binary distributions are created by default with Javadocs
included. But a global Javadoc index would be cool!

> * Bigger administrative overhead due to the new files.
> 
> * Increases the bandwitdh used at ibiblio.org. I don't know if it's a
> big problem or not.

Nope, we can stuff them to the rafters. There is no cap as that I am
aware of.

> * Adding the files to the existing libraries would be a big job, and
> this can hardly be delegated to anyone because of the trust issue.
> However, since the files won't be executed, this is a little less of an
> issue.
> 
> Of course this feature would be optional, activated by an option in the
> <dependency> section of each library.
> 
> Now if you've read through this entire post, you can probably tell if
> this a just a pipe dream for some reason I overlooked, or if it is
> possible. 

Nope :-) I hope that eventually the repository will become the first
place Java developers look for project information. The more POMs we get
the better.

> Best Regards,
-- 
jvz.

Jason van Zyl
jason@zenplex.com
http://tambora.zenplex.org

In short, man creates for himself a new religion of a rational
and technical order to justify his work and to be justified in it.
  
  -- Jacques Ellul, The Technological Society

Re: [PROPOSAL] Distributing source and docs from the repository

[Stephane Mor <st...@yahoo.fr>]

On Thu, Feb 13, 2003 at 10:47:37PM +0100, David Garnier wrote:

Hello,
> 
> I'm thinking that Maven's repository could be used to distribute source
> and documentation along with the binary of a library. For each version
> of a library, the repository would contain the source code and the
> documentation, in two different .jar files. I browsed the archive and I
> don't think this idea surfaced before.
> 
> This would enable several interesting features:
> 
> * Not having to hunt around for the source or the documentation of a
> library when a problem arises. Personally, I try to keep around the
> source and the documentation of each library I use in a project. 
> Managing this directory is time-consuming compared to Maven's
> repository.

The POM keeps the url, site address, cvs, etc. of the project, so I'd rather put a
pointer there to the actual source distribution instead of copying everything to
ibiblio. Something like "maven get-source" could download it from it's
_original_ location, an put it in your local repository. "maven get-cvs" or something
would download the source from the cvs, for instance.

For this, we need to have each project's POM on the repository (a few kbs).

> 
> * Source-level debugging for libraries: many IDEs allow you to attach a
> source archive to a library, so you can debug directly in its source.
> Eclipse, JBuilder and Netbeans can do it, so I guess that the others can
> do it too. Their respective plugins could be modified to automatically
> add the source to their configuration files when they are generated by
> Maven. For anyone using the command-line, there are numerous tools that
> can mount a jar file as a file system (like Konqueror).

This is a nice feature. Whether we get it from ibiblio or the original source is
irrelevant, IMHO.

> 
> * Pretty-printed version of the source of each library in the web site.
> Probably fairly intensive for big projects,but I think that it is worth
> it.

Each project should be responsible for its source and docs, and those should
go on _its_ website, IMHO.

> 
> Various issues I can think of:
> 
> * The definition of what constitues the documentation can vary widly
> from project to project. In many cases, the documentation is a set of
> webpages, PDFs, .doc files and many other artifacts. Furthermore, the
> copyrights of theses pieces aren't always very clear. But there is at
> least one piece of documentation that is consistent across projects:
> Javadocs, so let starts with that.

Each "mavenized" project can put that for free on its generated website, even
the whole docs and not only the 

> 
> * Bigger administrative overhead due to the new files.

That's for sure !!
If you look at the archive for "jar request", you'll see that having the libs
uploaded to ibiblio is not something trivial until the admin app is out.
Add to that the source and the docs, and imagine what it gives you!

> 
> * Increases the bandwitdh used at ibiblio.org. I don't know if it's a
> big problem or not.

This _IS_ a big problem.
For instance, I use Maven on a Gentoo Linux distribution. Gentoo uses a global
repository to download and install softwares automagically (like Debian).
Gentoo's main
repository lives at ibiblio as well. When gcc-3.2.1 and kde-3.1 went out,
the download rates reached an unusable state (0.1 kbps, when it wasn't a
timeout). This affected both Gentoo and Maven.

Bandwidth is something that I hate to waste. If each project stores its docs and
sources, the bandwidth need is divided in as many places, and ibiblio is safe!

> 
> * Adding the files to the existing libraries would be a big job, and
> this can hardly be delegated to anyone because of the trust issue.
> However, since the files won't be executed, this is a little less of an
> issue.
> 
> Of course this feature would be optional, activated by an option in the
> <dependency> section of each library.
> 
> Now if you've read through this entire post, you can probably tell if
> this a just a pipe dream for some reason I overlooked, or if it is
> possible.

It _IS_ possible, but I'm -1 on it.
I would like Maven to be a "light" tool. Having a repository which contains the
libraries is a GREAT thing, but we shouldn't use it to store otherwise present
docs and sources, IMHO.

I'd rather have a cvs repository of POMs, which would store all the POMs of the
mavenized projects. This way, we could get all the infos we need from a single
place.

Dreamers (as I am) can imagine a tool using those infos.
(hint: have a look at Gentoo Linux's Portage tree, and its associated "emerge"
tool: 
http://www.gentoo.org/doc/en/portage-manual.xml 
http://www.gentoo.org/doc/en/portage-user.xml)

Cheers,
Stéphane

Re: [PROPOSAL] Distributing source and docs from the repository

[Leif Nelson <ln...@llnl.gov>]

I think this is an excellent idea.  I do similar kinds of things (outside 
of Maven) and would love to have this stuff built-in.

--Leif

At 10:47 PM 2/13/2003 +0100, you wrote:
>Hello,
>
>I'm thinking that Maven's repository could be used to distribute source
>and documentation along with the binary of a library. For each version
>of a library, the repository would contain the source code and the
>documentation, in two different .jar files. I browsed the archive and I
>don't think this idea surfaced before.
>
>This would enable several interesting features:
>
>* Not having to hunt around for the source or the documentation of a
>library when a problem arises. Personally, I try to keep around the
>source and the documentation of each library I use in a project.
>Managing this directory is time-consuming compared to Maven's
>repository.
>
>* Source-level debugging for libraries: many IDEs allow you to attach a
>source archive to a library, so you can debug directly in its source.
>Eclipse, JBuilder and Netbeans can do it, so I guess that the others can
>do it too. Their respective plugins could be modified to automatically
>add the source to their configuration files when they are generated by
>Maven. For anyone using the command-line, there are numerous tools that
>can mount a jar file as a file system (like Konqueror).
>
>* Pretty-printed version of the source of each library in the web site.
>Probably fairly intensive for big projects,but I think that it is worth
>it.
>
>Various issues I can think of:
>
>* The definition of what constitues the documentation can vary widly
>from project to project. In many cases, the documentation is a set of
>webpages, PDFs, .doc files and many other artifacts. Furthermore, the
>copyrights of theses pieces aren't always very clear. But there is at
>least one piece of documentation that is consistent across projects:
>Javadocs, so let starts with that.
>
>* Bigger administrative overhead due to the new files.
>
>* Increases the bandwitdh used at ibiblio.org. I don't know if it's a
>big problem or not.
>
>* Adding the files to the existing libraries would be a big job, and
>this can hardly be delegated to anyone because of the trust issue.
>However, since the files won't be executed, this is a little less of an
>issue.
>
>Of course this feature would be optional, activated by an option in the
><dependency> section of each library.
>
>Now if you've read through this entire post, you can probably tell if
>this a just a pipe dream for some reason I overlooked, or if it is
>possible.
>
>Best Regards,
>--
>David Garnier <da...@etudier-online.com>