.. -*- 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.

The ``mw-serve-ctl`` command
============================


``--purge-cache=HOURS``

  Remove 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.

``--clean-up``

  Report errors for processes that have died irregularly.


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

