Doxygen: Improve file structure and includes (#6344)

doc/doxygen/extra-pages/developer_documentation/card_database_schema_and_parsing.md

@@ -0,0 +1 @@
+@page card_database_schema_and_parsing Card Database Schema and Parsing

doc/doxygen/extra-pages/developer_documentation/displaying_cards.md

@@ -0,0 +1,83 @@
+@page displaying_cards Displaying Cards
+
+Cockatrice offers a number of widgets for displaying cards. To pick the right one for your purpose, it is first
+important
+to determine the context in which you will be displaying the card.
+
+# In-client
+
+In the client (like in your custom widgets), you can use the existing card display widgets.
+
+## Simple Display
+
+The most general purpose of these is @ref CardInfoPictureWidget, which simply displays a picture of a card.
+
+The textual equivalent to this is @ref CardInfoTextWidget, which displays all the properties of a card in text form.
+
+## Detailed Display
+
+The convenience class @ref CardInfoDisplayWidget displays both of these widgets in a tabbed container, which allows
+choosing between either visual, textual, or both representations at the same time. It is the class that is most
+familiar to our users when a single card is highlighted or inspected, since it is used in the deck editor and in-game
+for these purposes.
+
+If you would like the user to be able to inspect a single card in your custom widget, you should
+expose a @ref CardInfoDisplayWidget to them and incorporate it as a dock widget inside your custom widget.
+
+@ref CardInfoDisplayWidget is great for ensuring that the user has all the relevant details of a card available.
+It is crucial anywhere the user might encounter a card for the first time or needs to make an informed decision.
+
+## Visual Display
+
+However, there is a reason why it is possible to have a visual-only representation of the card in the
+@ref CardInfoDisplayWidget.
+
+Cards are, by design, meant to be represented as images and cards which we can reasonably
+expect the user to know (for example, cards contained in a user made deck or explicitly chosen by the user) can be
+represented with just their image as a sort of "visual shorthand".
+
+The simplest way to do this is of course, the above-mentioned @ref CardInfoPictureWidget which simply displays the
+picture without modifications.
+
+However, there exist a couple of other convenience classes which subclass @ref CardInfoPictureWidget to accomplish some
+things which you might find useful as well.
+
+- @ref CardInfoPictureWithTextOverlayWidget displays text overlaid on top of the card picture and scales this text to
+  fit automatically.
+- @ref DeckPreviewCardPictureWidget is a @ref CardInfoPictureWithTextOverlayWidget which also features a
+  raise-on-mouse-enter animation, controlled by the global setting (TODO: specify which).
+- @ref CardInfoPictureArtCropWidget attempts to display an 'art crop' of the card by cropping the upper region of the
+  card and only displaying that.
+
+## Groups of Cards
+
+Sometimes it is useful to display images of cards in groups, for example to represent the deck in the @ref
+VisualDeckEditorWidget or during confirmation in the pre-game lobby.
+
+To this end, Cockatrice offers three convenience classes to display cards for an index in a @ref DeckListModel in a
+group and one to display all cards in a particular zone of a @ref DeckListModel.
+
+The generic way to do this is @ref CardGroupDisplayWidget, which displays cards in @ref QVBoxLayout. This class is very
+generic and it is probably a better choice to either subclass it or use one of the two existing implementations.
+
+@ref FlatCardGroupDisplayWidget displays cards using a horizontal @ref FlowWidget. This means it will fill available
+screen space, left to right with no margins, with card pictures, skipping to a new line if it overflows available screen
+space horizontally.
+
+@ref OverlappedCardGroupDisplayWidget displays cards using an @ref OverlapWidget, which displays widgets on top of each
+other in vertical columns until it exceeds available screen space in which case it will start a new column. The amount
+of overlap as well as the overlap direction is configurable.
+
+@ref DeckCardZoneDisplayWidget can be used to visualize all cards in a zone with either a @ref
+FlatCardGroupDisplayWidget or a @ref OverlappedCardGroupDisplayWidget and headed by a @ref BannerWidget. It also allows
+grouping and sorting.
+
+# In-game
+
+The in-game view is a @ref QGraphicsScene, which means any widget we want to display inside of it should be a @ref
+QGraphicsObject.
+
+- @ref CardItem
+
+
+

doc/doxygen/extra-pages/developer_documentation/index.md

@@ -0,0 +1,9 @@
+@page developer_reference Developer Reference
+
+- @subpage primer_cards
+
+- @subpage card_database_schema_and_parsing
+- @subpage querying_the_card_database
+
+- @subpage loading_card_pictures
+- @subpage displaying_cards

doc/doxygen/extra-pages/developer_documentation/loading_card_pictures.md

@@ -0,0 +1,52 @@
+@page loading_card_pictures Loading Card Pictures
+
+Pictures associated with CardInfo%s are retrieved either from on-disk or the network through the CardPictureLoader.
+
+In most cases, you don't need to concern yourself with the internals of CardPictureLoader.
+
+Simply using one of the ways described in @ref displaying_cards is enough to automatically queue a request to the
+CardPictureLoader when the chosen widget is shown, emitting signals to refresh the widget when the request is finished.
+
+# How requests are triggered
+
+CardPictureLoader::getPixmap() is called exactly two times in the code base, in CardInfoPictureWidget::loadPixmap(), the
+base class
+for all widget based card picture display, and AbstractCardItem::paintPicture(), the base class for all QGraphicsItem
+based card picture
+display. See @ref displaying_cards for more information on the difference between these two display methods.
+
+Because both of these calls are made in the paintEvent() methods of their respective classes, this means that requests
+are issued as soon as but not before the widget is shown on screen.
+
+It is also possible to "warm up" the cache by issuing card picture load requests to the CardPictureLoader without using
+a display widget and waiting for it to be shown by calling CardPictureLoader::cacheCardPixmaps() with a list of
+ExactCard%s.
+
+# The QPixmapCache and QNetworkDiskCache
+
+Cockatrice uses the QPixmapCache from the Qt GUI module to store card pictures in-memory and the QNetworkDiskCache from
+the Qt Network module to cache network requests for card pictures on-disk.
+
+What this means is that the CardPictureLoader will first attempt to look up a card in the QPixmapCache according to the
+ExactCard::getPixmapCacheKey() method of an ExactCard object. If it does not find it in the in-memory cache, it will
+issue a load request, which will first look for local images on-disk and then consult the QNetworkDiskCache and if
+found, use the stored binary data from the network cache to populate the in-memory pixmap cache under the card's cache
+key. If it is not found, it will then proceed with issuing a network request.
+
+The size of both of these caches can be configured by the user in the "Card Sources" settings page.
+
+# PixmapCacheKeys and ProviderIDs
+
+TODO
+
+# The Redirect Cache
+
+TODO
+
+# Local Image Loading
+
+TODO
+
+# URL Generation and Resolution
+
+TODO

doc/doxygen/extra-pages/developer_documentation/primer_cards.md

@@ -0,0 +1,71 @@
+@page primer_cards A Primer on Cards
+
+# The Cockatrice Card Library
+
+All non-gui code related to cards used by Cockatrice is contained within libcockatrice_card.
+
+# A Basic Card Object: CardInfo
+
+A CardInfo object is the translational unit used by the CardDatabase to represent an on-disk XML entry as an in-memory
+Qt object.
+
+For a complete overview of the fields that define a CardInfo object, see the class documentation and more specifically
+@ref PrivateCardProperties.
+
+These fields correspond to either entries or a combination of entries in the XML card entry to which the
+CardDatabaseParser applies special logic to map, populate or determine their respective values in the CardInfo object.
+
+Any property to which special parsing is not applied is stored in CardInfo::properties and may be retrieved or set with
+CardInfo::getProperty() or CardInfo::setProperty() as well as CardInfo::getProperties() to get a collection of the
+property keys a CardInfo contains.
+
+For more information on how special fields contained within @ref PrivateCardProperties are parsed, see
+CockatriceXml4Parser::loadCardsFromXml().
+
+Apart from access to the basic and extended properties of a card, CardInfo also provides two important mechanisms to us.
+The first is the CardInfo::pixmapUpdated() signal, which allows the CardPictureLoader to signal when it is done
+manipulating (in most cases: loading) the QPixmap of an ExactCard::getPixmapCacheKey(), where the ExactCard::card
+corresponds to this CardInfo object.
+
+Put simply: Whenever the CardPictureLoader loads a new PrintingInfo which is not already in the cache, it emits this
+signal so that any widget using a CardInfo object can update the display of it to possibly use this new QPixmap.
+
+\attention It should be noted that it is not possible to use CardPictureLoader::getPixmap() with anything but an
+ExactCard, which is a CardInfo object associated with a PrintingInfo, i.e. a definitive printing of a specific card
+
+The other signal, CardInfo::cardInfoChanged() conceptually works much the same way, except it is concerned with the
+properties of the CardInfo object.
+
+# Getting specific: PrintingInfo and ExactCard
+
+## Printing Info
+
+A CardInfo object describes the basic properties of a card in much the same way that we say "Two cards with the same
+name are and should be equal if their properties are equal". However, there are certain (mostly visual) properties which
+might differ between printings of a card but still conceptually classify two instances of a card as "the same card".
+The most obvious example to this are cards which fundamentally share all properties except the artwork depicted on the
+card.
+
+We refer to such differences as Printings and track them in the PrintingInfo class. A PrintingInfo is always related to
+the CardSet that introduced the variation. Multiple variations can exist in the same CardSet and the respective
+PrintingInfo::getProperty() can be used to determine the differences, such as the collector numbers on the printings, if
+there are any.
+
+## Exact Card
+
+A CardInfo object is used to hold the functional properties of a card and a PrintingInfo object can be used to hold the
+visual properties of a card. To represent a 'physical' card, as in, a concrete immutable instance of a card, we can use
+ExactCard, which combines a CardInfo and a PrintingInfo object into one class. The class is used as a container around
+CardInfo objects whenever the user (and thus the program) expects to be presented with a defined card printing.
+
+# Using Cards
+
+For more information on the XML database schema which the CardDatabaseParser parses to generate CardInfo objects, see
+@ref card_database_schema_and_parsing.
+
+For more information on querying the CardDatabase for CardInfo objects, see @ref querying_the_card_database.
+
+For more information on displaying CardInfo and ExactCard objects using Qt Widgets, see @ref displaying_cards.
+
+For more information on how card pictures are loaded from disk or the network, see @ref loading_card_pictures as well as
+the CardPictureLoader documentation.

doc/doxygen/extra-pages/developer_documentation/querying_the_card_database.md

@@ -0,0 +1,39 @@
+@page querying_the_card_database Querying the Card Database
+
+# The CardDatabaseQuerier Class
+
+The CardDatabaseQuerier is the only class used for querying the database. The CardDatabase is an in-memory map and thus
+provides no structured query language. CardDatabaseQuerier offers methods to retrieve cards by name, by providerID or in
+bulk, as CardSet%s.
+
+## Obtaining a handle to the CardDatabaseQuerier for usage
+
+To obtain the CardDatabaseQuerier related to the global CardDatabase singleton, use CardDatabaseManager::query().
+
+## Querying for known cards
+
+There are, essentially, two ways to ensure card equality, with the second being optional but necessitating the first.
+These two ways are CardInfo name equality and PrintingInfo provider ID equality.
+
+Because of this, most queries require, at the very least, a card name to match against and optionally a providerID to
+narrow the results.
+
+### Generic Card Infos
+
+To check if a card with the exact provided name exists as a CardInfo in the CardDatabase use,
+CardDatabaseQuerier::getCardInfo() or CardDatabaseQuerier::getCardInfos() for multiple cards.
+
+### Guessing Cards
+
+If the exact name might not be present in the CardDatabase, you can use CardDatabaseQuerier::getCardBySimpleName(),
+which automatically simplifies the card name and matches it against simplified card names in the CardDatabase.
+
+Alternatively, you can use CardDatabaseQuerier::lookupCardByName(), which first attempts an exact match search and then
+uses CardDatabaseQuerier::getCardBySimpleName() as a fallback.
+
+### ExactCard%s
+
+To obtain an ExactCard from the CardDatabaseQuerier, you must use a CardRef as a parameter to
+CardDatabaseQuerier::getCard(), CardDatabaseQuerier::getCards(), or CardDatabaseQuerier::guessCard().
+
+CardRef is a simple struct consisting of a card name and a card provider ID as QString%s.

doc/doxygen/extra-pages/index.md

@@ -0,0 +1,8 @@
+@mainpage Cockatrice Documentation
+
+# Welcome
+
+This is the **main landing page** of the Cockatrice documentation.
+
+- Go to the @subpage user_reference page
+- Or check out the @subpage developer_reference

doc/doxygen/extra-pages/user_documentation/deck_management/creating_decks.md

@@ -0,0 +1,17 @@
+@page creating_decks Creating Decks
+
+Creating a new deck is done using either the \ref editing_decks_classic or \ref editing_decks_visual.
+
+They can be accessed either by clicking the "Create Deck" button in the TabHome screen, which will open the default deck
+editor configured in the "User Interface" -> "Deck editor/storage settings" -> "Default deck editor type" setting, or
+by selecting "Deck Editor" or "Visual Deck Editor" under the "Tabs" application menu located at the top.
+
+# Further References
+
+See @ref editing_decks for information on how to modify the attributes and contents of a deck in the Deck Editor
+widgets.
+
+See @ref exporting_decks for information on how to store and persist your deck either in-client or to external
+services.
+
+See @ref importing_decks for information on how to import existing decks either in-client or from external services

doc/doxygen/extra-pages/user_documentation/deck_management/editing_decks.md

@@ -0,0 +1,7 @@
+@page editing_decks Editing Decks
+
+@subpage editing_decks_classic
+
+@subpage editing_decks_visual
+
+@subpage editing_decks_printings

doc/doxygen/extra-pages/user_documentation/deck_management/editing_decks_classic.md

@@ -0,0 +1,54 @@
+@page editing_decks_classic Classic Deck Editor
+
+\image html classic_deck_editor.png width=900px
+
+# Editing Basic Deck Information
+
+Editing basic deck information is done through the deck dock widget (DeckEditorDeckDockWidget).
+
+\image html deckeditordeckdockwidget.png
+
+This widget allows editing:
+
+- The name
+- The comments
+- The banner card, which is used to represent the deck in the visual deck storage
+- The tags, which are used for filtering in the visual deck storage
+
+# Adding Cards
+
+Adding cards is done using the list of cards in the database presented in the list view on the left.
+
+\image html classic_database_display.png
+
+Cards can be added by either double-clicking an entry, pressing return with an entry selected to add it to the mainboard
+or pressing ctrl/cmd + return to add it to the sideboard.
+
+There are also buttons for these two functions on the right of the search bar above the list view.
+
+\image html classic_database_display_add_buttons.png
+
+# Modifying the Deck List
+
+To modify or remove cards in the deck list, the tree list view in the deck dock widget can be used.
+
+\image html deck_dock_deck_list.png
+
+Just above the list, at the top right, there are four buttons to manipulate the currently selected card(s):
+
+- Increment Card
+- Decrement Card
+- Remove Card
+- Switch Card between Mainboard and Sideboard
+
+\image html deck_dock_deck_list_buttons.png
+
+Additionally, there is a combo box above the list, which may be used to change how cards are grouped in the list
+display. This is only for visual display and does not affect how the list is saved.
+
+\image html deck_dock_deck_list_group_by.png
+
+# Modifying printings
+
+For more information on modifying the printings in a deck see @ref editing_decks_printings
+

doc/doxygen/extra-pages/user_documentation/deck_management/editing_decks_printings.md

@@ -0,0 +1,122 @@
+@page editing_decks_printings Printing Selector
+
+\image html printing_selector.png
+
+# Purpose
+
+The PrintingSelector allows editing the PrintingInfo associated with CardInfo%s contained in DeckList%s.
+
+As described in PrintingInfo, a CardInfo can have different variations contained within the same or different CardSet%s.
+
+PrintingSelector allows the user to choose a variation, as well as pinning a variation to be used as the preferred
+printing in all cases where the 'default' or 'most preferred' image should be shown.
+
+# Pre-requisites (User Interface)
+
+To use the printing selector, ensure that you are using the Post-ProviderID change behavior (Checkbox as shown in the
+image).
+
+\image html printing_selector_pre_providerid.png
+
+\attention This is the default behavior, unless you have explicitly changed it, in which case you will have seen a
+warning as follows. Once again, checking this box will *disable* the new behavior and revert you to the legacy system
+without the printing selector.
+
+Disabling the printing selector:
+
+\image html printing_selector_enable.png
+
+Enabling the printing selector:
+
+\image html printing_selector_disable.png
+
+# Pre-requisites (Card Database)
+
+The PrintingSelector requires each underlying CardInfo object to have a <set> entry with a *unique* providerID attribute
+for each variation that should be displayed.
+
+Here is an example, that first defines three sets, and then the 'Ace of Hearts' card with three variations.
+
+```xml
+<set rarity="common" uuid="00000000-0000-0000-0000-000000000033" num="51" muid="AH">PKR</set>
+<set rarity="common" uuid="00000000-0000-0000-0001-000000000033" num="51" muid="AHSTD">STD</set>
+<set rarity="common" uuid="00000000-0000-0000-0002-000000000033" num="51" muid="AHNBR">NBR</set>
+```
+
+```xml
+<?xml version='1.0' encoding='UTF-8'?>
+<cockatrice_carddatabase version="4">
+    <sets>
+        <set>
+            <name>PKR</name>
+            <longname>Cockatrice Poker</longname>
+            <settype>Custom</settype>
+            <releasedate>2025-11-15</releasedate>
+        </set>
+        <set>
+            <name>STD</name>
+            <longname>Standard Poker</longname>
+            <settype>core</settype>
+            <releasedate>2025-11-14</releasedate>
+        </set>
+        <set>
+            <name>NBR</name>
+            <longname>Numbers</longname>
+            <settype>core</settype>
+            <releasedate>2025-11-14</releasedate>
+        </set>
+    </sets>
+    <cards>
+        <card>
+            <name>Ace of Hearts</name>
+            <text>Ace of Hearts</text>
+            <prop>
+                <layout>normal</layout>
+                <side>front</side>
+                <type>Ace</type>
+                <maintype>Ace</maintype>
+                <manacost>14</manacost>
+                <cmc>14</cmc>
+                <colors>H</colors>
+                <coloridentity>H</coloridentity>
+                <format-standard>legal</format-standard>
+            </prop>
+            <reverse-related>Joker</reverse-related>
+            <token>0</token>
+            <tablerow>1</tablerow>
+            <cipt>0</cipt>
+            <upsidedown>0</upsidedown>
+            <set rarity="common" uuid="00000000-0000-0000-0000-000000000033" num="51" muid="AH">PKR</set>
+            <set rarity="common" uuid="00000000-0000-0000-0001-000000000033" num="51" muid="AHSTD">STD</set>
+            <set rarity="common" uuid="00000000-0000-0000-0002-000000000033" num="51" muid="AHNBR">NBR</set>
+        </card>
+    </cards>
+</cockatrice_carddatabase>
+```
+
+# Using the Printing Selector
+
+To use the PrintingSelector, first select a card in the DeckEditorDeckDockWidget:
+
+\image html deck_dock_deck_list.png
+
+You may add a variation to the mainboard by clicking the + and - buttons in the top row. The bottom row will add the
+variation to your sideboard.
+
+\image html printing_selector.png
+
+You can also right-click a variation to pin it, which will move it to the top of the variation list for easy access and
+additionally, use it as the default printing whenever the printing isn't explicitly specified (such as adding a card
+from the database in the deck editor).
+
+Only one printing may be pinned at a time.
+
+Additionally, the PrintingSelector offers a navigation bar at the bottom to navigate through cards in your deck, as well
+as an option to modify the variations of cards in bulk via the 'Bulk Selection' option.
+
+\image html printing_selector_navigation.png
+
+The search bar at the top may be used to filter the displayed variations and the cogwheel may be clicked to open up
+additional settings.
+
+\image html printing_selector_options.png

doc/doxygen/extra-pages/user_documentation/deck_management/editing_decks_visual.md

@@ -0,0 +1,93 @@
+@page editing_decks_visual Visual Deck Editor
+
+\image html vde_overlap_layout_type_grouped.png width=1200px
+
+# Editing Basic Deck Information
+
+Editing basic deck information is done through the deck dock widget (DeckEditorDeckDockWidget).
+
+\image html deckeditordeckdockwidget.png
+
+This widget allows editing:
+
+- The name
+- The comments
+- The banner card, which is used to represent the deck in the visual deck storage
+- The tags, which are used for filtering in the visual deck storage
+
+# Adding Cards
+
+Adding cards is done by either using the "Quick search and add card" search bar at the top of the "Visual Deck View" tab
+or by clicking on a picture of a card in the "Visual Database Display" tab.
+
+See @ref visual_database_display for more information on how to utilize the visual database display.
+
+# Modifying the Deck List
+
+To modify or remove cards in the deck list, the tree list view in the deck dock widget can be used.
+
+\image html deck_dock_deck_list.png
+
+Just above the list, at the top right, there are four buttons to manipulate the currently selected card(s):
+
+- Increment Card
+- Decrement Card
+- Remove Card
+- Switch Card between Mainboard and Sideboard
+
+\image html deck_dock_deck_list_buttons.png
+
+Additionally, there is a combo box above the list, which may be used to change how cards are grouped in the list
+display. This is only for visual display and does not affect how the list is saved.
+
+\image html deck_dock_deck_list_group_by.png
+
+# Modifying the visual deck layout
+
+The visual deck editor displays cards visually, as opposed to simply in list form in the Deck Dock Widget. Each entry in
+the deck list is represented by a picture. These entries are grouped together under their respective sub-groups.
+Sub-groups may be collapsed (i.e. the pictures contained within them are hidden) by clicking on the name of the group in
+the banner.
+
+Cards may be displayed in a "Flat" layout, which displays each picture next to each other and ensures full
+visibility for each card.
+
+\image html vde_flat_layout_type_grouped.png width=1200px
+
+or in an "Overlap" layout, which overlaps cards on top of each other (leaving the top 20% of
+the card uncovered so names remain readable) and arranges them in stacks to save space and allow for an easy overview.
+
+\image html vde_overlap_layout_type_grouped.png width=1200px
+
+Additionally, it is possible to change how the cards in the deck list are grouped by selecting a different grouping
+method from the combo box, either in the top left of the "Visual Deck View" tab or above the list view in the deck dock
+widget.
+
+Example - Cards grouped by suit/color:
+
+\image html vde_flat_layout_color_grouped.png width=1200px
+
+Furthermore, it is possible to change how the cards are sorted within the sub-group. This is done by clicking on the
+button with the cogwheel icon next to the combo box that adjusts grouping in the top left of the "Visual Deck View" tab.
+This presents a list of available sort criteria, which may be rearranged to change their priorities.
+
+# Modifying printings
+
+For more information on modifying the printings in a deck see @ref editing_decks_printings
+
+# Deck Analytics
+
+The visual deck editor offers a "Deck Analytics" tab, which displays information about:
+
+- The mana curve
+- The mana devotion
+- The mana base
+
+\image html vde_deck_analytics.png width=1200px
+
+# Sample Hand
+
+The visual deck editor offers a "Sample Hand" tab, which allows simulating drawing a configurable amount of cards from
+the deck, which reduces the need to launch a single player game for testing purposes.
+
+\image html vde_sample_hand.png width=1200px

doc/doxygen/extra-pages/user_documentation/deck_management/exporting_decks.md

@@ -0,0 +1,151 @@
+@page exporting_decks Exporting Decks
+
+# Where to export?
+
+There are two screens in the client which can be used to import decks, depending on the context.
+
+- The deck editor tab
+- The deck storage tab (not to be confused with the visual deck storage tab)
+
+# The Deck Editor Tab
+
+The deck editor tabs (Classic and Visual) offer three ways of export a deck:
+
+- To a file on your local storage
+- To your clipboard
+- To an online service
+
+## Local File Storage
+
+To save a deck to a file on your local storage, select the "Save Deck" action in the "Deck Editor" or "Visual Deck
+Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd + S
+to access this action.
+
+Selecting this action will open a file picker dialog provided by your operating system. Simply enter a file name and
+select a format (.cod is recommended) and confirm.
+
+Just below the "Save Deck" action described above is the "Save Deck as..." option, which allows saving an existing file
+under a different filename, which is useful for saving a different version or copy of a deck.
+
+## From Clipboard
+
+To save a deck to your clipboard, select the "Save deck to clipboard..." action in the "Deck Editor" or "Visual Deck
+Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd +
+Shift + C or Ctrl/Cmd + Shift + R to access this action.
+
+Selecting this action will save the currently open deck list to your clipboard.
+
+Saving the decklist without annotations will export the decklist, with each card being described in the following format
+
+```
+CARD_AMOUNT CARD_NAME (SET_SHORT_NAME) CARD_COLLECTOR_NUMBER
+```
+
+There is also the (no set info) option, which will simply export each card as
+
+```
+CARD_AMOUNT CARD_NAME
+```
+
+Mainboard and sideboard are delimited by a newline like so:
+
+```
+1 MainboardCard
+1 OtherMainboardCard
+
+1 SideboardCard
+```
+
+Saving the decklist as annotated will insert comments (marked with // in front of them).
+It will first insert the name and any comments associated with the deck before separating each deck section into its own
+newline delimited and annotated group.
+
+Example: TODO: Adjust this to be non mtg based.
+
+```
+// Full Deck
+
+// An example comment.
+
+// 63 Maindeck
+// 4 Ace
+1 Ace of Clubs (PKR) 49
+1 Ace of Diamonds (PKR) 50
+1 Ace of Hearts (PKR) 51
+1 Ace of Spades (PKR) 52
+
+// 13 Face
+1 Jack of Clubs (PKR) 53
+1 Jack of Diamonds (PKR) 54
+1 Jack of Hearts (PKR) 55
+1 Jack of Spades (PKR) 56
+1 King of Clubs (PKR) 57
+1 King of Diamonds (PKR) 58
+1 King of Spades (PKR) 60
+1 Queen of Clubs (PKR) 61
+1 Queen of Diamonds (PKR) 62
+1 Queen of Hearts (PKR) 63
+1 Queen of Spades (PKR) 64
+2 King of Hearts (PKR) 59
+
+// 44 Number
+1 0 of Clubs (PKR) 1
+1 0 of Diamonds (PKR) 2
+1 0 of Hearts (PKR) 3
+1 1 of Clubs (PKR) 11
+1 1 of Diamonds (PKR) 12
+1 1 of Hearts (PKR) 13
+1 1 of Spades (PKR) 14
+1 10 of Clubs (PKR) 5
+1 10 of Diamonds (PKR) 6
+1 10 of Hearts (PKR) 7
+1 2 of Clubs (PKR) 17
+1 2 of Diamonds (PKR) 18
+1 2 of Hearts (PKR) 19
+1 2 of Spades (PKR) 20
+1 3 of Clubs (PKR) 21
+1 3 of Diamonds (PKR) 22
+1 3 of Hearts (PKR) 23
+1 3 of Spades (PKR) 24
+1 4 of Clubs (PKR) 25
+1 4 of Diamonds (PKR) 26
+1 4 of Hearts (PKR) 27
+1 4 of Spades (PKR) 28
+1 5 of Clubs (PKR) 29
+1 5 of Diamonds (PKR) 30
+1 5 of Hearts (PKR) 31
+1 5 of Spades (PKR) 32
+1 6 of Clubs (PKR) 33
+1 6 of Diamonds (PKR) 34
+1 6 of Hearts (PKR) 35
+1 6 of Spades (PKR) 36
+1 7 of Clubs (PKR) 37
+1 7 of Diamonds (PKR) 38
+1 7 of Hearts (PKR) 39
+1 7 of Spades (PKR) 40
+1 8 of Clubs (PKR) 41
+1 8 of Diamonds (PKR) 42
+1 8 of Hearts (PKR) 43
+1 8 of Spades (PKR) 44
+1 9 of Clubs (PKR) 45
+1 9 of Diamonds (PKR) 46
+1 9 of Hearts (PKR) 47
+1 9 of Spades (PKR) 48
+1 10 of Spades (PKR) 8
+1 0 of Spades (PKR) 4
+
+
+// 2 Joker
+1 1 Joker (PKR) 10
+1 2 Joker (PKR) 16
+```
+
+## From an online service
+
+To export a deck to an online service, select the "Send deck to online service..." action in the "Deck Editor" or "
+Visual Deck Editor" menu in the application menu bar at the top of the screen.
+
+Selecting this action will open your browser with the selected service open and the deck list information from the
+client supplied to it.
+
+Currently supported services are DeckList and TappedOut.

doc/doxygen/extra-pages/user_documentation/deck_management/importing_decks.md

@@ -0,0 +1,62 @@
+@page importing_decks Importing Decks
+
+# Where to import?
+
+There are three screens in the client which can be used to import decks, depending on the context.
+
+- The deck editor tab
+- The pre-game lobby tab
+- The deck storage tab (not to be confused with the visual deck storage tab)
+
+# The Deck Editor Tab
+
+The deck editor tabs (Classic and Visual) offer three ways of importing a deck:
+
+- From a file on your local storage
+- From your clipboard
+- From an online service
+
+## Local File Storage
+
+To load a deck from a file on your local storage, select the "Load Deck" action in the "Deck Editor" or "Visual Deck
+Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd + O
+to access this action.
+
+Selecting this action will open a file picker dialog provided by your operating system. Simply select a supported file
+here and it will be loaded.
+
+Just below the "Load Deck" action described above is the "Load recent deck" option, which keeps a record of the last 10
+loaded decks for quick access.
+
+## From Clipboard
+
+To load a deck from your clipboard, select the "Load deck from clipboard..." action in the "Deck Editor" or "Visual Deck
+Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd +
+Shift + V to access this action.
+
+Selecting this action will open a new text editor dialog with the contents of your clipboard pasted inside it.
+
+The import dialog expects each line to be a card with the following format:
+
+TODO
+
+Each card should be on a separate line and there should be no empty lines between cards. The first empty line between
+two blocks of cards will be considered as the divider between mainboard and sideboard.
+
+Selecting "Parse Set Name and Number (if available)" will automatically parse these options and attempt to resolve them
+to valid provider IDs found in the card database. If this option is unselected, Cockatrice will import all cards as
+versions without provider IDs, which means they will display to everyone according to their own user defined set
+preferences, rather than being the same defined printing for everyone.
+
+## From an online service
+
+To load a deck from an online service, select the "Load deck from online service..." action in the "Deck Editor" or "
+Visual Deck Editor" menu in the application menu bar at the top of the screen.
+
+Selecting this action will open a dialog containing the contents of your clipboard pasted into it. If your clipboard
+currently contains a supported URL, the dialog will accept it and close on its own, otherwise you may adjust the URL and
+confirm.
+
+The action will automatically import the deck from the online service without any other required user action.
+
+Currently supported services are Archidekt, Deckstats, Moxfield, and TappedOut.

doc/doxygen/extra-pages/user_documentation/index.md

@@ -0,0 +1,13 @@
+@page user_reference User Reference
+
+@subpage search_syntax_help
+
+@subpage deck_search_syntax_help
+
+@subpage creating_decks
+
+@subpage importing_decks
+
+@subpage editing_decks
+
+@subpage exporting_decks