User Guide Document Restructuring Proposal

There has been a request (Issue #40) 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. Contributing to the Project [about_picard/contributing.rst]
3. Acknowledgements [about_picard/acknowledgements.rst]
   1. Editor [about_picard/acknowledgements.rst]
   2. Translation Teams [about_picard/acknowledgements.rst]
   3. Contributors [about_picard/acknowledgements.rst]
4. Glossary of Terms [about_picard/glossary.rst]

Part 2 - Getting Started

1. Download & Install Picard [getting_started/download.rst]
2. Main Screen [getting_started/screen_main.rst]
3. 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. Configuration [config/configuration.rst]
   1. Screen Setup [config/configuration.rst]
   2. Action Options [config/configuration.rst]
   3. 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]

Part 3 - Using Picard (Basic)

1. General Usage [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]
2. Workflow Recommendations [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]

Part 4 - Using Picard (Advanced)

1. Other Picard Tasks [usage/other.rst]
   1. Attaching a disc id to a release [usage/attach_disc_id.rst]
   2. Submitting acoustic fingerprints [usage/submit_acoustid.rst]
   3. Generating tags from file names [usage/tags_from_file_names.rst]
2. Extending Picard [extending/extending.rst]
   1. Plugins [extending/plugins.rst]
   2. Scripts [extending/scripts.rst]
      1. File Naming Script [extending/scripts.rst]
      2. Tagging Scripts [extending/scripts.rst]
3. Scripting [extending/scripting.rst]
   1. Syntax [extending/scripting.rst]
   2. Metadata Variables [extending/scripting.rst]
   3. Scripting Functions [extending/scripting.rst]
4. Tutorials [NEW]
   1. Writing a file naming script [tutorials/naming_script.rst]
   2. Understanding acoustic fingerprinting and AcoustIDs [tutorials/acoustid.rst]

Part 5 - Developing Plugins for Picard

1. Processing Order of Plugins and Scripts [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]
2. Picard's Plugins API [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]
3. Tutorials [NEW]
   1. Developing a basic plugin [tutorials/write_plugin.rst]

Part 6 - 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 7 - 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 8 - Appendices

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 9 - Index

1. Index [Auto Generated]