Without SUBCOMPONENTs, the install dialogue would look something like this:
Install Component [Delainy Portrait 1 by Bob] [Y]es, [N]o, or [Q]uit Install Component [Delainy Portrait 2 by Fred] [Y]es, [N]o, or [Q]uit Install Component [Delainy Portrait 3 by Wilhelmus] [Y]es, [N]o, or [Q]uit
The end user would need to click through the options each time. Worse, conflicting components could be installed. These problems can be limited somewhat by judicious use of predicates, but taking advantage of the SUBCOMPONENT feature yields far superior results:
Install Component [Delainy Portrait] [N]o, [Q]uit, or choose one: 1] Portrait 1 by Bob 2] Portrait 2 by Fred 3] Portrait 3 by Wilhelmus
Only one of these options can be installed at any time; re-installing and selecting a different SUBCOMPONENT will automatically uninstall the previously installed one. Setting this up is dead simple:
BEGIN ~Portrait 1 by Bob~ /* The string above is displayed in the subcomponent listing, i.e. the list with 1] 2] 3] etc. You can, of course, use TRA references instead for this and the SUBCOMPONENT string below. */ SUBCOMPONENT ~Delainy Portrait~ /* The string above is displayed as the component listing and must be the same for each SUBCOMPONENT. The tp2 code that follows is only executed if this SUBCOMPONENT is selected. */ COPY ~Delainy/portraits/opt1G.bmp~ ~override/CDDELAIG.bmp~ COPY ~Delainy/portraits/opt1M.bmp~ ~override/CDDELAIM.bmp~ COPY ~Delainy/portraits/opt1S.bmp~ ~override/CDDELAIS.bmp~ BEGIN ~Portrait 2 by Fred~ SUBCOMPONENT ~Delainy Portrait~ COPY ~Delainy/portraits/opt2G.bmp~ ~override/CDDELAIG.bmp~ COPY ~Delainy/portraits/opt2M.bmp~ ~override/CDDELAIM.bmp~ COPY ~Delainy/portraits/opt2S.bmp~ ~override/CDDELAIS.bmp~ BEGIN ~Portrait 3 by Wilhelmus~ SUBCOMPONENT ~Delainy Portrait~ COPY ~Delainy/portraits/opt3G.bmp~ ~override/CDDELAIG.bmp~ COPY ~Delainy/portraits/opt3M.bmp~ ~override/CDDELAIM.bmp~ COPY ~Delainy/portraits/opt3S.bmp~ ~override/CDDELAIS.bmp~
Any REQUIRE_FILEs or other module requirements for the whole group should be put with the first subcomponent. If such a requirement fails, none of the subcomponents can be installed. In addition, each individual subcomponent can be guarded by its own predicate. If that predicate fails, that particular subcomponent cannot be installed.
One note about SUBCOMPONENTs and mod ordering: WeiDU will display SUBCOMPONENTs in a single grouping no matter if they fall consecutively in the tp2 or not. However, the component number (the one that gets placed in weidu.log and the one you check for in REQUIRE_COMPONENT et al) is still based on their tp2 order.
Discussion and comments can be handled in this thread.
