Documentation is needed
joachim - August 19, 2008 - 18:05
| Project: | getID3() |
| Version: | 5.x-1.1 |
| Component: | Documentation |
| Category: | bug report |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | duplicate |
Description
This module doesn't seem to have any instructions.
Some questions docs should answer:
Which version of getid3 do I need to download?
(In fact, tell me first that I need to get it, as the first indication that I need it is the error message I get after I enable the module.)
Where exactly do I put it?
#1
I second that. the audio module contains more information about getID3 than the getID3 module itself. All getID3 related information should be centralized in this module. The audio module recommends to use getID3 1.7.7 version.
#2
i agree, a patch would be much appreciated.
#3
Regarding docs: if maintainers post the answers, I'll write them up as a handbook page. :)
#4
If you write a few helpful sentences, I'd be happy to stick it in hook_help ;-) .
#5
It's a while since I've installed this module, but going by my initial report, there was an error message on install.
So I'd suggest three things are needed here:
1. a code fix so instead of an error message on install, you get a message saying 'You need to install the getid3 library for the getid3 module to work. Read more about this on the help page.'
2. Text for the help page.
3. A handbook page so people can read about what they need to do before installing.
2 & 3 I can do if provided with the information.
#6
Hey it's been 2 months, is there any more information on this?
#7
I just installed this module on drupal 6.6 and can answer some of the questions that someone would want to know going into the install.
A. The GetID3 configuration page says: "Currently, the recommended version of the getID3 library is 1.7.7." Although this version is a couple of years old, but if it does what GetID3 (the module) and more importantly what the Audio module needs, why give yourself headaches with what are now betas of the next versions.
B. If like with the 5.x version of Audio module, you download the getid3-1.7.7.zip file into the module root, for example sites/all/modules/getid3 and then unpack the zip there it will give you a directory getid3. This puts the executable at:
sites/all/modules/getid3/getid3/getid3/getid3.php
The first getid3 directory is for the drupal module
The second getid3 directory is has the general files for the getid3 project.
The third getid3 directory is where the getid3 project puts it's php files.
Using this to Update the instructions from the Audio module readme we get something like:
1. Install the getID3 package MAKE SURE YOU READ THE SECURITY NOTE BELOW!
a. Download the project getId3 version from http://www.getid3.org/ which will direct you to SourceForge.net.
The latest version tested with the GetID3 module is 1.7.7. Earlier versions contain
bugs that will cause you headaches.
b. Extract the archive into the sites/all/modules/getid3 directory. When you're
finished the directory structure should look something like:
drupal/
sites/
all/
modules/
getid3/
getid3/
README.txt
[...]
getid3/
getid3.php
write.php
c. *** IMPORTANT ***
YOU MUST DELETE THE 'demos' FOLDER OF THE ID3 LIBRARY. FAILURE TO DO SO
OPENS UP A MASSIVE SECURITY HOLE AND MAKES YOUR SITE EXTREMELY VULNERABLE
TO ATTACKS!
Fortunately the GetID3 module will check this for you and warn you if the evil demo directory still exists.
2. Enable the getid3 module on the
Administer >> Site building >> modules page. The database tables will be created
automagically for you at this point.
3. Go to Administer >> Site configuration >> GetID3 and check that the PATH to the getID3
package is configured correctly. If you follow the above directory
structure, the path should be "sites/all/modules/getid3/getid3/getid3/".
4. This module is intended to be called by other modules (e.g. audio) and relies on those modules to
manage permissions so there is no getid3 section on Administer >> User management >> Permissions
#8
Suggestion: You may wish to place the getid3 package on a separate folder, out of the document root. That way you can replace the getid3 module folder when it is updated without having to move the folder where the getid3 package is located, and viceversa.
#9
What if I only get two getid3 tags? For instance, mine says: sites/default/modules/getid3/getid3. It's throwing up no error signs, but will my computer explode in the future if I try to use it?
#10
I understand the logic of moving the library out of the module directory. These directory trees might want to be updated separately. In order for that to be less confusing I would think that Rob would need to change the name of the module to getid3_shim or something. I think a naming convention like that would be good, but I don't see that in other libraries.
The Drupal naming convention (module name = library name) and the php library placement convention (library is untared inside module directory) is used by a number of drupal modules interfacing with php libraries (e.g. FCKeditor and TinyMCE).
#11
So far I have found the diagnostics on the settings page to be accurate. If it does not complain then any explosions are likely to be the result of unnamed evil doers. If you see the version number on the settings page then, as the description below the version number indicates, your PATH values match the location of the getid3 library and you are good to go.
Since it is hard to get people to read descriptions maybe the version number message could be more verbose as in the attached patch.
#12
Another possible approach would be to distribute the library with the module, which is allowed if the library is "GPL v2 or later".
As in example, the ApacheSolr module distributes the PHP Solr client library, I also did the same with the Sphinxsearch module. Drupal itself distributes jQuery, etc.
Maybe this approach could make things easier here as well. It also offers the possibility to test new library releases with the module and release them if and when things work correctly together.
#13
This appeals to me, this way you are guaranteed compatibility. It particularly makes sense in this case, in that 1) the library is not moving very fast, and 2) the module only exposes certain features of the library in any case. This second condition is not true of a project like FCKeditor where an upgrade to the library would presumably add features to the user without any changes from the drupal module.
#14
Sorry this was solved in a duplicate issues: #510660: Move getid3 libary to sites/all/libraries/getid3 and add installation instructions / #222666: GetID3 documentation and installation help
#15