diff --git a/docs/plugins/parentwork.rst b/docs/plugins/parentwork.rst index 1aea9e9ff..cc3f21c0c 100644 --- a/docs/plugins/parentwork.rst +++ b/docs/plugins/parentwork.rst @@ -18,22 +18,24 @@ example, all the movements of a symphony. This plugin aims to solve this problem by also fetching the parent work, which would be the whole symphony in this example. -It uses the ``mb_workid`` tag to retrieve the *parent work* and stores the -``mb_workid`` as ``parentwork_workid_current``. When one executes -``beet parentwork`` it checks if ``mb_workid`` has changed by comparing it -with ``parentwork_workid_current``, if it has changed or if ``force`` is -enabled it fetches the *parent work* again. +The plugin can detect changes in ``mb_workid`` so it knows when to re-fetch +other metadata, such as ``parentwork``. To do this, when it runs, it stores a +copy of ``mb_workid`` in the bookkeeping field ``parentwork_workid_current``. +At any later run of ``beet parentwork`` it will check if the tags +``mb_workid`` and ``parentwork_workid_current`` are still identical. If it is +not the case, it means the work has changed and all the tags need to be +fetched again. This plugin adds six tags: - **parentwork**: The title of the parent work. -- **mb_parentworkid**: The musicbrainz id of the parent work. +- **mb_parentworkid**: The MusicBrainz id of the parent work. - **parentwork_disambig**: The disambiguation of the parent work title. - **parent_composer**: The composer of the parent work. - **parent_composer_sort**: The sort name of the parent work composer. - **work_date**: The composition date of the work, or the first parent work that has a composition date. Format: yyyy-mm-dd. -- **parentwork_workid_current**: The Musicbrainz id of the work as it was when +- **parentwork_workid_current**: The MusicBrainz id of the work as it was when the parentwork was retrieved. This tag exists only for internal bookkeeping, to keep track of recordings whose works have changed. @@ -53,5 +55,5 @@ configuration file. The available options are: Default: ``no`` - **auto**: If enabled, automatically fetches works at import. It takes quite - some time, because beets is restricted to one musicbrainz query per second. + some time, because beets is restricted to one MusicBrainz query per second. Default: ``no``