Wiki
Clone wikiKeysight Plugins For Atlassian Products / Confluence Plugins / Guidance Plugin
Introduction
The guidance plugin provides a set of macros use to facilitate the usage of the DO, CONSIDER, AVOID, and DO NOT convention made popular in Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries by Krzysztof Cwalina and Brad Abrams. The macros try to provide the ✔ and the ✘ glyphs as a unicode font character that scale perfectly; however, under depending on the plugin configuration circumstances it will provide a raster image instead
Nice rendering in HTML, PDF and Word
Thee macro has a configuration page which can be accessed from the Confluence Add-on manager. In the configuration the Confluence Administrator can decide how the macro will render the glyph (as a unicode character or a raster image) for various output formats. Experimentally, the default pdf output does not render the unicode font characters correctly so the default for that format is raster.
Features at a Glance
Feature | Description |
---|---|
Guideline Inline | A macro to insert a guidance term inline with text. |
Guideline Block | A macro to insert a guidance term at the start of a block. |
Do, Consider, Avoid and Do Not Macros | Shortcut macros to the variation of the block macro. |
Features in Detail
Guideline Inline
Description
This macro inserts the glyph and text inline with the rest of the text. In the editor, it will simply show a graphic with the text.
Usage
Insert the Guideline (Inline) macro. Click on the macro and select the guidance term to be used. Alternatively, one can press the edit button and select the guidance term from the dropdown.
Purpose
This macro is intended for inserting the text prior to a short sentence or paragraph. It is a bit easier to read in the e
Guideline Block
Description
This macro inserts the glyph and text in a block with the rest of the text. If the block of text starts with one of the guidance terms (Do, Consider, Avoid or Do Not) and the Guidance macro parameter is set to auto, the macro will automatically insert the appropriate glyph and bold the text. If the macro's Guidance Parameter is set to auto and the text does not start with one of the terms, an error message and alert will be shown. If the guidance term is not set to auto, the macro will insert the appropriate text. If the text also starts with the guidance term, the text will not be rendered twice.
Usage
Insert the Guideline (Block) macro. While the guidance term can be explicity set, the recommended usage is to type the guidance term into the start of the body. This make is more readable in the editor.
Purpose
This is the appropriate macro to use for multi-paragraph guidance descriptions. All of the text will be indented for the guidance term giving the reader a visual clue that it all belongs to one rule.
Do, Consider, Avoid and Do Not Macros
These are shortcuts to the block guideline macro where the guidance term is fixed to the name of the macro.
Updated