In this article, we’re going to look at the ‘markers’ (or ‘call-outs’) that typically appear in documents generated for simulations. These are the numbers in circles that point to the ‘action areas’ on the screenshots, as shown in the example below:
You probably don’t usually give these a second thought, as they are generated by default, automatically, and ‘just work’. However, there are a few interesting things you can do with them – and some things it is worth knowing you can’t do. So let’s look at these.
Most of the useful settings related to Markers are defined in the Documentation Settings resource for the relevant document type, under the Markers category. Here’s a typical example:
Most of these are self-explanatory, but a few are worth noting:
- Highlight Offset: This specifies the number of pixels of ‘padding’ that should be left between the outer edge of the ‘action area’ (as defined by the Highlight Position / Size property of the action – see Figure 3) and the inner edge of the Highlight.
- Border: This specifies the width of the Highlight drawn around the action area. Note that this extends outwards, so will never overlap the action area or ‘eat into’ the padding. This width is applied to the Highlight and the ‘connector line’ pointing to it, but will not apply to the border of the Marker circle itself – that always seems to be approximately 2 pixels.
- Arrow Length and Arrow Width: Despite their location within the Markers category, these have nothing to do with the Markers. They actually specify the width and length of the arrow head on a Documentation Arrow macro (which, as we’ll see shortly, doesn’t even conform to the Marker settings the way you’d think it would…).
These settings apply to all Markers in the applicable document type. There is also a single setting for individual actions in the simulation project. This is the Marker Orientation property, in the Documentation category, highlighted below:
By default, Marker Orientation is set to Auto, which means that SAP Enable Now will automatically determine the best position for the Marker in relation to the highlight, to ensure there is no overlap or ‘crowding’ of Markers. If necessary, you can ‘force’ a particular position of the Marker for an individual action by selecting the required orientation (again, of the Marker in relation to the Highlight) in this field. This has been done for Marker [5] in Figure 1, which is set to East; all others were positioned automatically (and were given values of Southeast, West, and Northwest as necessary).
(Incidentally, if you’re wondering how you can define the length of the connector between the Highlight and the Marker (‘number circle’): you can’t. It is always set to a default length that can’t be changed. However, setting a Marker Orientation of Auto will typically take care of making sure the Markers never overlap, so you never really need to worry about this. Even if you manually set specific orientations, SAP Enable Now will override these if it needs to, to ensure no overlap.)
So far so good. Now let’s look at one last category of settings that influence Markers. These are back in the Documentation Settings resource, but this time under the Numbering category.
We’ll start with the easier one first – the Style setting. This is a simple drop-down list providing three choices for how the numbered list (of actions) below the screenshot is formatted. Choices are effectively “(n)”, “[n]”, and “n.”. It’s worth noting here that these don’t actually use a ‘numbered list’ format in Microsoft Word (with tabs and indents to align the text). Instead, they are formatted as paragraphs that have the number (in the selected format) at the start of them. You can see this in Figure 1, where the text for Marker [3] is a single paragraph, but is all left-aligned.
The final setting is the Indexing setting. This is more interesting, and has much larger implications than the settings we’ve looked at so far. This setting controls the way the numbers that appear inside the Markers are generated. It has five possible values:
- Step – highlights only
- Step – all objects
- Global – highlights only
- Global – all objects
- None
First, let’s look at the difference between the two ‘Step’ options and the two ‘Global’ options. For the Step options, numbering (of the Markers and the associated Step/Action list (or table)) (re)starts at 1 with each Step. Technically, this is actually ‘with each heading‘ – regardless of whether the heading is being taken from the Step Name, the Screen Title, or the Partial Screenshot Title (see the Project Content > Headings from setting for the document type) – although, inconsistently, a Documentation Heading macro will not restart the numbering (but see below).
If a Global option is used, then numbering starts at 1 at the beginning of the document and all Markers are numbered incrementally from this, all the way to the end of the document (that is, in a single sequence). In Figure 1, a Global option has been used – you can tell this because the first Marker has a number of [3], even though it is the first Marker following the heading. (If you’re wondering if 2- or 3-digit numbers will still fit in the Marker circle, don’t worry; the circle is elongated horizontally to always contain the number – as you can see for Markers [10] and [11] in Figure 1.)
Complicating things slightly, the Documentation Description macro has a property named Reset Global Index Counter. If you select this, numbering will restart at 1 with the next item in the list. Despite the property name, this is done regardless of whether a Global option or a Step option is used for Indexing. Interestingly, the Text property of the Description macro is not mandatory, so you can leave it blank. This means that if you want to insert your own heading in your document and restart (Global or Step) numbering following this, you can insert a Heading macro, followed by an ’empty’ Description macro that has its Reset Global Index Counter property selected, and this will achieve the desired effect.
Now let’s look at the difference between the two ‘highlights only’ options and the two ‘all objects’ options. If you use a ‘highlights only’ option, then only the interaction macros will have Markers and be listed in the Step/Action list. This includes all of the ‘action’ macros (Mouse Action, Input Text, and so on), and any Explanation macros that have a defined Document Highlight (this is an important qualifier – see below).
If you use an ‘all objects’ option, then some additional items will also have Markers and be listed in the Step/Action list. Specifically, these are:
- Explanation macros that do not have a defined Document Highlight and that have an Icon setting of None. (If a specific Icon is used, the Explanation is not included in the Step/Action list, but is formatted in a 2-column table.) In Figure 1, Marker [3] is for such an Explanation macro (note there is no associated Document Highlight, and no Icon).
- Document Highlight macros that have a specified Text. In Figure 1, Marker [4] is for a Document Highlight macro.
Strangely, ‘all objects’ does not include Documentation Arrow macros, or Documentation Notes macros. Further adding to the inconsistency, a Note macro does not include a None option on the Icon property which in theory would allow it to be included in the Step/Action table.
Finally, let’s look at the None option for the Indexing setting. If this value is selected, then no Markers are shown in the document, and the Step/Action list is a simple list of paragraphs, without numbering. So, effectively, this option obviates all other Marker settings. If you generate a Training Guide document type (where the Step/Action list is formatted as a table) the Step column will be blank – so this option is not recommended for this document type.
In summary, although the default settings and behavior of Markers are perfectly adequate, there are additional capabilities – especially with regard to what other objects can be included in the Marker list – that are worth investigating.
