Discuss active versus working copies

It doesn't have anything to do with versioning. Working files are files that have been uploaded, but not saved or published yet. With Attachment, you add a file, hit add and it uploads the file, updates the edit form of the node, but you haven't actually saved or published the node yet. If you were to abandon working on the node, the working file wouldn't ever get promoted to active, and would eventually be cleaned up (deleted). When you do save and publish your node, it gets promoted to active, and thus saved permanently.

It's a very temporary state and has nothing to do with versioning (which really isn't currently a feature, but I just entered a thread for that if you have any input: http://drupal.org/node/173402 ).

If you'd like to read the code in detail and update the docs after you understand the API, feel free to do so, I'll review and apply the patch. I'm not the origional writer of the code, so I'm not 100% up on all the details of the API yet. I've only been working with the code for about 2 months, and only because it was abandoned and I needed it updated to 5.x for a site upgrade. So, don't expect miracle answers from me. That said, feel free to ask a question, perhaps between the two of us we can figure it all out.

Thanks,
- Steve

Unfortunately I don't have the time to read through all the code and fully understand all the details. I thought this module would be the best bet for me to finish a project I'm working on the fastest. Unfortunately, the documentation for this module is severely lacking and disorganized. While I understand you are new to this project, I don't "expect miracles" from you. I'm frankly a little insulted by your response to this issue.

Since you understood my question and managed to answer it completely, I'm merely asking that you add this information into the README. I'm probably not the first person to have this question and I'm sure I won't be the last. It would also take quite a lot of work to read through this module and determine what took you 5 seconds to tell me and should be documented since this is an API module.

Susurrus,

I'm sorry I insulted you. I answered your question. I did it quickly. I did it concisely. I suggested that perhaps the two of us could work together to understand the API as the original author intended it to be used and use our knowledge to fix the fact that there's a miserable lack of documentation on this module. I apologize to you for the insult; there was none intended.

Have a nice day,
- Steve

I understand that you meant no insult, I just misunderstood what you were saying.

I would definitely like to help out with documenting, but as of now my knowledge of this module is extremely minimal. I'm also having issues with the uploading process in general and being able to check if a file was uploaded without replicating the same process within filemanager (which seems impossible as filemanager_add_upload() calls file_check_upload(), but doesn't test its return value.

As of right now I think that just reorganizing the documentation would help significantly. Documentation is currently located in the following places:
README.txt, INSTALL, doc/filemanager.php, filemanager.module

I think that it would be great to reorganize this structure a little better:
1 - remove doc folder and filemanager.php
2 - Leave just the description of this module in the README.txt
3 - Move the Important Notes section from INSTALL to README.txt
4 - Move the example code and descriptions from doc/filemanager.php to README.txt
5 - Add information about working versus active files to README.txt
5 - Update INSTALL to Drupal 5 instructions or remove it completely as there is probably little to say about the install

What ends up happening is most everything is moved to README.txt, where I think everything belongs. I like having documentation in as few locations as possible.

General README.txt structure

- Module Description
- Overview of how filemanager works (includes difference between active/working files)
- Filemanager API explanation/code examples
- FAQ/Important Notes section

Not checking the return value could be a bug. Don't know though not having looked at it. At the very least it is sloppy coding practice.... or possibly something in the Drupal API changed over the versions and that call didn't get updated.

For some usage example, you might want to look at Attachment if you haven't already. AFAIK, it is the only module that uses Filemanager anymore (a few others used it but dropped it since it was abandoned and not updated to 5.x).

Note that Attachment has to do some double checking also: it maintains a DB table of its own so has to do some of its own checking.

BTW, as you're using Filemanager as an API, please look at http://drupal.org/node/173402 You might have some input on the revisions feature I'm proposing.

Thanks,
- Steve