Repeat blocks in Commands

A “repeat block” is a fixed chunk of keywords that can be applied to all keywords one level above it. The repeat block is used to present the chunk of keywords once on the command reference page, rather than repeating the block (hence the name) after every keyword above it.

Repeat blocks cannot be nested (you can’t attach a repeat block to the keyword in a repeat block), but it is possible to have more than one keyword block on a command (however unlikely).

See zone apply or ball attribute for illustrations.

Construct as follows.

1. In the body of the main command reference, the keyword block is denoted in square brackets ([ ]) by a unique name, specified at the appropriate location, within a keyword signature:

   .. kwd:: Velocity [zonefieldoptions]
   

2. Below the main body of the command, the block is presented. The section starts with a .. rubric::

   .. rubric:: Optional Block Apply Modifiers
      :class: h2
      :name: zonefieldoptions
   

   Here, most importantly, the :name: argument of the directive must exactly match the unique name supplied in the preceding keywords.

3. A description of the content of the block follows:

   The modifiers listed below are available to specify additional information for the following geometry paint-extra keywords:

Here note the colon. This is done because item 5. below will cause the list of major keywords that take this repeat block to be listed after the colon.

4. A list of keywords then follows. Each keyword must be given the argument :class: rblock

   .. kwd:: XDX
      :class: rblock
   
      Get the `x`-component of the vector.
   

5. Optionally, a keyword can also be given the :rblock-list-before: argument. When this is done, it causes the major keywords that take the repeat block to be listed above the current keyword, at the end of whatever matter precedes this keyword. This is a trick of sorts to allow listing which commands use the repeat block at the end of the descriptive matter introducing the block — so it should really only be used once, on the first keyword in the block.:

   .. kwd:: ALWays-First
      :class: rblock
      :kwd-list-before:
   
      This keyword is the first keyword in the block.
   

6. Optionally, a keyword can take either the :include: or :exclude: arguments. Either should have one or more (comma separated) keywords listed following the argument word. These cause the keyword to be omitted from the keyword(s) listed (:exclude:), or to be applied only to the keyword(s) listed (:include:). No newline at end of file