Documentation|Readme: Added documentation about the Packages tab

doomsday/doc/readme/games.ame

@@ -8,8 +8,13 @@ can be found:
 
 @list{
 
-    @ifndef{WIN32}{The directory @file{/usr/share/games/doom} is checked for
-    any recognized IWAD files.}
+    @item The first time you launch Doomsday and it doesn't find any IWADs, it
+    will show a tab titled @ui{Data Files?} containing a single button.
+    Clicking the button opens a file dialog where you can pick a folder where
+    your IWAD files are located.
+
+    @ifdef{UNIX}{@item The directory @file{/usr/share/games/doom} is always
+    checked for any recognized IWAD files.}
 
     @ifndef{UNIX}{@item If you have Steam installed, Doomsday will
     automatically detect if you have purchased a compatible game and will
@@ -18,14 +23,14 @@ can be found:
     @ifdef{WIN32}{@item Compatible games purchased from
     @link{GOG.com}{https://gog.com} are autodetected.}
 
-    @item Using the @opt{-iwad} option. You can either provide the path to the
-    IWAD to use, or the path of the directory under which IWADs are located.
-    Doomsday will look through the specified location and use all the
+    @item Using the @opt{-iwad} command-line option. You can either provide the
+    path to the IWAD to use, or the path of the directory under which IWADs are
+    located. Doomsday will look through the specified location and use all the
     recognized IWADs automatically. In other words, you can have the IWADs for
     all games stored in a single directory; Doomsday will use the appropriate
     one for each launched game.
 
-    @opt{-iwad} accepts multiple paths as parameters:
+    @opt{-iwad} will also accept multiple paths as parameters:
 
     @samp{@opt{-iwad path1 path2}}
 
@@ -35,7 +40,7 @@ can be found:
     Script command prompt.
 
     @ifndef{WIN32}{@item The configuration file @file{~/.doomsday/paths} is
-    checked for @var{iwaddir} (see @ref{paths_file}{Additional files}).}
+    checked for @var{iwaddir} (see @ref{paths_file}{Files}).}
 
     @item Environment variables DOOMWADDIR and DOOMWADPATH (see
     @ref{environ}{Environment}).

doomsday/doc/readme/readme.ame

@@ -12,6 +12,7 @@
 
 $ Readme-specific formatting macros.
 @macro{plugin}{@arg}
+@macro{ui}{@dquote{@arg}}
 @ifndef{MAN}{
     @macro{man_opt}{-@glue{@arg}}
     @macro{man_opt2}{-@glue{@arg{1}} (@arg{2})}

doomsday/doc/readme/technical/files_common.ame

@@ -1,13 +1,20 @@
 @deflist{
 
-    @item{@file{runtime/autoexec.cfg}} Console commands to execute after  loading the game with the @opt{-game} option.
+    @item{@file{runtime/autoexec.cfg}} Console commands to execute after
+    loading the game with the @opt{-game} option.
 
-    @item{@file{runtime/cache/}} Cached data that helps Doomsday run faster. You can delete the contents of this folder; Doomsday will recreate them automatically as needed.
+    @item{@file{runtime/cache/}} Cached data that helps Doomsday run faster.
+    You can delete the contents of this folder; Doomsday will recreate them
+    automatically as needed.
 
-    @item{@file{runtime/configs/}} Game profiles and saved values for console variables and control bindings.
+    @item{@file{runtime/configs/}} Game profiles and saved values for console
+    variables and control bindings.
 
     @item{@file{runtime/doomsday.out}} Log message output file.
 
-    @item{@file{runtime/savegames/}} Folder containing all saved games. Each game has its own subfolder for saves. Note that the subfolders are game-specific rather than profile-specific; if you create custom game profiles, their saves will be written in the same subfolder as saves from the default game profile.
-
-}
+    @item{@file{runtime/savegames/}} Folder containing all saved games. Each
+    game has its own subfolder for saves. Note that the subfolders are
+    game-specific rather than profile-specific; if you create custom game
+    profiles, their saves will be written in the same subfolder as saves from
+    the default game profile.
+}

doomsday/doc/readme/technical/files_macos.ame

@@ -1,4 +1,15 @@
 Your runtime files (savegames, screenshots) are inside a folder called
 @file{~/Library/Application Support/Doomsday Engine/}.
 
-@include{technical/files_common}
+@include{technical/files_common}
+
+@ifdef{MACOSX}{        
+    @a{paths_file} Additional files:
+    @deflist{        
+        @item{@file{~/.doomsday/paths}} Customized file path
+        configuration (@var{basedir}, @var{libdir}, @var{iwaddir}). The
+        @wikilink{syntax of the
+        file}{Configuration#Unix_system-level_config_files} is documented in
+        the wiki.    
+    }
+}

doomsday/doc/readme/ui/home.ame

@@ -14,7 +14,7 @@ to a different tab:
     @item Click on the left or right edge of the screen.
 }
 
-@section{ Doom, Heretic, Hexen, Other Games }
+@section{ Game library }
 
 The game library tabs list all the available game profiles and saved games
 associated with them. Each game profile can be configured to use a set of
@@ -27,45 +27,99 @@ entire game tabs, if you are not interested in a particular family of games.
 
 @parag{Starting a game with or without additional packages.} Click on a profile
 to select it, or move the selection with the arrow keys. When selected, Package
-Selection and Play buttons slide in. The Package Selection button shows a
-number for how many additional packages have been configured. Click Play or
-double-click the profile to start the game.
+and Play buttons slide in. The Package button shows a number for how many
+additional packages have been configured. Click Play or double-click the
+profile to start the game.
 
-@parag{Selecting packages.} Click the profile's Package Selection button to
-choose which additional packages are going to be loaded when the game is
-started. On the left side of the dialog, you have a list of the packages
-attached to the profile. On the right, you can browse the available packages.
-The package browser works similarly to the Packages tab, and it has a search
-field and Info buttons (see @ref{packages}{Packages}). To add a package to the
-profile, click the Plus button or double-click the package.
+@parag{Selecting packages.} Click the profile's Package button to choose which
+additional packages are going to be loaded when the game is started. On the
+left side of the dialog, you have a list of the packages attached to the
+profile. On the right, you can browse the available packages. The package
+browser works similarly to the Packages tab, and it has a search field and Info
+buttons (see @ref{packages}{Packages}). To add a package to the profile, click
+the Plus button or double-click the package.
 
 @parag{Loading a saved game.} All saved games are listed under the game profile
-they were created in. Click on a save to select it, and then press the profile's Play button. Clicking on an already selected save will unselect it.
+they were created in. Click on a save to select it, and then press the
+profile's Play button. Clicking on an already selected save will unselect it.
 
 @notice{Old savegames created with Doomsday 1.x do not contain information
 about which data files and packages were in use when the save was created, so
 Doomsday can't determine which profile they belong to. Such saves are listed
 under each profile of the game.}
 
-@parag{Savegame information.} Right-click on a saved game to see information about the save: which data files and packages were in use, the overall game parameteres, current map, and other status information.
+@parag{Savegame information.} Right-click on a saved game to see information
+about the save: which data files and packages were in use, the overall game
+parameteres, current map, and other status information.
 
-@parag{Deleting a saved game.} When a savegame is selected, a small X button appears next to it. Clicking the X lets you delete the save.
+@parag{Deleting a saved game.} When a savegame is selected, a small X button
+appears next to it. Clicking the X lets you delete the save.
 
-@parag{Creating a new profile.} At the bottom of each profile list, there is a Plus button that creates a new, empty profile. In the profile parameters, you can choose which game will be used, and which packages are selected for loading. Note that game profiles cannot have a name that is identical to an already existing game profile name.
+@parag{Creating a new profile.} At the bottom of each profile list, there is a
+Plus button that creates a new, empty profile. In the profile parameters, you
+can choose which game will be used, and which packages are selected for
+loading. Note that game profiles cannot have a name that is identical to an
+already existing game profile name.
 
-@parag{Duplicate, edit, and delete profiles.} Any profile can be duplicated by right-clicking on it and selecting Duplicate. Profiles can also be edited to change their name and the set of selected packages.
+@parag{Duplicate, edit, and delete profiles.} Any profile can be duplicated by
+right-clicking on it and selecting @ui{Duplicate}. Profiles can also be edited
+to change their name and the set of selected packages.
 
 @a{packages}@section{ Packages }
 
+The Packages tab is used to browse all the available @wikiterm{packages}. With
+the exception of game IWAD files, it shows all the data files that Doomsday can
+load. You can also quickly try out individual packages in one your existing
+game profiles.
+
+@parag{Configuring the folders where packages are found.} To let Doomsday know
+where your packages can be found, either select @ui{Folders} in the Packages
+tab's actions menu (the @ui{...} button under the tab title), or go to Data
+Files settings (see @ref{config}{Configuration}). The packages will not be
+copied or moved from wherever you keep them.
+
+@parag{Searching for packages.} The packages list may contains hundreds of
+items, so you may want to find the package you're looking for by entering some
+search terms. Enter the words to search in the search field at the top of the
+list. The search is limited to package metadata; the actual file contents are
+not accessed. When entering multiple words, only packages whose metadata
+contains all the words are shown.
+
+@parag{Special search keywords.} Some search words have a special meaning:
 @list{
-    @item Setting additional folders where to load packages
-    @item Viewing information about a package: version, intended game, etc.
-    @item Quickly trying out packages in a game
-    @item Quickly adding a package to an existing profile
-    @item Searching for packages
-    @item Special filter keywords: hidden, loaded
+    @item @dquote{hidden}: Only packages that are normally hidden will be
+    shown. Packages that are hidden by default include, for example, packages
+    inside other packages that will get automatically loaded.
+
+    @item @dquote{loaded}: Only show currently loaded packages. This is useful
+    when browsing packages while playing a game.
 }
 
+@parag{Viewing information about a package.} Right-click a package or click on
+the @ui{...} button to view information about it. In the case of WAD files, all
+the maps in the WAD are listed so you'll know which map to start when playing.
+The info popup also shows the game title picture found in the package, and
+readme notes provided by the author. In some cases, Doomsday can make a guess
+about the game that the package is meant to be used with.
+
+@parag{Quickly trying out a package.} One of the most useful features of the
+Packages tab is quickly loading a package in one your games. This will make no
+changes to your profiles. Simply open the package info popup and click on
+@ui{Play in...}. However, you should first check that the package actually is
+compatible with the game you are playing. Also be aware that if you are already
+in a game, it will be unloaded first and any unsaved progress will be lost.
+
+@parag{Quickly adding a package to a profile.} The @ui{Add to...} button in the
+package info popup will add the package to one of your existing game profiles.
+The profiles that already have the package are labeled @ui{ADDED} in the list.
+
+@parag{Configuring optional contents.} Some packages have optional
+subcomponents. For instance, add-ons that use the @wikiterm{Snowberry Box}
+format may include both opt-in and opt-out packages. When viewing information
+about this kind of collections, an additional @ui{Options} button is shown in
+the package info popup. This will let you enable or disable individual
+contained sub-packages.
+
 @section{ Multiplayer }
 
 Doomsday supports client/server based multiplayer games for up to 15 players.