projectdoc Toolbox

In case an author requires to identify document elements to readers, for instance a numbering of paragraphs or sentences, the Content Marker Macro allows to employ a page-related auto-numbering and provides means to specify the format for these consecutive numbers.

Audience
Type
Level of Experience

The Content Marker Macro allows to wrap content with an identifier to form a content element. It also allows to associate the content element with a sequence number. The projectdoc Toolbox then auto-numbers the content elements and allows to render this number with the content element.

This is helpful for documents where readers need to identify content elements like paragraphs or sentences.

This tip shows a use case where the Content Marker Macro is used to track the definitions and explanations within a specification document.

Prerequisites

This feature is supported with version 4.12 of the projectdoc Toolbox.

Use case

For a specification document suppose to add a number on definitions and explanations.

Each definition and each explanation is enclosed on a Content Marker Macro. Each definition (Def.1, Def.2, ...) and each explanation (Expl.1, Expl.2, ...) should have its own sequence number for unique identification within a document.

Implementation

For this example there are three definition and two explanations within a chapter of the specification document.

Each content marker has an identifier (D.1, E.1, D.2, D.3, and Example.1) and a Render Counter (definition or explanation).

The identifier is not related to the render counter. It is probably more stable to identify the element not by the sequence name. If they are not related, references to the content need not to be changed if another content of the same type is added in front at a later time. You may either use a text phrase or some arbitrary identifier.

Styling the Render Counter

Without any formatting, the rendered content looks like this:

You may add appropriate styles for your design to you space or site style sheet. Alternatively you may use a render template or combine the two approaches.

CSS Styles

Each counter is rendered with the class projectdoc-render-counter-element plus the name of the render counter.

CSS Class Names
projectdoc-render-counter-element definition

Render Counter Template

Add the style information as a space property Render Counter Template named projectdoc.renderCounterElement.template. and append your render counter name (e.g. projectdoc.renderCounterElement.template.definition).

For a layout with tooltip you may use the Layout Element Macro.

Define the label for the counter in the body of the Layout Element Macro.

Note the use of {} as a placeholder for the consecutive element counters. 

The rendered content is now:

Multiple Elements

It is possible to add multiple elements within one paragraph. In the following example we assume that D.1 and E.1 belong together and D2, D.3, and Example.1 also should be part of one paragraph.

The Content Marker Macros are enclosed in additional Content Marker Macros where the Merge Block Elements parameter is set to true.

This is the rendered content:

Render Counter Context

The render counter context allows to define render counter sequences with the same name in different contexts. Each context is identified by its name. A Content Marker Macro is associated with a Render Counter and optional with a Render Counter Context, defined by parameters.

The render counter context is especially useful if the Content Marker Macros are transcluded on the same page. In this case set the Render Counter Context on a wrapping Content Marker Macro around the source content.

Multiple Documents

In case the chapters of a document are on separate pages, the start value may be specified by a document property of the following format:

{render-counter-context}#{render-counter}

Example for valid Values

 
  • #definition
  • source#definition

References

Content Marker Macro
Marks a piece of content within a document. This content can be referenced for transclusion.
Render Counter Template
Provides a template to render the counter tracking elements of the Content Marker Macro.
projectdoc-render-counter-element
Marks the counter element rendered by the Content Marker Macro.
Skip rendering Counter Element
If counter elements are rendered purely by CSS styles, setting this flag to true prevents the rendering of the counter within its own HTML element.