From 613c85ad6e2d355ad2cf76e00f773888036d2e28 Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Thu, 30 Oct 2014 11:42:27 -0700 Subject: [PATCH] Plugin docs overhaul tweaks through "duplicates" Moving alphabetically through the docs. Got a long way to go... --- docs/Makefile | 6 ++++- docs/plugins/bpd.rst | 19 ++++++++------- docs/plugins/bucket.rst | 27 +++++++++++---------- docs/plugins/chroma.rst | 8 +++++-- docs/plugins/convert.rst | 33 +++++++++++++------------ docs/plugins/duplicates.rst | 48 +++++++++++++++++++------------------ docs/refresh_safari.js | 21 ++++++++++++++++ 7 files changed, 99 insertions(+), 63 deletions(-) create mode 100644 docs/refresh_safari.js diff --git a/docs/Makefile b/docs/Makefile index 3c8aa63d6..fd4676f6b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -17,7 +17,7 @@ PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest auto help: @echo "Please use \`make ' where is one of" @@ -38,6 +38,10 @@ help: @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" +# My magical rebuilding, Safari-reloading auto target. +auto: + watchmedo shell-command --patterns='*.rst' --ignore-pattern='_build/*' --recursive --command='make html ; osascript -l JavaScript refresh_safari.js' --wait + clean: -rm -rf $(BUILDDIR)/* diff --git a/docs/plugins/bpd.rst b/docs/plugins/bpd.rst index 4d87ebe13..b5082b220 100644 --- a/docs/plugins/bpd.rst +++ b/docs/plugins/bpd.rst @@ -70,16 +70,17 @@ on your headless server box. Rad! Configuration ------------- -Available options are pretty self-explanatory: +To configure the plugin, make a ``bpd:`` section in your configuration file. +The available options are: -- ``host`` - Default: ``u''`` -- ``port`` - Default: ``6600`` -- ``password`` - Default: ``u''`` -- ``volume``: initial volume in percent - Default: ``100`` +- ``host``: + Default: Bind to all interfaces. +- ``port``: + Default: 6600 +- ``password``: + Default: No password. +- ``volume``: Initial volume, as a percentage. + Default: 100 Here's an example:: diff --git a/docs/plugins/bucket.rst b/docs/plugins/bucket.rst index 3b96866aa..a325d4552 100644 --- a/docs/plugins/bucket.rst +++ b/docs/plugins/bucket.rst @@ -1,5 +1,5 @@ Bucket Plugin -============== +============= The ``bucket`` plugin groups your files into buckets folders representing *ranges*. This kind of organization can classify your music by periods of time @@ -38,19 +38,20 @@ The definition of a range is somewhat loose, and multiple formats are allowed: Configuration ------------- -Available options: +To configure the plugin, make a ``bucket:`` section in your configuration file. +The available options are: -- ``bucket_alpha``: ranges to use for all substitutions occuring on textual +- ``bucket_alpha``: Ranges to use for all substitutions occurring on textual fields. - Default: ``[]`` -- ``bucket_alpha_regex``: list of ``key: value`` (one per line) with 'key' - being one of the `bucket_alpha` range and 'value' a regex that override - original range definition. - Default: ``{}`` -- ``bucket_year``: ranges to use for all substitutions occuring on the + Default: none. +- ``bucket_alpha_regex``: A ``range: regex`` mapping (one per line) where + ``range`` is one of the `bucket_alpha` range and ``value`` is a regex that + override original range definition. + Default: none. +- ``bucket_year``: Ranges to use for all substitutions occurring on the `$year` field. - Default: ``[]`` -- ``extrapolate`` : activate it when you want to group your files into multiple + Default: none. +- ``extrapolate``: Enable this if you want to group your files into multiple year ranges without enumerating them all. This option will generate year bucket names by reproducing characteristics of declared buckets. Default: ``no`` @@ -64,6 +65,6 @@ Here's an example:: bucket_alpha_regex: 'A - D': ^[0-9a-dA-D…äÄ] -The above configuration creates five-year ranges for any input year. +THis configuration creates five-year ranges for any input year. The *A - D* bucket now matches also all artists starting with ä or Ä and 0 to 9 -and … (three dots). The other alpha buckets work as ranges. +and … (ellipsis). The other alpha buckets work as ranges. diff --git a/docs/plugins/chroma.rst b/docs/plugins/chroma.rst index 3640e642b..c770fe698 100644 --- a/docs/plugins/chroma.rst +++ b/docs/plugins/chroma.rst @@ -105,8 +105,12 @@ written to files' metadata. Configuration ------------- -The only option is **auto**, set it to 'no' to disable fingerprinting on -import. +There is one configuration option in the ``chroma:`` section, ``auto``, which +controls whether to fingerprint files during the import process. To disable +fingerprint-based autotagging, set it to ``no``, like so:: + + chroma: + auto: no Submitting Fingerprints ----------------------- diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst index 9876507be..a2ddeb10c 100644 --- a/docs/plugins/convert.rst +++ b/docs/plugins/convert.rst @@ -50,35 +50,38 @@ them. Configuration ------------- -Available options: +To configure the plugin, make a ``convert:`` section in your configuration +file. The available options are: -- ``auto``: set it to ``yes`` to import transcoded versions of your files - automatically during the ``import`` command. With this option enabled, the - importer will transcode all non-MP3 files over the maximum bitrate before - adding them to your library. +- ``auto``: Import transcoded versions of your files automatically during + imports. With this option enabled, the importer will transcode all (in the + default configuration) non-MP3 files over the maximum bitrate before adding + them to your library. Default: ``no``. -- ``dest``: the directory where the files will be converted (or copied) to. - Default: ``None`` -- ``embed`` indicates whether or not to embed album art in converted items. - Default: ``yes``. -- ``max_bitrate``: all lossy files with a higher bitrate will be +- ``dest``: The directory where the files will be converted (or copied) to. + Default: none. +- ``embed`` Embed album art in converted items. Default: ``yes``. +- ``max_bitrate``: All lossy files with a higher bitrate will be transcoded and those with a lower bitrate will simply be copied. Note that this does not guarantee that all converted files will have a lower bitrate---that depends on the encoder and its configuration. -- ``never_convert_lossy_files``: cross-conversions between lossy codecs---such + Default: none. +- ``never_convert_lossy_files``: Cross-conversions between lossy codecs---such as mp3, ogg vorbis, etc,---makes little sense as they will decrease quality even further. If set to ``yes``, lossy files are always copied. - Default: ``no`` -- ``paths``: lets you specify the directory structure and naming scheme for the + Default: ``no``. +- ``paths``: Lets you specify the directory structure and naming scheme for the converted files. Use the same format as the top-level ``paths`` section (see :ref:`path-format-config`). By default, the plugin reuses your top-level path format settings. -- ``quiet``: prevents the plugin from announcing every file it processes. +- ``quiet``: Prevent the plugin from announcing every file it processes. Default: ``false``. -- ``threads``: number of threads to use for parallel encoding. +- ``threads``: The number of threads to use for parallel encoding. By default, the plugin will detect the number of processors available and use them all. +You can also configure the format to use for transcoding. + .. _convert-format-config: Configuring the transcoding command diff --git a/docs/plugins/duplicates.rst b/docs/plugins/duplicates.rst index 3cf99a1ed..08379451f 100644 --- a/docs/plugins/duplicates.rst +++ b/docs/plugins/duplicates.rst @@ -36,46 +36,48 @@ duplicates themselves via command-line switches :: Configuration ------------- -Available options (mirroring the CLI ones): +To configure the plugin, make a ``duplicates:`` section in your configuration +file. The available options mirror the command-line options: -- ``album``: lists duplicate albums instead of tracks. +- ``album``: List duplicate albums instead of tracks. Default: ``no``. -- ``checksum``: enables the use of any arbitrary command to compute a checksum - of items. It overrides the ``keys`` option the first time it is run; however, - because it caches the resulting checksum as ``flexattrs`` in the database, - you can use ``--keys=name_of_the_checksumming_program any_other_keys`` (or - set configuration ``keys``option) the second time around. +- ``checksum``: Use an arbitrary command to compute a checksum + of items. This overrides the ``keys`` option the first time it is run; + however, because it caches the resulting checksum as ``flexattrs`` in the + database, you can use ``--keys=name_of_the_checksumming_program + any_other_keys`` (or set configuration ``keys`` option) the second time + around. Default: ``ffmpeg -i {file} -f crc -``. -- ``copy``: takes a destination base directory into which it will copy matched +- ``copy``: A destination base directory into which to copy matched items. + Default: none (disabled). +- ``count``: Print a count of duplicate tracks or albums in the format + ``$albumartist - $album - $title: $count`` (for tracks) or ``$albumartist - + $album: $count`` (for albums). Default: ``no``. -- ``count``: prints a count of duplicate tracks or albums, with ``format`` - hard-coded to ``$albumartist - $album - $title: $count`` or ``$albumartist - - $album: $count`` (for the ``-a`` option). - Default: ``no``. -- ``delete``: removes matched items from the library and from the disk. +- ``delete``: Removes matched items from the library and from the disk. Default: ``no`` -- ``format``: lets you specify a specific format with which to print every track - or album. This uses the same template syntax as beets - ’:doc:`path formats`. The usage is inspired by, and +- ``format``: A specific format with which to print every track + or album. This uses the same template syntax as beets' + :doc:`path formats`. The usage is inspired by, and therefore similar to, the :ref:`list ` command. Default: :ref:`list_format_item` -- ``full``:lists every track or album that has duplicates, not just the +- ``full``: List every track or album that has duplicates, not just the duplicates themselves. Default: ``no``. -- ``keys``: defines in which track or album fields duplicates are to be +- ``keys``: Define in which track or album fields duplicates are to be searched. By default, the plugin uses the musicbrainz track and album IDs for this purpose. Using the ``keys`` option (as a YAML list in the configuration file, or as space-delimited strings in the command-line), you can extend this behavior to consider other attributes. Default: ``[mb_trackid, mb_albumid]`` -- ``move``: takes a destination base directory into which it will move matched +- ``move``: A destination base directory into which it will move matched items. + Default: none (disabled). +- ``path``: Output the path instead of metadata when listing duplicates. Default: ``no``. -- ``path``: convenience wrapper for ``-f \$path``. - Default: ``no``. -- ``tag``: takes a ``key=value`` string, and adds a new ``key`` attribute with - ``value`` value as a flexattr to the database. +- ``tag``: A ``key=value`` pair. The plugin will add a new ``key`` attribute + with ``value`` value as a flexattr to the database for duplicate items. Default: ``no``. Examples diff --git a/docs/refresh_safari.js b/docs/refresh_safari.js new file mode 100644 index 000000000..8678a3664 --- /dev/null +++ b/docs/refresh_safari.js @@ -0,0 +1,21 @@ +var safari = Application('com.apple.Safari'); +safari.strictPropertyScope = true; +safari.strictCommandScope = true; + +for (var i = 0; i < safari.windows.length; ++i) { + var win = safari.windows[i]; + var tabs = win.tabs; + if (Object.keys(tabs).length) { + for (var j = 0; j < win.tabs.length; ++j) { + var tab = win.tabs[j]; + var url = tab.url(); + if (url.indexOf("file:") == 0) { + // A local file URL. + console.log(url); + tab.url = url; // Refresh. + } + } + } +} + +'done';