Skip to content

User Guide Document Restructuring Proposal

Jump to bottom
Bob Swift edited this page Aug 22, 2023 · 12 revisions

There has been a request (PICARD-2732) to restructure the Picard User Guide document. This wiki page is intended to provide an outline for the restructured document in a format that others can edit (with the edits tracked) in order to try to achieve some consensus before beginning the actual restructuring work. When modifying this outline, please indicate the file name of any existing content, or NEW if the content needs to be developed.

Picard User Guide

Part 1 - Introduction

  1. Introduction [about_picard/introduction.rst]
    1. Picard can... [about_picard/introduction.rst]
    2. Picard cannot... [about_picard/introduction.rst]
    3. Limitations [about_picard/introduction.rst]
  2. How to use this documentation [NEW]
    1. Basic Picard usage [NEW]
    2. Tag your music your way [NEW]
    3. Advanced Usage [NEW]
  3. How you can Give Something Back [about_picard/contributing.rst]
    1. Documentation [NEW]
    2. Documentation Translations [NEW]
    3. Improving MusicBrainz data [NEW]
    4. User forum support [NEW]
    5. Plugins [NEW]
    6. Picard translations [NEW]
    7. Picard improvements [NEW]
  4. User Guide Acknowledgements [about_picard/acknowledgements.rst]
    1. Editor [about_picard/acknowledgements.rst]
    2. Translation Teams [about_picard/acknowledgements.rst]
    3. Contributors [about_picard/acknowledgements.rst]
  5. Glossary of Terms [about_picard/glossary.rst]

Part 2 - Getting Started

  1. Start using Picard fast [NEW]
  2. Download & Install Picard [getting_started/download.rst]
  3. What Picard looks like [getting_started/screen_main.rst]
    1. Main Screen [getting_started/screen_main.rst]
    2. Status Icons [getting_started/status_icons.rst]
      1. Album / Release Icons [getting_started/status_icons.rst]
      2. Track Icons [getting_started/status_icons.rst]
  4. Minimum configuration [NEW]
    1. Your music library location [NEW]
    2. Any other most minimal configuration [NEW]
  5. How Picard works [usage/using.rst]
    1. Retrieving Album Information [usage/retrieve.rst]
    2. Matching Files to Tracks [usage/match.rst]
    3. Setting the Cover Art [usage/coverart.rst]
    4. Saving Updated Files [usage/save.rst]
  6. How to load files [workflows/workflows.rst]
    1. When the CD is available [workflows/workflow_cd.rst]
    2. When files are grouped by album [workflows/workflow_album.rst]
    3. When files are not grouped but have some metadata [workflows/workflow_metadata.rst]
    4. When files are not grouped and have little or no existing metadata [workflows/workflow_no_info.rst]
  7. Getting metadata from MusicBrainz [NEW]
    1. Tagging from MusicBrainz [NEW]
    2. Loading an Album manually [NEW]
    3. Loading the MusicBrainz webpages [NEW]
    4. Searching [NEW]
  8. Saving your metadata [NEW]
    1. Default file naming [NEW]
    2. Default music library structure [NEW]
    3. Default metadata [NEW]
  9. Changing the downloaded metadata [NEW]
    1. What if you think MusicBrainz has wrong / missing information [NEW]
    2. Getting even more metadata from MusicBrainz [NEW]
    3. Manually editing metadata [NEW]
    4. Scripting changes to metadata [NEW]
    5. Deleting metadata [NEW]
    6. Preserving existing metadata [NEW]
  10. Essential security information [NEW]
    1. Data Picard sends over the internet [NEW]
    2. Data Picard accesses on your computer [NEW]
    3. Executable code [NEW]
    4. Administrative / Root access [NEW]

Part 3 - Tag your music your way

  1. Introduction to metadata [NEW]
    1. What's the point of tagging music files with metadata [NEW]
    2. Albums / Releases [NEW]
    3. Tracks / Recordings [NEW]
    4. Works [NEW]
    5. International character sets [NEW]
    6. Album art [NEW]
    7. Genres [NEW]
    8. Music players [NEW]
  2. Introduction to configuring Picard [NEW]
    1. Options [NEW]
    2. Using Plugins [NEW]
    3. Writing Scripts [NEW]
  3. Picard Options [config/configuration.rst]
    1. Changing the Screen Layout [config/configuration.rst]
    2. Option Settings [config/configuration.rst]
      1. General Options [config/options_general.rst]
      2. Metadata Options [config/options_metadata.rst]
      3. Tag Options [config/options_tags.rst]
      4. Cover Art Options [config/options_cover.rst]
      5. File Naming Options [config/options_filerenaming.rst]
      6. Fingerprinting Options [config/options_fingerprinting.rst]
      7. CD Lookup Options [config/options_cdlookup.rst]
      8. Plugins Options [config/options_plugins.rst]
      9. User Interface Options [config/options_interface.rst]
      10. Scripting Options [config/options_scripting.rst]
      11. Advanced Options [config/options_advanced.rst]
  4. Using Plugins [extending/plugins.rst]
  5. Writing Scripts [extending/scripts.rst]
    1. Tagging Scripts [extending/scripts.rst]
    2. File Naming Script [extending/scripts.rst]
      1. Naming your music files [NEW]
      2. Structuring your music library [NEW]
      3. International character sets [NEW]
      4. Gotchas to avoid [NEW]
    3. Writing a file naming script [tutorials/naming_script.rst]
  6. Scripting [extending/scripting.rst]
    1. Syntax [extending/scripting.rst]
    2. Metadata Variables [extending/scripting.rst]
    3. Scripting Functions [extending/scripting.rst]
  7. Other Picard Functionality [usage/other.rst]
    1. CD DiscIds [usage/attach_disc_id.rst]
      1. Attaching a disc id to a release [usage/attach_disc_id.rst]
    2. Acoustic fingerprints NEW
      1. Understanding acoustic fingerprinting and AcoustIDs [tutorials/acoustid.rst]
      2. Submitting acoustic fingerprints [usage/submit_acoustid.rst]
    3. Generating tags from file names [usage/tags_from_file_names.rst]

Part 4 - Reference Information

  1. Tags & Variables [variables/variables.rst]
    1. Basic Tags [variables/tags_basic.rst]
    2. Advanced Tags [variables/tags_advanced.rst]
    3. Basic Variables [variables/variables_basic.rst]
    4. Advanced Variables [variables/variables_advanced.rst]
    5. File Variables [variables/variables_file.rst]
    6. Classical Music Tags [variables/variables_classical.rst]
    7. Tags from Plugins [variables/variables_plugins.rst]
    8. Other Information [variables/variables_other_information.rst]
  2. Scripting Functions [functions/list_by_type.rst]
    1. Assignment Functions [functions/list_by_type.rst]
    2. Text Functions [functions/list_by_type.rst]
    3. Multi-Value Functions [functions/list_by_type.rst]
    4. Mathematical Functions [functions/list_by_type.rst]
    5. Conditional Functions [functions/list_by_type.rst]
    6. Information Functions [functions/list_by_type.rst]
    7. Loop Functions [functions/list_by_type.rst]
    8. Miscellaneous Functions [functions/list_by_type.rst]
  3. Tag Mapping [appendices/tag_mapping.rst]
  4. Command Line Options [appendices/command_line.rst]

Part 5 - Frequently Asked Questions

  1. Configuration [faq/faq_config.rst]
    1. Where is the Picard configuration saved? [faq/faq_config.rst]
    2. I tagged a file in Picard, but iTunes is not seeing the tags! [faq/faq_config.rst]
    3. My tags are truncated to 30 characters in Windows Media Player! [faq/faq_config.rst]
    4. How do I tell Picard which browser to use? [faq/faq_config.rst]
  2. File Formats [faq/faq_file_formats.rst]
    1. What formats does Picard support? [faq/faq_file_formats.rst]
    2. What formats will Picard support? [faq/faq_file_formats.rst]
    3. Which tags can Picard write to my files? [faq/faq_file_formats.rst]
    4. How do I edit several tags at once? Why is it not easier to do so? [faq/faq_file_formats.rst]
    5. The built-in audio player cannot play my file. Which formats does it support? [faq/faq_file_formats.rst]
    6. I am using Fedora. Why doesn't acoustic fingerprinting work? [faq/faq_file_formats.rst]
  3. Using Picard [faq/faq_usage.rst]
    1. How do I tag files with Picard? [faq/faq_usage.rst]
    2. The green "Tagger" button disappeared from MusicBrainz.org, how do I get it back? [faq/faq_usage.rst]
    3. I'm trying to load a release in Picard but all I'm seeing is "Couldn't load album" errors. What's up? [faq/faq_usage.rst]
    4. I'm using macOS, where are my network folders or drives? [faq/faq_usage.rst]
    5. macOS shows the app is damaged. How can I run Picard? [faq/faq_usage.rst]
    6. Picard is installed on Linux as a Snap. How can I access removable media? [faq/faq_usage.rst]

Part 6 - Troubleshooting

  1. General Troubleshooting [troubleshooting/troubleshooting.rst]
    1. Getting Help [troubleshooting/troubleshooting.rst]
    2. Reporting a Bug [troubleshooting/troubleshooting.rst]
    3. Getting Logs [troubleshooting/troubleshooting.rst]
  2. Picard won't start [troubleshooting/does_not_start.rst]
  3. There is no coverart [troubleshooting/no_coverart.rst]
    1. Picard isn't finding and downloading any cover art [troubleshooting/no_coverart.rst]
    2. Coverart that is saved with the files isn't displayed [troubleshooting/no_coverart.rst]
  4. Tags are not updated or saved [troubleshooting/missing_tags.rst]
  5. Files are not being saved [troubleshooting/not_saving.rst]
  6. Picard just stopped working [troubleshooting/stopped_working.rst]
  7. macOS shows the app is damaged [troubleshooting/macos_startup_error.rst]

Part 7 - Plugin Development

  1. So you have a great idea for a plugin [NEW]
  2. When plugins are called [extending/processing.rst]
    1. Startup [extending/processing.rst]
    2. Loading a Release [extending/processing.rst]
    3. Loading Music Files [extending/processing.rst]
    4. Adding / Removing Files [extending/processing.rst]
    5. Saving Files [extending/processing.rst]
    6. Removing Albums [extending/processing.rst]
    7. Context Menus [extending/processing.rst]
  3. Structure of a plugin [appendices/plugins_api.rst]
    1. Plugin Metadata [appendices/plugins_api.rst]
    2. Metadata Processors [appendices/plugins_api.rst]
    3. Event Hooks [appendices/plugins_api.rst]
    4. File Formats [appendices/plugins_api.rst]
    5. Tagger Script Functions [appendices/plugins_api.rst]
    6. Context Menu Actions [appendices/plugins_api.rst]
  4. Common Plugin functions [NEW]
    1. Accessing Album/Track Metadata [NEW]
    2. Getting additional data from MusicBrainz [NEW]
    3. Getting additional data from other web sites [NEW]
    4. Caching additional data [NEW]
    5. Calling external programs [NEW]
    6. Running tasks in the background [NEW]
    7. Handling Genres [NEW]
    8. Handling album art [NEW]
  5. The plugin development To-Do list [NEW]

Part 8 - Picard Development

  1. You too can improve Picard [NEW]
  2. The Picard development To-Do list [NEW]
  3. MusicBrainz development and other projects [NEW]

Part 9 - Index

  1. Index [Auto Generated]

The MusicBrainz Picard Documentation Project and the Picard User Guide are licensed under CC0 1.0.

Clone this wiki locally