Posted by moshe weitzman on September 10, 2007 at 4:54pm
7 followers
| Project: | Drupal core |
| Version: | 6.x-dev |
| Component: | base system |
| Category: | task |
| Priority: | normal |
| Assigned: | moshe weitzman |
| Status: | closed (won't fix) |
Issue Summary
The README file is the main way that Contrib maintainers document their modules. Yet users often don't read them, leading to loads of installation mistakes and unnoticed features. This patch adds a link to the README if it exists on admin/build/modules, admin/by-module, and admin/build/themes. This is handy for later reading, not just during installation.
The easiest way to test this patch is to add a README file with a bit of dummy text to one of the core module's directories and in a core theme directory. You should then see the link appear.
After this patch goes in, we can discuss whether core modules and themes should have README files. My intent for now is to expose all the great contrib README content in the UI.
| Attachment | Size | Status | Test result | Operations |
|---|---|---|---|---|
| mw_75.patch | 3.44 KB | Ignored: Check issue status. | None | None |
Comments
#1
a screenshot. notice links at end of description.
#2
Sorry, but -1. We already have a mechanism for documenting modules: admin/help/module. Create a help hook that contains the finer points of your README.txt.
#3
A module has to be active in order to show up on that page. But your point stands. I just think we can only fight the flow for so many years. Module authors use README more than admin/help and we might as well go with it. It is just a link, after all.
#4
i should add that installers like drush.module and instal profiles both put modules in your dir that you did not research before downloading. It makes good sense to read the readme before activating them. These links make that easy.
yes this could be a contrib module, but thats a sad outcome, IMO.
#5
It seems for me like useful feature. Thanks.
#6
I tried patch. I had problem to apply patch so I used "patch" without "-p0" parameter.
It works nice. Only problem is that many modules and few themes are using small letters in filename of README. They use "readme.txt" instead of "README.txt" and in such case no link appears. I am not sure if files on MAC OS X are case sensitive, but on linux "README.txt" and "readme.txt" can be two different files.
#7
since README.txt is standard, modules with the lowercase version should probably be treated as buggy I guess.
#8
if someone could tst the patch and then RTBC it if appropriate, that would be great. it is a small patch, so little technical expertise is needed. then the CVS commit team can give their opinion.
#9
Patch applies (with some fuzz and offset) and works with a dummy README.txt . Putting it into the core committer queue.
#10
Well, I somewhat agree with Moshe and Angie.
- README is such a technical "verb", it is not too friendly here (but I don't know better)
- there are several phpdoc issues in the patch (too long line on function oneliner description, @param and @return have text on the same line)
I'd love to hear Dries' opinions.
#11
I fixed the doxygen. Thanks Gabor.
I think the word README is widely understood now. Just like blog and RSS - they are unfortunate words which eventually everyone comes to understand. If someone disagrees, make sure to suggest something better.
#12
+1 to this patch and i agree with gàbor. I know that my opinion is not too important... :)
#13
time to hear Dries' opinion (and others, if you are listening).
#14
fwiw I think just about anyone installing software regularly knows what a README is (and doesn't bother to read it), so +1 to the wording and the patch. A lot of software even sets a checkbox to show the README when you've finished installing it which you then have to uncheck before it comes up in notepad etc. so it's not that obscure.
#15
I'm not a fan of this patch.
First, it promotes the wrong ideas; I'd rather see us get rid of README.txt files and move towards proper documentation. It's too developer-ish.
Second, it is silly. README.txt files are well understood, I don't know any other software linking to their ASCII README.txt from withing the application itself.
I'm marking this "won't fix".