include

• A search of the xwiki-platform sources: 281 of the 282 include calls of its wiki pages use the reference parameter, 3 also set author and 3 set context, none sets section.

C1: the name is shown as "Author." with a trailing period, and the description "The author to use to execute the content when context is "Current"." refers to the context parameter, which is deprecated and hidden from the dialog, and does not explain the values Auto, Current and Target or that they decide the rights the included content runs with. Open the Edit Macro dialog of {{include reference="Sandbox.TestPage1"/}} , Optional parameters.

C9: realistic use: running the included content with the rights of the current page instead of those of the included page.

C9: deprecated, hidden from the Edit Macro dialog unless the macro already sets it.

C9: deprecated, hidden from the Edit Macro dialog unless the macro already sets it, where it is offered as a third alternative of the Reference feature.

C1, minor: hidden, but shown when the macro already sets it, like the first example of the documentation, {{include page="Sandbox/TestPage1"/}} . The Edit Macro dialog of that macro then shows two alternatives named "Page" with the same description "The reference of the page to include.", page and reference, with no way to tell them apart.

C4, minor: in the same case, a plain text field, while the reference alternative next to it has a page picker.

C9: hidden from the dialog of a new macro.

C2: not mandatory itself, but it is the only shown alternative of the required Reference feature; no default makes sense, the current page would include itself.

C4: a page picker that finds the page by its title, its name or its reference, and also accepts a typed reference.

C1: the description "An optional id of a section to include in the specified page." does not say that the id is "H" followed by the heading title without spaces, like HMySection, so the user cannot guess what to type. The German description explains it.

C4: a plain text field where the user must type a generated heading id, while the headings of the chosen page could be offered in a picker: to include the "My Heading" section the user has to work out and type {{include reference="Page1.Page2" section="HMyHeading"/}} , and a heading with accented letters gives an id with hexadecimal codes, like HCafE9.

C6: used by one example of the documentation, but listed last in the Optional parameters, after Author, which no example uses. The most common example sets only the page, which comes first, so the order is OK.

C9: hidden from the Edit Macro dialog; the Page picker sets the reference type.