Last modified: 2010-10-26 20:09:53 UTC
maintenance/edit.php lacks information on how to use it. It is a shame to have the program not be used because it is not clear how to do so. Please add instructions and usage message. Thank you.
Looks like it has usage information: bawolff@Bawolff-L:/var/www/w/phase3/maintenance$ php edit.php --help Edit an article from the command line, text is from stdin Usage: php edit.php [--a|--b|--conf|--dbpass|--dbuser|--globals|--help|--m|--memory-limit|--no-rc|--quiet|--s|--u|--wiki] <title> a : Enable autosummary b : Bot edit conf : Location of LocalSettings.php, if not default dbpass : The password to use for this script dbuser : The DB user to use for this script globals : Output globals at the end of processing for debugging help : Display this help message m : Minor edit memory-limit : Set a specific memory limit for the script, "max" for no limit or "default" to avoid changing it no-rc : Do not show the change in recent changes quiet : Whether to supress non-error output s : Edit summary u : Username wiki : For specifying the wiki ID <title> : Title of article to edit What more do you want it to say?
First, there should be a comment in the file saying 'for instructions use $ php edit.php --help' Then the should be an example of how one could use it to say add a line at the third line of a file: wget http://en.wikipedia.org/wiki/Food?action=raw -O Food ed Food <<EOF 3i bla bla . w q EOF php edit.php Food < Food Wait, what do I see in getText.php!: * Outputs page text to stdout, useful for command-line editing automation. * Example: php getText.php "page title" | sed -e '...' | php edit.php "page title" Well, if only that example also was there in the edit.php usage message...
(In reply to comment #2) > First, there should be a comment in the file saying 'for instructions use > $ php edit.php --help' That's pretty standard, I think we can presume that people have a basic knowledge of the unix convention that commandName --help gives them help. Failing that they can look at mediawiki wiki where this is also documented. Furthermore just running it without any arguments will also give the help message. > > Then the should be an example of how one could use it to say add a line > at the third line of a file: > > wget http://en.wikipedia.org/wiki/Food?action=raw -O Food > ed Food <<EOF > 3i > bla bla > . > w > q > EOF > php edit.php Food < Food > > Wait, what do I see in getText.php!: > > * Outputs page text to stdout, useful for command-line editing automation. > * Example: php getText.php "page title" | sed -e '...' | php edit.php "page > title" > > Well, if only that example also was there in the edit.php usage message... Perhaps an example would be useful (I added one to http://www.mediawiki.org/wiki/Manual:Edit.php ) on the other hand its not really the job of these help messages to teach basic unix concepts. A person using one of these scripts should (hopefully) know what edit the article given as the last argument with the text from stdin means (but thats just imho).
(In reply to comment #3) Please make sure that both getText.php and edit.php are equally documented in their source code comments: either strip the example from one or add it to the other. I suppose we are to poke around the wiki for where the maintenance commands are documented these days. It would be nice if the URL was embedded in the source, but everybody will remember to look there anyway I suppose, so I suppose never mind. As far as hoping commands have --help options: works until one day you find one that says '--help: no such file or directory' and proceeds to mow through your filesystem... As far as running commands with no options to hope they will tell you how to use them: Bad habit. One day you will find that some programs are not that fancy and just proceed to do things. One day it will happen to you.
(In reply to comment #4) > As far as hoping commands have --help options: works until one day you > find one that says '--help: no such file or directory' and proceeds to > mow through your filesystem... > > As far as running commands with no options to hope they will tell you > how to use them: Bad habit. One day you will find that some programs are > not that fancy and just proceed to do things. One day it will happen to > you. edit.php presents usage information both when called with --help and when called with no arguments, so the bug as filed can be closed. catrope@roanLaptop:~/mediawiki/trunk/phase3$ php maintenance/edit.php Argument <title> required! Edit an article from the command line, text is from stdin Usage: php edit.php [--a|--b|--conf|--dbpass|--dbuser|--globals|--help|--m|--memory-limit|--no-rc|--quiet|--s|--u|--wiki] <title> a : Enable autosummary b : Bot edit conf : Location of LocalSettings.php, if not default dbpass : The password to use for this script dbuser : The DB user to use for this script globals : Output globals at the end of processing for debugging help : Display this help message m : Minor edit memory-limit : Set a specific memory limit for the script, "max" for no limit or "default" to avoid changing it no-rc : Do not show the change in recent changes quiet : Whether to supress non-error output s : Edit summary u : Username wiki : For specifying the wiki ID <title> : Title of article to edit catrope@roanLaptop:~/mediawiki/trunk/phase3$ php maintenance/edit.php --help Edit an article from the command line, text is from stdin Usage: php edit.php [--a|--b|--conf|--dbpass|--dbuser|--globals|--help|--m|--memory-limit|--no-rc|--quiet|--s|--u|--wiki] <title> a : Enable autosummary b : Bot edit conf : Location of LocalSettings.php, if not default dbpass : The password to use for this script dbuser : The DB user to use for this script globals : Output globals at the end of processing for debugging help : Display this help message m : Minor edit memory-limit : Set a specific memory limit for the script, "max" for no limit or "default" to avoid changing it no-rc : Do not show the change in recent changes quiet : Whether to supress non-error output s : Edit summary u : Username wiki : For specifying the wiki ID <title> : Title of article to edit
