Page MenuHomePhabricator

maintenance/edit.php lacks instructions or usage message
Closed, DeclinedPublic

Description

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.


Version: 1.17.x
Severity: normal

Details

Reference
bz25630

Event Timeline

bzimport raised the priority of this task from to Medium.Nov 21 2014, 11:13 PM
bzimport set Reference to bz25630.
bzimport added a subscriber: Unknown Object (MLST).

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