translate reference pages from wiki

docs/reference/cli.rst

@@ -1,4 +1,184 @@
 Command-Line Interface
 ======================
 
-cli
+**beet** is the command-line interface to beets.
+
+TODO: global flags
+
+import
+------
+::
+
+    beet import [-CWAPRqst] [-l LOGPATH] DIR...
+    beet import [options] -L QUERY
+
+Add music to your library, attempting to get correct tags for it from
+MusicBrainz.
+
+Point the command at a directory full of music. The directory can be a single
+album or a directory whose leaf subdirectories are albums (the latter case is
+true of typical Artist/Album organizations and many people's "downloads"
+folders). The music will be copied to a configurable directory structure (see
+below) and added to a library database (see below). The command is interactive
+and will try to get you to verify MusicBrainz tags that it thinks are suspect.
+(This means that importing a large amount of music is therefore very tedious
+right now; this is something we need to work on. Read the
+:doc:`autotagging guide </starting/tagger>` if you need help.)
+
+* By default, the command copies files your the library directory and
+  updates the ID3 tags on your music. If you'd like to leave your music
+  files untouched, try the ``-C`` (don't copy) and ``-W`` (don't write tags)
+  options. You can also disable this behavior by default in the
+  configuration file (below).
+
+* Also, you can disable the autotagging behavior entirely using ``-A``
+  (don't autotag) -- then your music will be imported with its existing
+  metadata.
+
+* During a long tagging import, it can be useful to keep track of albums
+  that weren't tagged successfully -- either because they're not in the
+  MusicBrainz database or because something's wrong with the files. Use the
+  ``-l`` option to specify a filename to log every time you skip and album
+  or import it "as-is" or an album gets skipped as a duplicate.
+
+* Relatedly, the ``-q`` (quiet) option can help with large imports by
+  autotagging without ever bothering to ask for user input. Whenever the
+  normal autotagger mode would ask for confirmation, the quiet mode
+  pessimistically skips the album. The quiet mode also disables the tagger's
+  ability to resume interrupted imports.
+
+* Speaking of resuming interrupted imports, the tagger will prompt you if it
+  seems like the last import of the directory was interrupted (by you or by
+  a crash). If you want to skip this prompt, you can say "yes" automatically
+  by providing ``-p`` or "no" using ``-P``. The resuming feature can be
+  disabled by default using a configuration option (see below).
+
+* If you want to import only the *new* stuff from a directory, use the
+  ``-i``
+  option to run an *incremental* import. With this flag, beets will keep
+  track of every directory it ever imports and avoid importing them again.
+  This is useful if you have an "incoming" directory that you periodically
+  add things to.
+
+* By default, beets will proceed without asking if it finds a very close
+  metadata match. To disable this and have the importer as you every time,
+  use the ``-t`` (for *timid*) option.
+
+* The importer automatically tries to download album art for each album it
+  finds. To disable or enable this, use the ``-r`` or ``-R`` options.
+
+* The importer typically works in a whole-album-at-a-time mode. If you
+  instead want to import individual, non-album tracks, use the *singleton*
+  mode by supplying the ``-s`` option.
+
+Reimporting
+^^^^^^^^^^^
+
+The ``import`` command can also be used to "reimport" music that you've already
+added to your library. This is useful for updating tags as they are fixed in the
+!MusicBrainz database, for when you change your mind about some selections you
+made during the initial import, or if you prefer to import everything "as-is"
+and then correct tags later.
+
+Just point the ``beet import`` command at a directory of files that are already
+catalogged in your library. Beets will automatically detect this situation and
+avoid duplicating any items. In this situation, the "copy files" option
+(``-c``/``-C`` on the command line or ``import_copy`` in the config file) has
+slightly different behavior: it causes files to be *moved*, rather than
+duplicated, if they're already in your library. That is, your directory
+structure will be updated to reflect the new tags if copying is enabled; you
+never end up with two copies of the file. That means that the "delete files"
+(``-d`` or ``import_delete``) option is ignored when re-importing as well.
+
+The ``-L`` (``--library``) flag is also useful for retagging. Instead of listing
+paths you want to import on the command line, specify a :doc:`query string
+<query>` that matches items from your library. In this case, the ``-s``
+(singleton) flag controls whether the query matches individual items or full
+albums. If you want to retag your whole library, just supply a null query, which
+matches everything: ``beet import -L``
+
+list
+----
+::
+
+    beet list [-ap] QUERY
+
+:doc:`Queries <query>` the database for music.
+
+Want to search for "Gronlandic Edit" by of Montreal? Try ``beet list
+gronlandic``.  Maybe you want to see everything released in 2009 with
+"vegetables" in the title? Try ``beet list year:2009 title:vegetables``. (Read
+more in :doc:`query`.) You can use the ``-a`` switch to search for
+albums instead of individual items. The ``-p`` option makes beets print out
+filenames of matched items, which might be useful for piping into other Unix
+commands (such as `xargs`_).
+
+.. _xargs: http://en.wikipedia.org/wiki/Xargs
+
+remove
+------
+::
+
+    beet remove [-ad] QUERY
+
+Remove music from your library.
+
+This command uses the same :doc:`query <query>` syntax as the ``list`` command.
+You'll be shown a list of the files that will be removed and asked to confirm.
+By default, this just removes entries from the library database; it doesn't
+touch the files on disk. To actually delete the files, use ``beet remove -d``.
+
+modify
+------
+::
+
+    beet modify [-MWay] QUERY FIELD=VALUE...
+
+Change the metadata for items or albums in the database.
+
+Supply a :doc:`query <query>` matching the things you want to change and a
+series of ``field=value`` pairs. For example, ``beet modify genius of love
+artist="Tom Tom Club"`` will change the artist for the track "Genius of Love."
+The ``-a`` switch operates on albums instead of individual tracks. Items will
+automatically be moved around when necessary if they're in your library
+directory, but you can disable that with ``-M``. Tags will be written to the
+files according to the settings you have for imports, but these can be
+overridden with ``-w`` (write tags, the default) and ``-W`` (don't write tags).
+Finally, this command politely asks for your permission before making any
+changes, but you can skip that prompt with the ``-y`` switch.
+
+move
+----
+::
+
+    beet move [-ca] [-d DIR] QUERY
+
+Move or copy items in your library.
+
+This command, by default, acts as a library consolidator: items matching the
+query are renamed into your library directory structure. By specifying a
+destination directory with ``-d`` manually, you can move items matching a query
+anywhere in your filesystem. The ``-c`` option copies files instead of moving
+them. As with other commands, the ``-a`` option matches albums instead of items.
+
+update
+------
+::
+
+    beet update [-aM] QUERY
+
+Update the library (and, optionally, move files) to reflect out-of-band metadata
+changes and file deletions.
+
+This will scan all the matched files and read their tags, populating the
+database with the new values. By default, files will be renamed according to
+their new metadata; disable this with ``-M``.
+
+stats
+-----
+::
+
+    beet stats [QUERY]
+
+Show some statistics on your entire library (if you don't provide a
+:doc:`query <query>` or the matched items (if you do).

docs/reference/config.rst

@@ -1,4 +1,134 @@
 .beetsconfig
 ============
 
-Config
+The ``beet`` command reads configuration information from ``~/.beetsconfig``.
+The file is in INI format, and the following options are available, all of which
+must appear under the ``[beets]`` section header:
+
+* ``library``: path to the beets library file. Defaults to
+  ``~/.beetsmusic.blb``.
+
+* ``directory``: the directory to which files will be copied/moved when adding
+  them to the library. Defaults to ``~/Music``.
+
+* ``import_copy``: either ``yes`` or ``no``, indicating whether to copy files
+  into the library directory when using ``beet import``. Defaults to ``yes``.
+  Can be overridden with the ``-c`` and ``-C`` command-line options.
+
+* ``import_write``: either ``yes`` or ``no``, controlling whether metadata
+  (e.g., ID3) tags are written to files when using ``beet import``. Defaults to
+  ``yes``. The ``-w`` and ``-W`` command-line options override this setting.
+
+* ``import_delete``: either ``yes`` or ``no``. When enabled in conjunction with
+  ``import_copy``, deletes original files after they are copied into your
+  library. This might be useful, for example, if you're low on disk space -- but
+  it's risky! Defaults to ``no``.
+
+* ``import_resume``: either ``yes``, ``no``, or ``ask``. Controls whether
+  interrupted imports should be resumed. "Yes" means that imports are always
+  resumed when possible; "no" means resuming is disabled entirely; "ask" (the
+  default) means that the user should be prompted when resuming is possible. The
+  ``-p`` and ``-P`` flags correspond to the "yes" and "no" settings and override
+  this option.
+
+* ``import_incremental``: either ``yes`` or ``no``, controlling whether imported
+  directories are recorded and whether these recorded directories are skipped.
+  This corresponds to the ``-i`` flag to ``beet import``.
+
+* ``import_art``: either ``yes`` or ``no``, indicating whether the autotagger
+  should attempt to find and download album cover art for the files it imports.
+  Defaults to ``yes``. The ``-r`` and ``-R`` command-line options override this
+  setting.
+
+* ``import_quiet_fallback``: either ``skip`` (default) or ``asis``, specifying
+  what should happen in quiet mode (see the ``-q`` flag to ``import``, above)
+  when there is no strong recommendation.
+
+* ``import_timid``: either ``yes`` or ``no``, controlling whether the importer
+  runs in *timid* mode, in which it asks for confirmation on every autotagging
+  match, even the ones that seem very close. Defaults to ``no``. The ``-t``
+  command-line flag controls the same setting.
+
+* ``import_log``: specifies a filename where the importer's log should be kept.
+  By default, no log is written. This can be overridden with the ``-l`` flag to
+  ``import``.
+
+* ``art_filename``: when importing album art, the name of the file (without
+  extension) where the cover art image should be placed. Defaults to ``cover``
+  (i.e., images will be named ``cover.jpg`` or ``cover.png`` and placed in the
+  album's directory).
+
+* ``plugins``: a space-separated list of plugin module names to load. For
+  instance, beets includes the [BPD BPD] plugin for playing music.
+
+* ``pluginpath``: a colon-separated list of directories to search for plugins.
+  These paths are just added to ``sys.path`` before the plugins are loaded. The
+  plugins still have to be contained in a ``beetsplug`` namespace package.
+
+* ``threaded``: either ``yes`` or ``no``, indicating whether the autotagger
+  should use multiple threads. This makes things faster but may behave
+  strangely. Defaults to ``yes``.
+
+* ``color``: either ``yes`` or ``no``; whether to use color in console output
+  (currently only in the ``import`` command). Turn this off if your terminal
+  doesn't support ANSI colors.
+
+You can also configure the directory hierarchy beets uses to store music. That
+uses the ``[paths]`` section instead of the ``[beets]`` section. Each string is
+a `Python template string`_ that can refer to metadata fields (see below for
+examples). The extension is added automatically to the end. At the moment, you
+can specify two special paths: ``default`` (for most releases) and ``comp`` (for
+"various artist" releases with no dominant artist). You can also specify a
+different path format for each `MusicBrainz release type`_. The defaults look
+like this::
+
+    [paths]
+    default: $albumartist/$album/$track $title
+    comp: Compilations/$album/$track title
+    singleton: Non-Album/$artist/$title
+
+Note the use of ``$albumartist`` instead of ``$artist``; this ensure that albums
+will be well-organized. (For more about these format strings, see
+:doc:`pathformat`.)
+
+.. _Python template string:
+    http://docs.python.org/library/string.html#template-strings 
+.. _MusicBrainz release type:
+    http://wiki.musicbrainz.org/ReleaseType 
+
+Here's an example file::
+
+    [beets]
+    library: /var/music.blb
+    directory: /var/mp3
+    path_format: $genre/$artist/$album/$track $title
+    import_copy: yes
+    import_write: yes
+    import_resume: ask
+    import_art: yes
+    import_quiet_fallback: skip
+    import_timid: no
+    import_log: beetslog.txt
+    art_filename: albumart
+    plugins: bpd
+    pluginpath: ~/beets/myplugins
+    threaded: yes
+    color: yes
+
+    [paths]
+    default: $genre/$albumartist/$album/$track $title
+    soundtrack: Soundtracks/$album/$track $title
+    comp: $genre/$album/$track $title
+    singleton: Singletons/$artist - $track
+
+    [bpd]
+    host: 127.0.0.1
+    port: 6600
+    password: seekrit
+
+(That ``[bpd]`` section configures the optional :doc:`BPD </plugins/bpd>`
+plugin.)
+
+If you want to store your ``.beetsconfig`` file somewhere else for whatever
+reason, you can specify its path by setting the ``BEETSCONFIG`` environment
+variable.

docs/reference/index.rst

@@ -1,8 +1,12 @@
 Reference
 =========
 
+This section contains reference materials for various parts of beets.
+
 .. toctree::
    :maxdepth: 2
 
    cli
    config
+   pathformat
+   query

docs/reference/pathformat.rst

@@ -0,0 +1,83 @@
+Path Formats
+============
+
+The ``[paths]`` section of the config file (read more on the [Usage] page) lets
+you specify the directory and file naming scheme for your music library. You
+specify templates using Python template string notation---that is, prefixing
+names with ``$`` characters---and beets fills in the appropriate values.
+
+For example, consider this path format string: ``$albumartist/$album/$track
+$title``
+
+Here are some paths this format will generate:
+
+* ``Yeah Yeah Yeahs/It's Blitz!/01 Zero.mp3``
+
+* ``Spank Rock/YoYoYoYoYo/11 Competition.mp3``
+
+* ``The Magnetic Fields/Realism/01 You Must Be Out of Your Mind.mp3``
+
+Note that in path formats, you almost certainly want to use ``$albumartist`` and
+not ``$artist``. The latter refers to the "track artist" when it is present,
+which means that albums that have tracks from different artists on them (like
+`Stop Making Sense`_, for example) will be placed into different folders!
+Continuing with the Stop Making Sense example, you'll end up with most of the
+tracks in a "Talking Heads" directory and one in a "Tom Tom Club" directory. You
+probably don't want that! So use ``$albumartist``.
+
+.. _Stop Making Sense:
+    http://musicbrainz.org/release/798dcaab-0f1a-4f02-a9cb-61d5b0ddfd36.html
+
+As a convenience, however, beets allows ``$albumartist`` to fall back to the value for ``$artist`` and vice-versa if one tag is present but the other is not.
+
+Upgrading from 1.0b6
+--------------------
+
+Versions of beets prior to 1.0b7 didn't use a ``[paths]`` section. Instead, they
+used a single ``path_format`` setting for all music. To support old
+configuration files, this setting is still respected and overrides the default
+path formats. However, the setting is deprecated and, if you want to use
+flexible path formats, you need to remove the ``path_format`` setting and use a
+``[paths]`` section instead.
+
+Possible Values
+---------------
+
+Here's a (comprehensive?) list of the different values available to path
+formats. (I will try to keep it up to date, but I might forget. The current list
+can be found definitively `in the source`_.)
+
+.. _in the source: 
+    http://code.google.com/p/beets/source/browse/beets/library.py#36 
+
+Ordinary metadata:
+
+* title
+* artist
+* album
+* genre
+* composer
+* grouping
+* year
+* month
+* day
+* track
+* tracktotal
+* disc
+* disctotal
+* lyrics
+* comments
+* bpm
+* comp
+
+Audio information:
+
+* length
+* bitrate
+* format
+
+MusicBrainz IDs:
+
+* mb_trackid
+* mb_albumid
+* mb_artistid

docs/reference/query.rst

@@ -0,0 +1,115 @@
+Queries
+=======
+
+Many of beets' :doc:`commands <cli>` are built around **query strings:**
+searches that select tracks and albums from your library. This page explains the
+query string syntax, which is meant to vaguely resemble the syntax used by Web
+search engines.
+
+Keyword
+-------
+
+This command::
+
+    $ beet list love
+
+will show all tracks matching the query string ``love``. Any unadorned word like this matches *anywhere* in a track's metadata, so you'll see all the tracks with "love" in their title, in their album name, in the artist, and so on.
+
+For example, this is what I might see when I run the command above::
+
+    Against Me! - Reinventing Axl Rose - I Still Love You Julie
+    Air - Love 2 - Do the Joy
+    Bag Raiders - Turbo Love - Shooting Stars
+    Bat for Lashes - Two Suns - Good Love
+    ...
+
+Combining Keywords
+------------------
+
+Multiple keywords are implicitly joined with a Boolean "and." That is, if a
+query has two keywords, it only matches tracks that contain *both* keywords. For
+example, this command::
+
+    $ beet ls magnetic tomorrow
+
+matches songs from the album "The House of Tomorrow" by The Magnetic Fields in
+my library. It *doesn't* match other songs by the Magnetic Fields, nor does it
+match "Tomorrowland" by Walter Meego---those songs only have *one* of the two
+keywords I specified.
+
+Specific Fields
+---------------
+
+Sometimes, a broad keyword match isn't enough. Beets supports a syntax that lets
+you query a specific field---only the artist, only the track title, and so on.
+Just say ``field:value``, where ``field`` is the name of the thing you're trying
+to match (such as ``artist``, ``album``, or ``title``) and ``value`` is the
+keyword you're searching for.
+
+For example, while this query::
+
+    $ beet list dream
+
+matches a lot of songs in my library, this more-specific query::
+
+    $ beet list artist:dream
+
+only matches songs by the artist The-Dream. One query I especially appreciate is
+one that matches albums by year::
+
+    $ beet list -a year:2011
+
+Recall that ``-a`` makes the ``list`` command show albums instead of individual
+tracks, so this command shows me all the releases I have from this year.
+
+Phrases
+-------
+
+As of beets 1.0b9, you can query for strings with spaces in them by quoting or escaping them using your shell's argument syntax. For example, this command::
+
+    $ beet list the rebel
+
+shows several tracks in my library, but these (equivalent) commands::
+
+    $ beet list "the rebel"
+    $ beet list the\ rebel
+
+only match the track "The Rebel" by Buck 65. Note that the quotes and
+backslashes are not part of beets' syntax; I'm just using the escaping
+functionality of by shell (bash or zsh, for instance) to pass ``the rebel`` as a
+single argument instead of two.
+
+Path Queries
+------------
+
+Sometimes it's useful to find all the items in your library that are
+(recursively) inside a certain directory. With beets 1.0b9, use the ``path:``
+field to do this::
+
+    $ beet list path:/my/music/directory
+
+In fact, beets automatically recognizes any query term containing a path
+separator (``/`` on POSIX systems) as a path query, so this command is
+equivalent::
+
+    $ beet list /my/music/directory
+
+Note that this only matches items that are *already in your library*, so a path
+query won't necessarily find *all* the audio files in a directory---just the
+ones you've already added to your beets library.
+
+Future Work
+-----------
+
+Here are a few things that the query syntax should eventually support but aren't
+yet implemented. Please drop me a line if you have other ideas.
+
+* "Null" queries. It's currently impossible to query for items that have an
+  empty artist. Perhaps the syntax should look like ``artist:NULL`` or
+  ``artist:EMPTY``.
+
+* Regular expressions. Beets queries are based on simple case-insensitive
+  substring matching, but regexes might be useful occasionally as well. Maybe
+  the syntax should look something like ``re:artist:^.*$`` or, perhaps,
+  ``artist:/^.*$/``. Having regular expressions could help with null queries
+  (above): ``re:artist:^$``.