docs: use anchors and xref

Signed-off-by: Yuxuan Shui <[email protected]>

man/picom.1.adoc

@@ -52,7 +52,7 @@ OPTIONS
 *-f*, *--fading*::
 	Fade windows in/out when opening/closing and when opacity changes, unless *--no-fading-openclose* is used.
 
-*-i*, *--inactive-opacity*=_OPACITY_::
+[[inactive-opacity]]*-i*, *--inactive-opacity*=_OPACITY_::
 	Opacity of inactive windows. (0.1 - 1.0, defaults to 1.0). Using this option is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific opacity.
 
 *-e*, *--frame-opacity*=_OPACITY_::
@@ -94,31 +94,31 @@ OPTIONS
 *--shadow-blue* _VALUE_::
 	Blue color value of shadow (0.0 - 1.0, defaults to 0).
 
-*--inactive-opacity-override*::
+[[inactive-opacity-override]]*--inactive-opacity-override*::
 	Let inactive opacity set by *-i* override the __NET_WM_WINDOW_OPACITY_ values of windows. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific opacity.
 
-*--active-opacity* _OPACITY_::
+[[active-opacity]]*--active-opacity* _OPACITY_::
 	Default opacity for active windows. (0.0 - 1.0, defaults to 1.0). Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific opacity.
 
-*--inactive-dim* _VALUE_::
+[[inactive-dim]]*--inactive-dim* _VALUE_::
 	Dim inactive windows. (0.0 - 1.0, defaults to 0.0). Using this option is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific dim levels.
 
-*--corner-radius* _VALUE_::
+[[corner-radius]]*--corner-radius* _VALUE_::
 	Sets the radius of rounded window corners. When > 0, the compositor will round the corners of windows. Does not interact well with *--transparent-clipping*. (defaults to 0).
 
-*--corner-radius-rules* _RADIUS_:_CONDITION_::
+[[corner-radius-rules]]*--corner-radius-rules* _RADIUS_:_CONDITION_::
 	Specify a list of corner radius rules. Overrides the corner radii of matching windows. This option takes precedence over the *--rounded-corners-exclude* option, and also overrides the default exclusion of fullscreen windows. The condition has the same format as *--opacity-rule*. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific corner radius.
 
-*--rounded-corners-exclude* _CONDITION_::
+[[rounded-corners-exclude]]*--rounded-corners-exclude* _CONDITION_::
 	Exclude conditions for rounded corners. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific corner radius.
 
 *--no-frame-pacing*::
 	Disable vsync-aware frame pacing. By default, the compositor tries to make sure it only renders once per vblank interval, and also the render happens as late as possible to minimize the latency from updates to the screen. However this can sometimes cause stuttering, or even lowered frame rate. This option can be used to disable frame pacing.
 
-*--mark-wmwin-focused*::
+[[mark-wmwin-focused]]*--mark-wmwin-focused*::
 	Try to detect WM windows (a non-override-redirect window with no child that has _WM_STATE_) and mark them as active. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific rules.
 
-*--mark-ovredir-focused*::
+[[mark-ovredir-focused]]*--mark-ovredir-focused*::
 	Mark override-redirect windows that doesn't have a child window with _WM_STATE_ focused. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific rules.
 
 *--no-fading-openclose*::
@@ -127,10 +127,10 @@ OPTIONS
 *--no-fading-destroyed-argb*::
 	Do not fade destroyed ARGB windows with WM frame. Workaround of bugs in Openbox, Fluxbox, etc.
 
-*--shadow-ignore-shaped*::
+[[shadow-ignore-shaped]]*--shadow-ignore-shaped*::
 	Do not paint shadows on shaped windows. Note shaped windows here means windows setting its shape through X Shape extension. Those using ARGB background is beyond our control. Deprecated, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific shadow.
 
-*--detect-rounded-corners*::
+[[detect-rounded-corners]]*--detect-rounded-corners*::
 	Try to detect windows with rounded corners and don't consider them shaped windows. The accuracy is not very high, unfortunately.
 
 *--detect-client-opacity*::
@@ -154,28 +154,28 @@ OPTIONS
 *--unredir-if-possible-delay* _MILLISECONDS_::
 	Delay before unredirecting the window, in milliseconds. Defaults to 0.
 
-*--unredir-if-possible-exclude* _CONDITION_::
+[[unredir-if-possible-exclude]]*--unredir-if-possible-exclude* _CONDITION_::
 	Conditions of windows that shouldn't be considered full-screen for unredirecting screen. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific unredirect.
 
-*--shadow-exclude* _CONDITION_::
+[[shadow-exclude]]*--shadow-exclude* _CONDITION_::
 	Specify a list of conditions of windows that should have no shadow. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific shadow.
 
-*--clip-shadow-above* _CONDITION_::
+[[clip-shadow-above]]*--clip-shadow-above* _CONDITION_::
 	Specify a list of conditions of windows that should have no shadow painted over, such as a dock window. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific shadow clipping.
 
-*--fade-exclude* _CONDITION_::
+[[fade-exclude]]*--fade-exclude* _CONDITION_::
 	Specify a list of conditions of windows that should not be faded. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific fading.
 
-*--focus-exclude* _CONDITION_::
+[[focus-exclude]]*--focus-exclude* _CONDITION_::
 	Specify a list of conditions of windows that should always be considered focused. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way for doing this.
 
 *--inactive-dim-fixed*::
 	Use fixed inactive dim value, instead of adjusting according to window opacity.
 
-*--detect-transient*::
+[[detect-transient]]*--detect-transient*::
 	Use _WM_TRANSIENT_FOR_ to group windows, and consider windows in the same group focused at the same time.
 
-*--detect-client-leader*::
+[[detect-client-leader]]*--detect-client-leader*::
 	Use _WM_CLIENT_LEADER_ to group windows, and consider windows in the same group focused at the same time. This usually means windows from the same application will be considered focused or unfocused at the same time._WM_TRANSIENT_FOR_ has higher priority if *--detect-transient* is enabled, too.
 
 *--blur-method*, *--blur-size*, *--blur-deviation*, *--blur-strength*::
@@ -211,16 +211,16 @@ A 7x7 Gaussian blur kernel (sigma = 0.84089642) looks like:
 +
 May also be one of the predefined kernels: `3x3box` (default), `5x5box`, `7x7box`, `3x3gaussian`, `5x5gaussian`, `7x7gaussian`, `9x9gaussian`, `11x11gaussian`. All Gaussian kernels are generated with sigma = 0.84089642 . If you find yourself needing to generate custom blur kernels, you might want to try the new blur configuration (See *BLUR*).
 
-*--blur-background-exclude* _CONDITION_::
+[[blur-background-exclude]]*--blur-background-exclude* _CONDITION_::
 	Exclude conditions for background blur.
 
 *--resize-damage* _INTEGER_::
 	Resize damaged region by a specific number of pixels. A positive value enlarges it while a negative one shrinks it. If the value is positive, those additional pixels will not be actually painted to screen, only used in blur calculation, and such. (Due to technical limitations, with *--use-damage*, those pixels will still be incorrectly painted to screen.) Primarily used to fix the line corruption issues of blur, in which case you should use the blur radius value here (e.g. with a 3x3 kernel, you should use `--resize-damage 1`, with a 5x5 one you use `--resize-damage 2`, and so on). May or may not work with *--glx-no-stencil*. Only works with *--legacy-backends*. Shrinking doesn't function correctly.
 
-*--invert-color-include* _CONDITION_::
+[[invert-color-include]]*--invert-color-include* _CONDITION_::
 	Specify a list of conditions of windows that should be painted with inverted color. Resource-hogging, and is not well tested. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to do this.
 
-*--opacity-rule* _OPACITY_:_CONDITION_::
+[[opacity-rule]]*--opacity-rule* _OPACITY_:_CONDITION_::
 	Specify a list of opacity rules, in the format `PERCENT:PATTERN`, like `50:name pass:[*]= "Firefox"`. picom-trans is recommended over this. Note we don't make any guarantee about possible conflicts with other programs that set _pass:[_]NET_WM_WINDOW_OPACITY_ on frame or client windows. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific opacity.
 
 *--crop-shadow-to-monitor*::
@@ -275,9 +275,9 @@ May also be one of the predefined kernels: `3x3box` (default), `5x5box`, `7x7box
 	Specify a list of conditions of windows that should never have transparent clipping applied. Useful for screenshot tools, where you need to be able to see through transparent parts of the window.
 
 *--window-shader-fg* _SHADER_::
-	Specify GLSL fragment shader path for rendering window contents. Does not work when *--legacy-backends* is enabled. Shader is searched first relative to the directory the configuration file is in, then in the usual places for a configuration file. See section *SHADER INTERFACE* below for more details on the interface.
+	Specify GLSL fragment shader path for rendering window contents. Does not work when *--legacy-backends* is enabled. Shader is searched first relative to the directory the configuration file is in, then in the usual places for a configuration file. See section xref:_shader_interface[*SHADER INTERFACE*] below for more details on the interface.
 
-*--window-shader-fg-rule* _SHADER_:_CONDITION_::
+[[window-shader-fg-rule]]*--window-shader-fg-rule* _SHADER_:_CONDITION_::
 	Specify GLSL fragment shader path for rendering window contents using patterns. Similar to *--opacity-rule*, arguments should be in the format of _SHADER:CONDITION_, e.g. "shader.frag:name = 'window'". Leading and trailing whitespaces in _SHADER_ will be trimmed. If _SHADER_ is "default", then the default shader will be used for the matching windows. (This also unfortunately means you can't use a shader file named "default"). Does not work when *--legacy-backends* is enabled. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific shaders.
 
 *--dithered-present*
@@ -289,7 +289,7 @@ Window rules allow you to set window-specific options which can be used to chang
 
 Following is a list of all the options that are superseded by window rules:
 
-*--shadow-ignore-shaped*, *--inactive-opacity*, *--active-opacity*, *--inactive-opacity-override*, *--inactive-dim*, *--mark-wmwin-focused*, *--mark-ovredir-focused*, *--invert-color-include*, *--shadow-exclude*, *--fade-exclude*, *--focus-exclude*, *--rounded-corners-exclude*, *--blur-background-exclude*, *--opacity-rule*, *--corner-radius-rules*, *--window-shader-fg-rule*, *--clip-shadow-above*. As well as the *wintypes* configuration file option.
+<<shadow-ignore-shaped>>, <<inactive-opacity>>, <<active-opacity>>, <<inactive-opacity-override>>, <<inactive-dim>>, <<mark-wmwin-focused>>, <<mark-ovredir-focused>>, <<invert-color-include>>, <<shadow-exclude>>, <<fade-exclude>>, <<focus-exclude>>, <<rounded-corners-exclude>>, <<blur-background-exclude>>, <<opacity-rule>>, <<corner-radius-rules>>, <<window-shader-fg-rule>>, <<clip-shadow-above>>. As well as the xref:wintypes[*wintypes*] configuration file option.
 
 If window rules option is used, none of the above options will have any effect. And warning messages will be issued.
 
@@ -348,16 +348,16 @@ Within each sub-item, these keys are available: ::
 	Whether to make the matching window clip other windows like opaque windows do, instead of blending on top of them. When applied to transparent windows, this means nothing will be painted under the transparent parts of the window, essentially cuts a hole in the screen.
 
   shader:::
-	GLSL fragment shader path for rendering window contents. See section *SHADER INTERFACE* below for more details on the interface.
+	GLSL fragment shader path for rendering window contents. See section xref:_shader_interface[*SHADER INTERFACE*] below for more details on the interface.
 
 === Migrating old rules
 
 Most of the rule options should 1:1 map to the new window rules. Here is a list of the non-trivial ones and how to achieve the same effect with window rules.
 
-*Inactive dimming and opacity*:: This includes options *--inactive-opacity*, *--inactive-dim*, *--active-opacity*,
-*--inactive-opacity-override*, *--mark-wmwin-focused*, and *--mark-ovredir-focused*. When using the window rules, the compositor no longer have an "active window" concept, as it is easy to achieve with window rules. You can use `match = "focused || group_focused"` to match windows that would have been considered active with the old options. Then you can set the opacity and dim level for matched windows accordingly. *--mark-wmwin-focused* and *--mark-ovredir-focused* can be achieved by adding `|| wmmin` and `|| override_redirect` to the match string, respectively. *--inactive-opacity-override* can be achieved by setting `opacity-override = true`.
+*Inactive dimming and opacity*:: This includes options <<inactive-opacity>>, <<inactive-dim>>, <<active-opacity>>,
+<<inactive-opacity-override>>, <<mark-wmwin-focused>>, and <<mark-ovredir-focused>>. When using the window rules, the compositor no longer have an "active window" concept, as it is easy to achieve with window rules. You can use `match = "focused || group_focused"` to match windows that would have been considered active with the old options. Then you can set the opacity and dim level for matched windows accordingly. <<mark-wmwin-focused>> and <<mark-ovredir-focused>> can be achieved by adding `|| wmmin` and `|| override_redirect` to the match string, respectively. <<inactive-opacity-override>> can be achieved by setting `opacity-override = true`.
 
-*Active window*:: This includes option *--focus-exclude*. The *--focus-exclude* was only used to influence what windows are considered active, to apply inactive opacity and dimming. Since with window rules you no longer need the compositor to help you decide what is active and what is not (see above), the *--focus-exclude* option is no longer needed.
+*Active window*:: This includes option <<focus-exclude>>. This option was only used to influence what windows are considered active, to apply inactive opacity and dimming. Since with window rules you no longer need the compositor to help you decide what is active and what is not (see above), this option is no longer needed.
 
 FORMAT OF CONDITIONS
 --------------------
@@ -402,16 +402,16 @@ Supported predefined targets are: :::
 	Whether the window is focused.
 
   `group_focused`::::
-	Whether the window is in the same window group as the focused window. This requires *--detect-transient* or *--detect-client-leader*.
+	Whether the window is in the same window group as the focused window. This requires <<detect-transient>> or <<detect-client-leader>>.
 
   `wmwin`::::
 	Whether the window looks like a WM window, i.e. has no client window and is not override-redirected.
 
-  `bounding_shaped`::::
+  [[c2-bounding-shaped]]`bounding_shaped`::::
 	Whether the window has a bounding shape.
 
   `rounded_corners`::::
-	Whether the window bounding shape only has rounded corners, and is otherwise rectangular. This implies `bounding_shaped`. Requires *--detect-rounded-corners*. This has no relation to *--corner-radius*.
+	Whether the window bounding shape only has rounded corners, and is otherwise rectangular. This implies <<c2-bounding-shaped>>. Requires <<detect-rounded-corners>>. This has no relation to <<corner-radius>>.
 
   `window_type`::::
 	Window type, as defined by _pass:[_]NET_WM_WINDOW_TYPE_. Name only, e.g. _normal_ means _pass:[_]NET_WM_WINDOW_TYPE_NORMAL_.
@@ -540,6 +540,7 @@ picom uses general libconfig configuration file format. A sample configuration f
 
 Window-type-specific settings allow you to set window-specific options based on the window type. These settings are exposed only in configuration file. Using this is discouraged, see the xref:_window_rules[*WINDOW RULES*] section for the recommended way to set window-specific options. The format of this option is as follows:
 
+[#wintypes]
 ------------
 wintypes:
 {