.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MVS 1p" .TH MVS 1p "2011-02-12" "perl v5.10.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" mvs \- A command line Mediawiki client .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& mvs [Options] command [Options] [filename] \& \& mvs \-h|\-\-help \& mvs \-\-version \& mvs \-D \& \& mkdir wikistuff \& cd wikistuff \& \& mvs login [\-q|\-v] [\-T] [\-d ] [\-l language_code ] [\-u ] [\-p ] [\-w ] \& \& mvs update [\-q|\-v] [ ..] \& mvs up [[\-q|\-v] ..] \& \& mvs commit [\-q|\-v] [\-M] [\-W] \-m "commit message" \& mvs com [\-q|\-v] [\-M] [\-W] \-m "commit message" \& mvs preview [\-q|\-v] [\-M] [\-W] [\-m "commit message"] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`mvs\*(C'\fR is a command line client whose purpose is to simplify offline editing of Wiki content. It allows you to get any number of pages from a given Mediawiki site, edit the pages with any editor, get and merge any concurrent updates of the pages, and then safely commit the users own changes back to the version of the page on the server. .PP The \f(CW\*(C`mvs\*(C'\fR commands which take a filename argument only accept a single filename as so to avoid taking up too much server bandwidth. .PP \&\fBNote:\fRUsers of \f(CW\*(C`mvs\*(C'\fR from before version 0.27 will notice that in this documentation the options are mostly listed after the \f(CW\*(C`mvs\*(C'\fR sub-command. This makes \f(CW\*(C`mvs\*(C'\fR behave more like \f(CW\*(C`cvs\*(C'\fR, \f(CW\*(C`svn\*(C'\fR, or \f(CW\*(C`tla\*(C'\fR, and so should make it easier for people who are used to using those programs. If you prefer to use \f(CW\*(C`mvs\*(C'\fR the old way, that will still work, at least for the next few versions. .SH "QUICKSTART" .IX Header "QUICKSTART" .SS "Step 1: Create an account on the Mediawiki server." .IX Subsection "Step 1: Create an account on the Mediawiki server." This should be done the normal way, by visiting the Mediawiki website to which you want to contribute and creating a new account, setting the preferences, etc. .PP It should hopefully go without saying that you will want to become familiar with the editorial, usage, and copyright guidelines of the site. You should probably also make some contributions through the normal \s-1UI\s0, and learn about following recent changes before contributing using mvs. .PP In addition for the sake of this test you should already have a user page like User: with something on it, where is the user name with which you established the account. .SS "Step 2: Create a working directory" .IX Subsection "Step 2: Create a working directory" \&\f(CW\*(C`mvs\*(C'\fR works with Mediawiki formatted files with a \f(CW\*(C`.wiki\*(C'\fR extension and which are stored together with server information in a \fIworking directory\fR. You will have to have \fIat least\fR one working directory for each Mediawiki site to which you contribute. .PP Simply use \f(CW\*(C`mkdir\*(C'\fR or the equivalent to make a new directory, and then before cd into that directory. .PP .Vb 2 \& mkdir wikitravel.en \& cd wikitravel.en .Ve .PP All of the operations below should be done from this directory. .ie n .SS "Step 3: Login using ""mvs login""" .el .SS "Step 3: Login using \f(CWmvs login\fP" .IX Subsection "Step 3: Login using mvs login" To use login you will need to know the \fIhost\fRname for the Mediawiki site to which you want to contribute. .PP .Vb 1 \& www.wikitravel.org .Ve .PP Now use the \fIhost\fR with your username and password to login. .PP .Vb 1 \& mvs login \-d www.wikitravel.org \-u \-p \*(Aqsecret\*(Aq .Ve .PP If \f(CW\*(C`mvs\*(C'\fR knows about your Mediawiki host it will set set the \&\f(CW\*(C`wiki_path\*(C'\fR to the correct default for that server. In this case it will also be able to select the language version of that Wiki for you if you specify a \f(CW\*(C`language_code\*(C'\fR: .PP .Vb 1 \& mvs login \-d www.wikitravel.org \-l fr \-u \-p \*(Aqsecret\*(Aq .Ve .PP The code must match the one which your wiki host uses for a given language, and of course the language version must exist for the given host. .PP If your Mediawiki install uses a nonstandard path to the wiki script you can specify it on login. The path to the wiki script is the part of the \&\s-1URL\s0 after the host name, and before the '?': .PP .Vb 5 \& mvs login \e \& \-d www.wikitravel.org \e \& \-u \e \& \-p \*(Aqsecret\*(Aq \e \& \-w \*(Aqmw/wiki.phtml\*(Aq .Ve .PP You can change the edit and action paths in the created .mediawiki file after successful login accordingly. .PP Now anything you submit to the Mediawiki server will be credited to user \&\*(L"\*(R". .PP \&\fB\s-1NOTE:\s0\fR If you have been using an earlier version of \f(CW\*(C`mvs\*(C'\fR you should probably delete the .mediawiki file in your working directory. .ie n .SS "Step 4: Use ""mvs update"" to fetch one or more working files" .el .SS "Step 4: Use \f(CWmvs update\fP to fetch one or more working files" .IX Subsection "Step 4: Use mvs update to fetch one or more working files" You can fetch existing material off of the site, or create new pages with \&\f(CW\*(C`mvs update\*(C'\fR, remembering that your files will need a \f(CW\*(C`.wiki\*(C'\fR extension: .PP .Vb 1 \& mvs update User:.wiki User:/Test_Page.wiki .Ve .PP This should produce the output: .PP .Vb 2 \& U User:.wiki \& A User:/Test_Page.wiki .Ve .PP The U (for Updated) means that User: was found on the server and its contents inserted into the local files. The A (for Added) means that the User:/Test_Page.wiki page does not yet exist on the server, and will be added when you run \f(CW\*(C`mvs commit\*(C'\fR. .PP Note that both of the pages we are working with are within \fIyour\fR User Namespace. It's probably a good idea to restrict yourself to working with such pages while you are experimenting with \f(CW\*(C`mvs\*(C'\fR .SS "Step 5: Edit the files to make corrections and contributions" .IX Subsection "Step 5: Edit the files to make corrections and contributions" Use your favorite text editor to edit the files. You might want to check out this page to see if there is a Mediawiki syntax highlighting file for your editor: .PP .Vb 1 \& http://en.wikipedia.org/wiki/Wikipedia:Syntax_highlighting .Ve .PP Of course if you don't find a highlighting file for you editor you are welcome to create one and submit it to the page above. .ie n .SS "Step 6: Use ""mvs commit"" to submit your changes" .el .SS "Step 6: Use \f(CWmvs commit\fP to submit your changes" .IX Subsection "Step 6: Use mvs commit to submit your changes" When you are done editing a file and would like to submit your changes to the wiki server use \f(CW\*(C`mvs commit\*(C'\fR to do so: .PP .Vb 1 \& mvs commit \-m \*(Aqcommit message\*(Aq User:.wiki .Ve .PP Where 'commit message' is whatever you want to say about the changes you are submitting and why. You must provide a commit message or \f(CW\*(C`mvs commit\*(C'\fR will fail. You might also find that \f(CW\*(C`mvs commit\*(C'\fR fails complaining that the file has changed on the server. If this is the case you will need to use \f(CW\*(C`mvs update\*(C'\fR again to get the most recent changes. .SS "Step 7: Update your wiki files" .IX Subsection "Step 7: Update your wiki files" You can use \f(CW\*(C`mvs update\*(C'\fR again at any time to reconcile any of your files with the most recent changes from the server. Your changes \fIwill not\fR be overwritten, but rather \f(CW\*(C`mvs\*(C'\fR will try to merge any server changes into the files as they exist in your working directory. Note that update and commit only work on one file at a time, as so to help prevent accidents and server congestion. .PP If for some reason there is a conflict, i.e. you and someone else have made changes which appear to be incompatible, and cannot be resolved then your file will contain a \fIconflict message\fR, as detailed in the documentation for \f(CW\*(C`mvs update\*(C'\fR below. You \fImust\fR resolve any conflicts \fIbefore\fR attempting to use \f(CW\*(C`mvs commit\*(C'\fR on the file. This is usually a very simple matter of choosing one version of the change or another. You should use your best judgement, consulting the relevant \f(CW\*(C`Talk:\*(C'\fR page to try to work out an agreement with the other contributor in cases where you just simply disagree. .SS "Repeat" .IX Subsection "Repeat" You can continue editing and committing changes with the files in your working directory. It might be a good idea for you to eventually create multiple working directories per site, perhaps grouping them by subject. This will work fine with \f(CW\*(C`mvs\*(C'\fR since it does \fInot\fR need to have a complete copy of all of the pages from a given server in a given working directory to work. .SH "CHARACTER ENCODING" .IX Header "CHARACTER ENCODING" All of your \f(CW\*(C`.wiki\*(C'\fR files should be stored with \s-1UTF\-8\s0 encoding. Upon login to a given server mvs will determine the encoding used by that server, and will upload in that encoding only. For servers using non\-UTF\-8 character sets you should use \s-1HTML\s0 entities for any character you want to represent which is outside of the server's character set. This includes the english Wikipedia. Most newer Mediawiki sites however do use \s-1UTF\-8\s0, on these sites \s-1HTML\s0 entities are \fInever\fR needed. .SH "ARGUMENTS" .IX Header "ARGUMENTS" .SS "Commands" .IX Subsection "Commands" The first argument after the options should be one of the following two commands: .IP "mvs login" 4 .IX Item "mvs login" Allows the user to login to the Mediawiki server using an \fIexisting\fR login and password for that server. After calling \f(CW\*(C`login\*(C'\fR all \f(CW\*(C`commit\*(C'\fRs from the same working directory will be logged as from the logged-in user. .IP "mvs update" 4 .IX Item "mvs update" Updates the specified file[s] with content from the Mediawiki server. If a file does not exist it is created and populated with the current online version. If there is no online version, the file either created and left blank, or just left as it is. If there is content in both the specified file and in the corresponding Wiki page, an attempt is made to merge the two, line by line. Files which are the same as the server version are ignored. .Sp If no filenames are given on the command line, all visible files with the \&.wiki extension are processed. .Sp Conflicting changes to a given line are detected on the basis of the date of the most recent update of the local file and date of the most recent change to the online Wiki page. If a line has changed in both the online page and the local file it is flagged as a conflict, as in \s-1CVS\s0, but with a slightly different syntax: .Sp .Vb 1 \& ********************Start of conflict 1 Insert to Primary, Insert to Secondary ************************************************************ \& \& The line as it appears on the server \& \& **************************************************************************************************** \& \& The line as it appears locally \& ********************End of conflict 1******************************************************************************** .Ve .Sp \&\f(CW\*(C`mvs update\*(C'\fR reports the status of files which it touches to \s-1STDERR\s0 with a letter indicating the file status, and then name of the file, again like \&\s-1CVS\s0. The status letters are: .RS 4 .IP "= (Unchanged)" 4 .IX Item "= (Unchanged)" The file is the same as the page on the server. .IP "A (Added)" 4 .IX Item "A (Added)" The file will become a new page on the wiki server. .IP "M (Modified)" 4 .IX Item "M (Modified)" The file has been modified locally. .IP "U (Updated)" 4 .IX Item "U (Updated)" The file has been updated with changes from the wiki server. .IP "C (Conflicts)" 4 .IX Item "C (Conflicts)" The file contains conflict markers. .IP "? (Unknown)" 4 .IX Item "? (Unknown)" Neither the file, nor a corresponding server page exist. .RE .RS 4 .RE .IP "commit" 4 .IX Item "commit" Commits any changes in the specified local file to the Wiki site. A check is made first to make sure that there are no changes on the server more recent than the most recent update. Nothing will be comitted if the file and server version are identical. .Sp When running \f(CW\*(C`mvs commit\*(C'\fR you \fImust\fR use the \f(CW\*(C`\-m\*(C'\fR flag to send a commit message to the Mediawiki server. e.g.: .Sp .Vb 1 \& mvs commit \-m \*(AqAdded Hotel Eldorado\*(Aq Paris.wiki .Ve .IP "preview" 4 .IX Item "preview" This command functions identically to \f(CW\*(C`mvs commit\*(C'\fR, except that nothing is actually committed. Instead, the file is uploaded and the Mediawiki server sends back a formatted preview. The \f(CW\*(C`\-m\*(C'\fR flag is optional. If you set the \s-1MVS_BROWSER\s0 environmental variable to the path and filename of your favorite browser, mvs will launch it with the preview page. .IP "clean" 4 .IX Item "clean" This command removes any local version reference files relating to pages you've deleted. .Sp .Vb 2 \& rm Paris.wiki \& mvs clean .Ve .SS "File names" .IX Subsection "File names" Any additional arguments are taken as \fIlocal\fR filenames to be processed. The local filename of a given Mediawiki page will be the same as its \s-1URL\s0 encoded name with the extension \*(L".wiki\*(R". If no arguments are given then any filenames with the \*(L"wiki\*(R" extension and under the current directory are processed. .SH "OPTIONS" .IX Header "OPTIONS" .SS "\-h" .IX Subsection "-h" Display usage information. .SS "\-D" .IX Subsection "-D" Print information about known Mediawiki servers, then exit. .SS "\-q" .IX Subsection "-q" Causes the command to be quiet. Informational messages are suppressed. .ie n .SS "\-u """"" .el .SS "\-u ``''" .IX Subsection "-u " Specifies a username for \f(CW\*(C`mvs login\*(C'\fR. .ie n .SS "\-p """"" .el .SS "\-p ``''" .IX Subsection "-p " Specifies a password for \f(CW\*(C`mvs login\*(C'\fR. .ie n .SS "\-l """"" .el .SS "\-l ``''" .IX Subsection "-l " The language code the wiki server uses to differentiate between language versions. .ie n .SS "\-m """"" .el .SS "\-m ``''" .IX Subsection "-m " A commit message for \f(CW\*(C`mvs commit\*(C'\fR. Use this to explain the nature of your changes. .ie n .SS "\-s """"" .el .SS "\-s ``''" .IX Subsection "-s " Same as \f(CW\*(C`\-m\*(C'\fR .SS "\-\-minor " .IX Subsection "--minor " Choose whether to mark change as a minor edit. The default is to mark changes as minor if the Mediawiki user profile is set to do so by default. Use this when committing a change with \f(CW\*(C`mvs commit\*(C'\fR or previewing with \f(CW\*(C`mvs preview\*(C'\fR. .SS "\-M" .IX Subsection "-M" Same as \f(CW\*(C`\-\-minor yes\*(C'\fR. .SS "\-\-watch " .IX Subsection "--watch " Choose whether to add the edited page to your watchlist. Specifying \&\f(CW\*(C`keep\*(C'\fR will maintain the current watched status. The default is to watch the page if it is already being watched, or if the Mediawiki user profile is set to do so by default. Use this when committing a change with \f(CW\*(C`mvs commit\*(C'\fR or previewing with \f(CW\*(C`mvs preview\*(C'\fR. .SS "\-W" .IX Subsection "-W" Same as \f(CW\*(C`\-\-watch yes\*(C'\fR. .ie n .SS "\-w """"" .el .SS "\-w ``''" .IX Subsection "-w " The path on the given \f(CW\*(C`host\*(C'\fR to the Mediawiki script. This defaults to \&\fIwiki/wiki.phtml\fR which is correct for a vanilla install of Mediawiki 1.4.x. .SS "\-v" .IX Subsection "-v" Verbose. If this is set \f(CW\*(C`mvs\*(C'\fR will give you lots of extra information about what it's doing. The \-q flag overrides this. .SH "ENVIRONMENTAL VARIABLES" .IX Header "ENVIRONMENTAL VARIABLES" .SS "\s-1MVS_BROWSER\s0" .IX Subsection "MVS_BROWSER" The browser you prefer to use for previewing changes. .SS "\s-1HTTP_PROXY\s0" .IX Subsection "HTTP_PROXY" A proxy server to use (if any), expressed as a standard \s-1URL\s0, something like this: .PP .Vb 1 \& export HTTP_PROXY=http://[username:password@]proxy.myorg.org:8080 .Ve .SH "CAVEATS" .IX Header "CAVEATS" This is an early version of this program. Future versions may have major differences which will effect your ability to use them interchangeably with this one. In particular the initial \*(L"command\*(R" arguments may become options and the handling of conflicts might change dramatically. .SH "BUGS" .IX Header "BUGS" Please submit bug reports to the \s-1CPAN\s0 bug tracker at . .SH "DISCUSSION" .IX Header "DISCUSSION" There is a discussion list. You can subscribe or read the archives at: .SH "SEE ALSO" .IX Header "SEE ALSO" .SS "Mediawiki" .IX Subsection "Mediawiki" .SS "\s-1CVS\s0" .IX Subsection "CVS" http://www.cvs.org .SH "AUTHORS" .IX Header "AUTHORS" .IP "Mark Jaroski " 4 .IX Item "Mark Jaroski " .PD 0 .IP "Bernhard Kaindl " 4 .IX Item "Bernhard Kaindl " .PD Improved error and usage messages. .IP "Oleg Alexandrov , Thomas Widmann " 4 .IX Item "Oleg Alexandrov , Thomas Widmann " Bug reports and feedback. .IP "Adrian Irving-Beer " 4 .IX Item "Adrian Irving-Beer " Preview support, export support for multi-page update, more 'minor' and 'watch' settings, and bug reports. .SH "COPYRIGHT" .IX Header "COPYRIGHT" (C) Copyright 2004\-2005, Mark Jaroski .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.