While in HTML the purpose of anchors is mostly for jumping to a position in the text,
in PmWiki they serve an internal purpose, too:
Each anchor also creates a section, because sections are defined as
the part of the page between their start anchor and the next anchor.
A section name is defined as the name of its start anchor.
Usage scenarios for sections include:
- To include parts of a page in another one or in itself.
- Easy retrieval of parts of a page in PHP, using the
RetrieveAuthSection() function.
- Re-use them as templates with include variables for dynamic parts.
- In blocks of conditional markup, you can defer interpretation of markup that would usually be parsed before the conditions. One way to achieve this is to interrupt the early markup's keyword by putting a bogus include variable in its middle, thus making it some invalid garbage. If the conditions are met to trigger your include command, then the section with the deactivated markup will be interpreted once again, but only after the include variables are replaced. Since your bogus variable has no text, it will just disappear, so this time it won't invalidate the early markup.
Rules for valid section names are by definition the same as for anchors (described in Links#anchors),
but in practice there are some additional limitations:
- If the name ends in more than one dot, the
(:include:) command and RetrieveAuthSection() can use it as an end anchor but not as a start anchor.
You can try some experiments on the Test.ExoticSectionNames? page or even just its preview.
Beware of subtle differences:
- If an anchor in the middle of a line is used as start anchor for the
(:include:) command, it reads from the beginning of the line that has the anchor and will include the [[#anchor]] markup, which results in an HTML anchor being generated.
- In comparison,
RetrieveAuthSection() will start reading text from exactly after the mid-line start anchor.
- When using an anchor in the middle of a line as end anchor though,
RetrieveAuthSection() behaves the same as the (:include:) command, about which Include Other Pages warns: It will stop reading at the beginning of the line that has the end anchor, so the last thing included will be the end of line character from the line before the end marker.
- To avoid the final EOL produce whitespace behind your
(:include:) command, end the line before the end anchor with a line joiner (backslash).
