man: Revise internal man page generation process.

For each section 8 man page, a .8_gen file is created from one of:
  .8_main            - Old-style man page - content used directly
  .8_des and .8_end  - Description and end section of a generated page
  .8_pregen	     - Pre-generated page used if the generator fails

Other man sections are not generated and use the suffix .5_main or .7_main.

Developers should use 'make generate' to regenerate the .8_pregen files.

1 files changed, 105 insertions, 0 deletions

diff --git a/man/pvscan.8_des b/man/pvscan.8_des
new file mode 100644
index 000000000..ab8c50cf7
--- /dev/null
+++ b/man/pvscan.8_des
@@ -0,0 +1,105 @@
+pvscan scans all supported LVM block devices in the system for PVs.
+
+\fBScanning with lvmetad\fP
+
+pvscan operates differently when used with the
+.BR lvmetad (8)
+daemon.
+
+Scanning disks is required to read LVM metadata and identify LVM PVs.
+Once read, lvmetad caches the metadata so that LVM commands can read it
+without repeatedly scanning disks.  This is helpful because scanning disks
+is time consuming, and frequent scanning may interfere with the normal
+work of the system and disks.
+
+When lvmetad is not used, LVM commands revert to scanning disks to read
+metadata.  Any LVM command that needs metadata will scan disks for it;
+running the pvscan command is not necessary for the sake of other LVM
+commands.
+
+When lvmetad is used, LVM commands avoid scanning disks by reading
+metadata from lvmetad.  When new disks appear, they must be scanned so
+their metadata can be cached in lvmetad.  This is done by the command
+pvscan \-\-cache, which scans disks and passes the metadata to lvmetad.
+
+The pvscan \-\-cache command is typically run automatically by system
+services when a new device appears.  Users do not generally need to run
+this command if the system and lvmetad are running properly.
+
+Many scripts contain unnecessary pvscan (or vgscan) commands for
+historical reasons.  To avoid disrupting the system with extraneous disk
+scanning, an ordinary pvscan (without \-\-cache) will simply read metadata
+from lvmetad like other LVM commands.  It does not do anything beyond
+displaying the current state of the cache.
+
+.IP \[bu] 2
+When given specific device name arguments, pvscan \-\-cache will only
+read the named devices.
+
+.IP \[bu] 2
+LVM udev rules and systemd services are used to initiate automatic device
+scanning.
+
+.IP \[bu] 2
+To prevent devices from being scanned by pvscan --cache, add them
+to
+.BR lvm.conf (5)
+.B devices/global_filter.
+The devices/filter setting does not
+apply to system level scanning.
+For more information, see:
+.br
+.B lvmconfig --withcomments devices/global_filter
+
+.IP \[bu] 2
+If lvmetad is started or restarted after devices are visible, or
+if the global_filter has changed, then all devices must be rescanned
+for metadata with the command pvscan \-\-cache.
+
+.IP \[bu] 2
+lvmetad does not cache older metadata formats, e.g. lvm1, and will
+be temporarily disabled if they are seen.
+
+.IP \[bu] 2
+To notify lvmetad about a device that is no longer present, the major and
+minor numbers must be given, not the path.
+
+.P
+
+\fBAutomatic activation\fP
+
+When event-driven system services detect a new LVM device, the first step
+is to automatically scan and cache the metadata from the device.  This is
+done by pvscan \-\-cache.  A second step is to automatically activate LVs
+that are present on the new device.  This auto-activation is done by the
+same pvscan \-\-cache command when the option '\-a|\-\-activate ay' is
+included.
+
+Auto-activation of VGs or LVs can be enabled/disabled using:
+.br
+.BR lvm.conf (5)
+.B activation/auto_activation_volume_list
+
+For more information, see:
+.br
+.B lvmconfig --withcomments activation/auto_activation_volume_list
+
+When this setting is undefined, all LVs are auto-activated (when lvm is
+fully integrated with the event-driven system services.)
+
+When a VG or LV is not auto-activated, traditional activation using
+vgchange or lvchange -a|--activate is needed.
+
+.IP \[bu] 2
+pvscan auto-activation can be only done in combination with \-\-cache.
+
+.IP \[bu] 2
+Auto-activation is designated by the "a" argument in '-a|--activate ay'.
+This is meant to distinguish system generated commands from explicit user
+commands, although it can be used in any activation command.  Whenever it
+is used, the auto_activation_volume_list is applied.
+
+.IP \[bu] 2
+Auto-activation is not yet supported for LVs that are part of partial or
+clustered volume groups.
+