.. -*- mode: rst; coding: utf-8 -*- ~~~~~~~~~~~~~~ mwlib Commands ~~~~~~~~~~~~~~ Common Options ============== This section contains a description of options that are accepted by more than one command. ``-h, --help`` Show usage information and exit. ``-c, --config=CONFIG`` The value for this option describes the source of MediaWiki articles and images for the command and can be of one of the following types: * A "base URL" of a MediaWiki installation. A base URL is the URL up to, but not including the ``index.php``/``api.php`` part. This URL can differ from the prefix seen in "pretty" article URLs. For example the article *Physics* in the English Wikipedia has the URL http://en.wikipedia.org/wiki/Physics, but the base URL is http://en.wikipedia.org/w/. If you've set up your own MediaWiki you probably know what your base URL should be, but if you're using a different MediaWiki, you can see the base URL if add a query string to the URL, e.g. by clicking on the edit link or by looking at an older revision of an article. This value for ``--config`` corresponds to ``type=mwapi`` in a configuration file (see ``docs/configfiles.txt``), i.e. articles and images are fetched with the `MediaWiki API`_. Specifying the URL directly as value for ``--config`` is usually the quicker way to achieve exactly the same result. This requires MediaWiki 1.11 or later. * A shortcut for a base URL. Currently there are the following shortcuts: - ":en" -- http://en.wikipedia.org/w/, i.e. the English Wikipedia - ":de" -- http://en.wikipedia.org/w/, i.e. the German Wikipedia * A filename of a ZIP file generated with the `the mw-zip Command`_. * A filename of a configuration file (see ``docs/configfiles.txt``). ``-m, --metabook=METABOOK`` Description of the article collection to be rendered in JSON format. This is used by the `Collection extension`_ to transfer this information to ``mw-serve`` which in turn passes the information to ``mw-render`` and ``mw-zip``. ``--collectionpage=COLLECTIONPAGE`` Title of a saved article collection (using the `Collection extension`_) ``-x, --no-images`` If given, no images are included in the output document. ``-i, --imagesize=IMAGESIZE`` Maximum size (which can be either width or height, whichever is greater) of images. If images exceed this maximum size, they're scaled down. ``--template-blacklist=ARTICLE`` A name of an article containing a list of "blacklisted templates", i.e. MediaWiki templates that should be discarded during rendering. Example for such a template blacklist page:: * [[Template:SkipMe]] * [[Template:MeToo]] ``--template-exclusion-category=CATEGORY`` A name of a category: Templates in this cateogry are excluded during rendering. ``--print-template-prefix=PREFIX`` Prefix for "print templates", i.e. templates that are tried to fetch before regular templates. The default value is 'Print' resultint in print template names of the form 'Template:PrintNAME' (with NAME being the name of the original template). ``-o, --output=OUTPUT`` Write output to given file. ``-l, --logfile=LOGFILE`` Log output to the given file. ``-d, --daemonize`` Become a daemon process as soon as possible. This doesn't work on Windows. ``--pid-file=PID_FILE`` To be used together with --daemonize: Write process ID of daemon process to this file. ``--login=USERNAME:PASSWORD[:DOMAIN]`` For MediaWikis that restrict the viewing of pages, login with given USERNAME, PASSWORD and optionally DOMAIN. Currently this is only supported for mwapidb, i.e. when the --config argument is a base URL or shortcut, or when ``type=mwapi`` in the configuration file. ``--num-threads=NUM`` Number of threads to fetch resources in parallel. Set to 0 or use ``--no-threads`` to not use threading. Default is 10. ``--no-threads`` If given, do not use multiple threads to fetch resources in parallel. This overrides ``--num-threads``. ``--title`` Specify a title for the article collection. This is e.g. used by some writers to produce a title page. This title overrides titles contained in ZIP files or metabook files. ``--subtitle`` Specify a subtitle for the article collection. This is e.g. used by some writers to produce a title page (note that subtitle might require a tilte). This subtitle overrides subtitles contained in ZIP files or metabook files. The ``mw-render`` Command ========================= Render MediaWiki articles to one of several output formats like PDF or OpenDocument Text. Usage ----- :: mw-render [OPTIONS] [ARTICLETITLE...] Specific Options ---------------- ``-w, --writer`` Name of the writer to produce the output. The list of available writers can be seen with ``mw-render --list-writers``. ``--list-writers`` List the available writers. ``-W, --writer-options`` Writer specific options in a ";" separated list (depending on your shell, quoting with "..." or '...' might be needed). Each item in that list can either be a single option or an option=value pair. To list the available writer options use ``mw-render --writer-info WRITERNAME``. ``--writer-info=WRITER`` Show available options and some additional information about the given writer. ``-s, --status-file=STATUS_FILE`` Write status/progress information in JSON format to this file. The file is continuously updated during the execution of ``mw-render``. ``-e, --error-file=ERROR_FILE`` If an error occurs, write the error message to this file. If no error occurs this file is not written/created. ``--keep-zip=FILENAME`` Do not remove the (otherwise temporary) ZIP file, but save it under FILENAME. The ``mw-zip`` Command ====================== Generate a ZIP file containing * articles, * images, * templates and * additional meta information (especially if ``--metabook`` is given, see `Common Options`_) like name and URL of the MediaWiki, licensing information and title, subtitle and the hierarchical structure of the article collection. Usage ----- :: mw-zip [OPTIONS] [ARTICLETITLE...] Specific Options ---------------- ``-p, --posturl=POSTURL`` Upload the ZIP file with an HTTP POST request to the given URL. ``-g , --getposturl`` Retrieve the POSTURL from PediaPress and open the upload page in the web browser. The ``mw-post`` Command ======================= Send a ZIP file generated with `the mw-zip command`_ to a given or an automatically retrieved URL via HTTP POST request. Usage ----- :: mw-post [OPTIONS] Specific Options ---------------- ``-i, --input=INPUT`` Filename of ZIP file. ``-p, --posturl=POSTURL`` Upload the ZIP file with an HTTP POST request to the given URL. ``-g , --getposturl`` Retrieve the POSTURL from PediaPress and open the upload page in the web browser. The ``mw-serve`` Command ======================== Provide a server interface to ``mw-render`` and ``mw-zip``. This can be used in conjunction with the `Collection extension`_ to provide PDF generation or the possibility to order printed books from a MediaWiki. Usage ----- :: mw-serve [OPTIONS] Specific Options ---------------- ``-P, --protocol=PROTOCOL`` Protocol to serve. The value can be one of "http", "fcgi" (FastCGI) and "scgi" for multi-process dispatching or one of "http_threaded", "fcgi_threaded" and "scgi_threaded" for multi-thread dispatching. Note: If you want to "serve" CGI instead, use `the mwlib.cgi script`_. ``-p, --port=PORT`` Listen on this TCP port. The default value is 8899. ``-i, --interface=INTERFACE`` Listen on this interface. The default value is "0.0.0.0". ``--cache-dir=CACHE_DIR`` Cache directory. This directory must be writeable by the ``mw-serve`` process. The default ist "/var/cache/mw-serve/". ``--mwrender=MWRENDER`` Path to the ``mw-render`` executable. The default is just "mw-render" which is ok, as long as ``mw-render`` is in the ``PATH``. ``--mwrender-logfile=LOGFILE`` Global logfile for ``mw-render``. The file must be writeable. If this option is not specified, a log file inside the collection directory under --cache-dir is written. ``--mwzip=MWZIP`` Path to the ``mw-zip`` executable. The default is just "mw-zip" which is ok, as long as ``mw-zip`` is in the ``PATH``. ``--mwzip-logfile=LOGFILE`` Global logfile for ``mw-zip``. The file must be writeable. If this option is not specified, a log file inside the collection directory under --cache-dir is written. ``--mwpost=MWPOST`` Path to the ``mw-post`` executable. The default is just "mw-post" which is ok, as long as ``mw-post`` is in the ``PATH``. ``--mwpost-logfile=LOGFILE`` Global logfile for ``mw-post``. The file must be writeable. If this option is not specified, a log file inside the collection directory under --cache-dir is written. ``-q, --queue-dir=QUEUE_DIR`` If specified, do not call ``mw-render`` and ``mw-zip`` but write small job description files in the given QUEUE_DIR directory for later processing by `the mw-watch command`_. ``-m, --method=METHOD`` Whether to use a preforking or a threaded server (values "prefork" and "threaded", default is "prefork"). When ``--protocol=http``, "prefork" the server isn't actually preforking, but just forking. ``--max-requests=NUM`` Maximum number of requests a child process can handle before it gets killed. This setting is irrelevant for ``--method=threaded`` or when ``--protocol=http``. A value of 0 means "no limit". The default is 0. ``--min-spare=NUM``, ``--max-spare=NUM`` Minimum and maximum number of spare processes or threads. Defaults are 2 and 5. ``--max-children=NUM`` Maximum number of processes/threads. This is a hard limit. Default: 50. ``--clean-cache=HOURS`` Clean all cached files in --cache-dir that haven't been touched for the last HOURS hours. This is meant to be run as a cron job. The ``mw-watch`` Command ======================== Work on jobs queued by `the mw-serve command`_. Specific Options ---------------- ``-q, --queue-dir=QUEUE_DIR`` Poll this directory for new job description files. The value must be the same to be given to the ``--queue-dir`` option of ``mw-serve`` to make any sense. Default is "/var/cache/mw-watch/q/". ``-p, --processing-dir=PROCESSING_DIR`` Job description files that are currently being processed are moved from the ``--queue-dir`` directory to this directory. After the processing they are deleted. ``--queued-dir`` and this directory must be on the same filesystem. Default is "/var/cache/mw-watch/p/". ``-n, --num-job=NUM_JOBS`` Maximum number of simultaneous jobs. Default is 5. The ``mwlib.cgi`` Script ======================== This script (located in the ``cgi-bin/`` directory) can be used as a CGI script equivalent for `the mw-serve command`_. Just copy the ``mwlib.cgi`` script to the cgi-bin directory of your web server and adjust the configuration variables located at the top of the file. .. _`MediaWiki API`: http://www.mediawiki.org/wiki/API .. _`Collection extension`: http://www.mediawiki.org/wiki/Extension:Collection