[MNG-8097] Outline the two different ways to reference a dependency

[kwin]

(with a related artifact handler)

[cstamas]

I find this very much mixed up and not quite comprehensive. @hboutemy

Issues:

• by removal of "filename", the term "extension" is suddenly changing it's meaning (maven extension? this was my first thought while trying to comprehend the message)
• did you maybe mix up the "former and latter"?
• I find this very confusing all in all. Type is type, why do you want to mixin here file extension?

[kwin]

by removal of "filename", the term "extension" is suddenly changing it's meaning (maven extension? this was my first thought while trying to comprehend the message)

you kind of said the opposite in apache/maven#1466 (comment). This is the extension of the artifact which is not necessarily the extension of the filename!

The depensency extension is told by type. Deoendency is never "anywhere on disk", it may come from repo only.

or in apache/maven#1466 (comment)

It is artifact that you need to inspect, not the backing file.
yes, good catch will fix.

I find this very confusing all in all. Type is type, why do you want to mixin here file extension

First of all, there was a mention of file extension before this PR, with this PR I only refer to artifact extension (do you find this part confusing???). This PR rather clarifies that there may be two ways to reference the same artifact, examples:

1. <dependency>
     <groupId>org.project</groupId>
     <artifactId>reusable-test-support</artifactId>
     <version>1.0</version>
     <classifier>tests</classifier>
   </dependency>
   

   vs.

   <dependency>
     <groupId>org.project</groupId>
     <artifactId>reusable-test-support</artifactId>
     <version>1.0</version>
     <type>test-jar</type>
   </dependency>
   

2. <dependency>
     <groupId>org.project</groupId>
     <artifactId>my-osgi-bundle</artifactId>
     <version>1.0</version>
   </dependency>
   

   vs.

   <dependency>
     <groupId>org.project</groupId>
     <artifactId>my-osgi-bundle</artifactId>
     <version>1.0</version>
     <type>bundle</type> <!-- defined by artifact handler in maven-bundle-plugin -->
   </dependency>
   
   

3.  <dependency>
      <groupId>org.project</groupId>
      <artifactId>my-content-package</artifactId>
      <version>1.0</version>
      <type>zip</type>
    </dependency>
   

   vs.

   <dependency>
     <groupId>org.project</groupId>
     <artifactId>my-content-package</artifactId>
     <version>1.0</version>
     <type>content-package</type> <!-- defined by artifact handler in filevault-package-maven-plugin -->
   </dependency>
   
   

Please be more concise with your criticism so that I am able to address it.