man/README - main - githubmirror/lvm2

man/README
102 строки4 KB
Peter Rajnoha
man: update README with conditional field and filtering documentation
05 мар 2026, 19:09
05 мар 2026, 19:09f8b9b74
Man Page Source Files
=====================

This directory contains the source files used to build LVM2 and
device-mapper man pages.  The final installable man pages (e.g.
lvcreate.8, lvm.conf.5) are generated at build time and are not
stored in the repository.

File suffixes
-------------

*_main
    Hand-written, complete man page source in nroff format.
    Used for pages whose content is entirely static: conceptual
    topics (lvmraid.7_main, lvmcache.7_main, ...), configuration
    files (lvm.conf.5_main), daemons (dmeventd.8_main, ...),
    and tools whose option set is not auto-generated (dmsetup.8_main,
    fsadm.8_main, ...).

*_des
    Short description text for commands whose man page is partially
    auto-generated.  Contains an introductory paragraph that appears
    after the auto-generated SYNOPSIS section.  Every _des file has
    a matching _end file.

*_end
    Trailing content (typically an EXAMPLES section) appended after
    the auto-generated option descriptions.  Paired 1:1 with _des
    files.

see_also.end
    Common "SEE ALSO" section shared by all auto-generated command
    pages.  Appended after the _end content.

*_meta
    Metadata about a man page used for index and category generation.
    Contains key=value pairs:
      category = <name>    Category for the categorized index.
      conditional = yes    Optional.  Marks the entry as conditional.
                           When pregenerated pages are used (cross-
                           compilation), entries for man pages not
                           enabled by the current configure are
                           filtered out.
    Every man page has a _meta file, including builtin commands that
    have no dedicated man page of their own (e.g. config.8_meta,
    help.8_meta).

*_gen
    Intermediate generated files produced during the build.  Created
    by the man-generator tool (or copied from _pregen fallbacks).
    Not stored in the repository.

*_pregen
    Pre-generated fallback content committed to the repository.
    Used when the man-generator tool cannot be built or fails to
    run (the Makefile checks for this via the test.gen probe).
    Regenerated with "make generate" and should be kept in sync
    with any source changes.

test.gen
    Build-time probe file.  The Makefile runs man-generator once
    at the start and writes the output to test.gen.  If the file
    has content, the generator is functional and is used to produce
    _gen files.  If it is empty, the build falls back to the
    committed _pregen files instead.  Not stored in the repository.

.5, .7, .8
    Final installable man pages.  Built from _main or _gen files
    by substituting version/path placeholders (SUBSTVARS) and
    escaping hyphens (ESCAPEHYPHENS).  These are build artifacts,
    listed in CLEAN_TARGETS, and not stored in the repository.

Build pipeline
--------------

Static pages (_main based):

    *_main  -->  SUBSTVARS  -->  ESCAPEHYPHENS  -->  *.5 / *.7 / *.8

Auto-generated command pages (_des + _end based):

    *_des + *_end + see_also.end
        --> man-generator --primary / --secondary
        --> *_gen
        --> SUBSTVARS  -->  ESCAPEHYPHENS  -->  *.8

    If the generator is unavailable, *_pregen is used in place
    of the generation step.

Index and category pages (_meta based):

    *_meta files
        --> man-generator --index / --categories
        --> *_gen
        --> SUBSTVARS  -->  ESCAPEHYPHENS  -->  *.7

    If the generator is unavailable, *_pregen is used in place
    of the generation step.  The pregenerated index and category
    files contain all possible entries (full configuration) with
    condition markers around optional entries.  At build time,
    entries for man pages not enabled by configure are filtered
    out.