github.com/containers/podman/v5@v5.1.0-rc1/docs/source/markdown/options/README.md (about)

     1  Common Man Page Options
     2  =======================
     3  
     4  This subdirectory contains option (flag) names and descriptions
     5  common to multiple podman man pages. Each file is one option. The
     6  filename does not necessarily need to be identical to the option
     7  name: for instance, `hostname.container.md` and `hostname.pod.md`
     8  exist because the **--hostname** option is sufficiently different
     9  between `podman-{create,run}` and `podman-pod-{create,run}` to
    10  warrant living separately.
    11  
    12  How
    13  ===
    14  
    15  The files here are included in `podman-*.md.in` files using the `@@option`
    16  mechanism:
    17  
    18  ```
    19  @@option foo           ! includes options/foo.md
    20  ```
    21  
    22  The tool that does this is `hack/markdown-preprocess`. It is a python
    23  script because it needs to run on `readthedocs.io`. From a given `.md.in`
    24  file, this script creates a `.md` file that can then be read by
    25  `go-md2man`, `sphinx`, anything that groks markdown. This runs as
    26  part of `make docs`.
    27  
    28  Special Substitutions
    29  =====================
    30  
    31  Some options are almost identical except for 'pod' vs 'container'
    32  differences. For those, use `<<text for pods|text for containers>>`.
    33  Order is immaterial: the important thing is the presence of the
    34  string "`pod`" in one half but not the other. The correct string
    35  is chosen based on the filename: if the file contains `-pod`,
    36  such as `podman-pod-create`, the string with `pod` (case-insensitive)
    37  in it is chosen.
    38  
    39  The string `<<subcommand>>` is replaced with the podman subcommand
    40  as determined from the filename, e.g., `create` for `podman-create.1.md.in`.
    41  This allows the shared use of examples in the option file:
    42  ```
    43      Example: podman <<subcommand>> --foo --bar
    44  ```
    45  As a special case, `podman-pod-X` becomes just `X` (the "pod" is removed).
    46  This makes the `pod-id-file` man page more useful. To get the full
    47  subcommand including 'pod', use `<<fullsubcommand>>`.
    48  
    49  Restrictions
    50  ============
    51  
    52  There is a restriction for having a single text line with three
    53  back-ticks in the front and the end of the line.  For instance:
    54  
    55  \`\`\`Some man page text\`\`\`
    56  
    57  This is currently not allowed and causes a corruption of the
    58  compiled man page.  Instead, put the three back-ticks on separate
    59  lines like:
    60  
    61  \`\`\`
    62  Some man page text
    63  \`\`\`