[gentoo-dev] [PATCH 13/14] cdrom.eclass: Update and improve documentation following changes

[James Le Cuirot <chewi@gentoo.org>]

---
 eclass/cdrom.eclass | 121 +++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 96 insertions(+), 25 deletions(-)

diff --git a/eclass/cdrom.eclass b/eclass/cdrom.eclass
index 36d967d2f4cd..c95bb80325e9 100644
--- a/eclass/cdrom.eclass
+++ b/eclass/cdrom.eclass
@@ -6,13 +6,13 @@
 # games@gentoo.org
 # @BLURB: Functions for CD-ROM handling
 # @DESCRIPTION:
-# Acquire cd(s) for those lovely cd-based emerges.  Yes, this violates
-# the whole 'non-interactive' policy, but damnit I want CD support!
+# Acquire CD(s) for those lovely CD-based emerges.  Yes, this violates
+# the whole "non-interactive" policy, but damnit I want CD support!
 #
-# With these cdrom functions we handle all the user interaction and
-# standardize everything.  All you have to do is call cdrom_get_cds()
-# and when the function returns, you can assume that the cd has been
-# found at CDROM_ROOT.
+# Do not call these functions in pkg_* phases like pkg_setup as they
+# should not be used for binary packages.  Most packages using this
+# eclass will require RESTRICT="bindist" but the point still stands.
+# The functions are generally called in src_unpack.
 
 if [[ -z ${_CDROM_ECLASS} ]]; then
 _CDROM_ECLASS=1
@@ -24,8 +24,8 @@ inherit portability
 # @DESCRIPTION:
 # By default, the eclass sets PROPERTIES="interactive" on the assumption
 # that people will be using these.  If your package optionally supports
-# disc based installed, then set this to "yes", and we'll set things
-# conditionally based on USE=cdinstall.
+# disc-based installs then set this to "yes" and we'll set things
+# conditionally based on USE="cdinstall".
 if [[ ${CDROM_OPTIONAL} == "yes" ]] ; then
 	IUSE="cdinstall"
 	PROPERTIES="cdinstall? ( interactive )"
@@ -34,19 +34,41 @@ else
 fi
 
 # @FUNCTION: cdrom_get_cds
-# @USAGE: <file on cd1> [file on cd2] [file on cd3] [...]
+# @USAGE: <cd1 file>[:alt cd1 file] [cd2 file[:alt cd2 file]] [...]
 # @DESCRIPTION:
-# The function will attempt to locate a cd based upon a file that is on
-# the cd.  The more files you give this function, the more cds the cdrom
-# functions will handle.
+# Attempt to locate a CD based upon a file that is on the CD.
 #
-# Normally the cdrom functions will refer to the cds as 'cd #1', 'cd #2',
-# etc...  If you want to give the cds better names, then just export
-# the appropriate CDROM_NAME variable before calling cdrom_get_cds().
-# Use CDROM_NAME for one cd, or CDROM_NAME_# for multiple cds.  You can
-# also use the CDROM_NAMES bash array.
+# If the data spans multiple discs then additional arguments can be
+# given to check for more files.  Call cdrom_load_next_cd() to scan for
+# the next disc in the set.
 #
-# For those multi cd ebuilds, see the cdrom_load_next_cd() function.
+# Sometimes it is necessary to support alternative CD "sets" where the
+# contents differ.  Alternative files for each disc can be appended to
+# each argument, separated by the : character.  This feature is
+# frequently used to support installing from an existing installation.
+# Note that after the first disc is detected, the set is locked so
+# cdrom_load_next_cd() will only scan for files in that specific set on
+# subsequent discs.
+#
+# The given files can be within named subdirectories.  It is not
+# necessary to specify different casings of the same filename as
+# matching is done case-insensitively.  Filenames can include special
+# characters such as spaces.  Only : is not allowed.
+#
+# If you don't want each disc to be referred to as "CD #1", "CD #2",
+# etc. then you can optionally provide your own names.  Set CDROM_NAME
+# for a single disc, CDROM_NAMES as an array for multiple discs, or
+# individual CDROM_NAME_# variables for each disc starting from 1.
+#
+# Despite what you may have seen in older ebuilds, it has never been
+# possible to provide per-set disc names.  This would not make sense as
+# all the names are initially displayed before the first disc has been
+# detected.  As a workaround, you can redefine the name variable(s)
+# after the first disc has been detected.
+#
+# This function ends with a cdrom_load_next_cd() call to scan for the
+# first disc.  For more details about variables read and written by this
+# eclass, see that function's description.
 cdrom_get_cds() {
 	unset CDROM_SET
 	export CDROM_CURRENT_CD=0 CDROM_CHECKS=( "${@}" )
@@ -100,13 +122,62 @@ cdrom_get_cds() {
 
 # @FUNCTION: cdrom_load_next_cd
 # @DESCRIPTION:
-# Some packages are so big they come on multiple CDs.  When you're done
-# reading files off a CD and want access to the next one, just call this
-# function.  Again, all the messy details of user interaction are taken
-# care of for you.  Once this returns, just read the variable CDROM_ROOT
-# for the location of the mounted CD.  Note that you can only go forward
-# in the CD list, so make sure you only call this function when you're
-# done using the current CD.
+# If multiple arguments were given to cdrom_get_cds() then you can call
+# this function to scan for the next disc.  This function is also called
+# implicitly to scan for the first disc.
+#
+# The file(s) given to cdrom_get_cds() are scanned for on any mounted
+# filesystem that resembles optical media.  If no match is found then
+# the user is prompted to insert and mount the disc and press enter to
+# rescan.  This will loop continuously until a match is found or the
+# user aborts with Ctrl+C.
+#
+# The user can override the scan location by setting CD_ROOT for a
+# single disc, CD_ROOT if multiple discs are merged into the same
+# directory tree (useful for existing installations), or individual
+# CD_ROOT_# variables for each disc starting from 1.  If no match is
+# found then the function dies with an error as a rescan will not help
+# in this instance.
+#
+# Users wanting to set CD_ROOT or CD_ROOT_# for specific packages
+# persistently can do so using Portage's /etc/portage/env feature.
+#
+# Regardless of which scanning method is used, several variables are set
+# by this function for you to use:
+#
+#  CDROM_ROOT: Root path of the detected disc.
+#  CDROM_MATCH: Path of the matched file, relative to CDROM_ROOT.
+#  CDROM_ABSMATCH: Absolute path of the matched file.
+#  CDROM_SET: The matching set number, starting from 0.
+#
+# The casing of CDROM_MATCH may not be the same as the argument given to
+# cdrom_get_cds() as matching is done case-insensitively.  You should
+# therefore use this variable (or CDROM_ABSMATCH) when performing file
+# operations to ensure the file is found.  Use newins rather than doins
+# to keep the final result consistent and take advantage of Bash
+# case-conversion features like ${FOO,,}.
+#
+# Chances are that you'll need more than just the matched file from each
+# disc though.  You should not assume the casing of these files either
+# but dealing with this goes beyond the scope of this ebuild.  For a
+# good example, see games-action/descent2-data, which combines advanced
+# globbing with advanced tar features to concisely deal with
+# case-insensitive matching, case conversion, file moves, and
+# conditional exclusion.
+#
+# Copying directly from a mounted disc using doins/newins will remove
+# any read-only permissions but be aware of these when copying to an
+# intermediate directory first.  Attempting to clean a build directory
+# containing read-only files as a non-root user will result in an error.
+# If you're using tar as suggested above then you can easily work around
+# this with --mode=u+w.
+#
+# Note that you can only go forwards in the disc list, so make sure you
+# only call this function when you're done using the current disc.
+#
+# If you cd to any location within CDROM_ROOT then remember to leave the
+# directory before calling this function again, otherwise the user won't
+# be able to unmount the current disc.
 cdrom_load_next_cd() {
 	local showedmsg=0 showjolietmsg=0
 
-- 
2.11.0