Add Topic Content – Paligo

In Paligo, you write content as separate pieces of information, see Topic-Based Authoring.

The Paligo Editor is designed to hide the code to simplify the writing process. You can still view the structure in the Element Structure Menu, XML Tree View or Source Code Editor.

First you Create a Topic and then to add content you use the Toolbar or the Element Context Menu. To work smoother, use the Keyboard Shortcuts.

You can add About Elements, Informal topics as well as nest existing components. When you are ready to save the content it will be validated.

A topic in the Paligo editor. It has a title, paragraph and a procedure with 3 steps. The text in the first step is selected. At the top, the element structure menu shows section, procedure, step, para.

XML tree view of a topic containing a title, paragraph, and a 3-step procedure. The XML tree has blue labels for each structure element (section, title, para, procedure, and step) and these are organized into a hierarchy.

To the left the Element Structure Menu. To the right the XML Tree View.

Note

You can add as many Block Elements and Inline Elements as you need, but the maximum permitted size for a topic is 1 MB.

Attributes

Every element has a set of attributes, which are properties that define the element's characteristics. Each attribute has a value, and by changing the value, you can control how Paligo uses the element.

Attributes are handled in the Element Attributes Panel.

Style with Attributes

Some common examples of how you can use the element attributes are:

Set the width attribute of an imageobject to control its size in the output, for example, width: 50%
Set the role attribute of a section to accordion so that the section appears as a collapsible section in the output
Set the audience attribute of para to developer so that the paragraph only appears in content aimed at developers.

Style with Attributes are handled in the Element Attributes Panel. You can use the advanced search to find components that contain specific attributes and profiling values, see Search for Attributes.

By selecting the element, currently applied attributes and values are shown in the Element Attributes Panel (1). You can add extra attributes from the Add attribute drop-down menu (2). If you add an attribute, you also need to set its value in the field next to the attribute name (1). You can also use the fields to change any existing attribute values. To find out more, see Attributes.

1 = Element attributes panel, 2 = Add attribute drop-down menu

Tip

If a topic contains information about several products, it can be suitable to create Favorite Profiles that contain certain filters and variables to switch on when viewing content or sending content to reviewers or contributors.

Add Attributes

Attributes are used for many different purposes in Paligo, including applying filters to your elements to include or exclude content in different scenarios. Many attributes come from the DocBook standard, but there are some Paligo-specific ones too.

To add attributes to an element:

Select the element in the topic.
Place the cursor in the Element Structure Menu below the toolbar.

Note

When you select an element in the Element Structure Menu, Paligo highlights it in yellow.
Select the element and choose Go to element to show the attributes for this particular element.

The Element Attributes Panel. now shows the attributes for the selected element.
Use the Add attribute search to enter the name of the attribute or scroll through the available options.

In the image above the attribute will be added to a para element .
Select the attribute to be inserted .

Note

You can only add attributes that are valid for the selected element.
Give the attribute a value. Depending on the attribute type:
- Select a menu option.
- Enter the value manually in a text-entry field.
- Check a box in front of a profiling value or Create Profiling Values
To the left - The attribute width has a manually entered size value. To the right - The attribute audience has a list of profiling values to choose from.
Select Save.
Repeat this procedure for any other elements that need attributes.

Tip

To remove an element attribute, see Remove Attributes.

To update a profiling value for an attribute, see Add or Remove Profiling Values.

Add Multiple Values to an Attribute

Element attributes are properties that you can add to an element, such as a section or table. There are many different attributes you can use, and you add them in the Element attributes panel (see Style with Attributes). When you add an element attribute, you also have to set its value. Typically, they have one value, but you can add multiple values when needed.

For example, if you want to use the role attribute to assign a class name to a section and also make it collapsible, you would need to add two values. In this case, "accordion" to make it collapsible and then another value for the class name.

To add multiple values:

Use the Element attributes panel to add an attribute to an element.
Enter the values in the field next to the attribute. Separate the values like this:
- Use a semi-colon to separate values. For example, here, the role attribute is given two role values: accordion and subsection. A semi-colon is used to separate the values.
```
role="accordion;subsection;"
```
- Use a colon to separate "keys" from values. "Keys" are properties that can have values. They are only suitable for certain attributes, such as the style attribute that you can give to a table element. For example:
```
style="border-style:solid 2px;border-color:blue;"
```
  Here, the attribute is style. The first key is border-style and it is separated from its value (solid 2px) by a colon (:). The second key is border-color and it is separated from its value (blue) by a colon (:). Each key and value pair is separated from the next by a semi-colon (;).
Select Save.

Note

Some attributes allow the space character as a separator. For example, if you add a role attribute and set its value to "specifications table", it will get two class names in HTML when it is published. In the HTML, it will appear as class="specifications table" which means "specifications" is a class and "table" is a different class.

For this reason, it is best practice to avoid using spaces inside a value that you want to become one class. For example, use "specifications-table" as this will be one class, rather than "specifications table" which will be two classes.

Remove Attributes

Each element in Paligo can have attributes, which are properties. For example, a paragraph could have a role attribute with the value "example-style" so that it can be styled differently from other paragraphs by using CSS. If an attribute is no longer needed, you can delete it.

To remove an applied attribute:

Select the element in the topic.
Place the cursor in the Element Structure Menu below the toolbar.

Note

When you select an element in the Element Structure Menu, Paligo highlights it in yellow.
Select the element and choose Go to element to show the attributes for this particular element.

The Element Attributes Panel. now shows the attributes for the selected element.
Place the cursor over the attribute in the Element Attributes Panel and select the X to remove it from the element.
Select Save.

Supported Attributes

Paligo is based on DocBook 5.1 and supports most of the attributes that are included in that content model. Read more about DocBook 5.1. But there are some differences to consider that Paligo:

Uses the <article> element for publication topics, see Supported Info Elements.
Uses the <section> for topics.
Does not support other root-level elements such as <book> and <set>.

Caution

Paligo also supports some "internal attributes" such as xinfo:image, xinfo:resource, and xinfo:text. These "internal attributes" are created and maintained automatically by Paligo and are used for allocating IDs to elements. You should not edit them.

Every element has a set of attributes, which are properties that define the element's characteristics. For each attribute, there is a value, and by changing the value, you can control how Paligo uses the element. Common usage areas are:

Filter Attributes to include or exclude content, see Filtering / Profiling and Create Profiling Values.
Width attributes for adjusting image sizes.
Role attributes for various features, including collapsible sections and adding class names to HTML, see Role Attribute Values.

Element attributes panel. The td element is selected and it has a style attribute. The value of the style attribute is set to background-color:bg1

Above Style is the attribute and background-color:bg1 is the value.

Paligo supports the Filter Attributes as well as the following attributes:

Attribute	Description
depth	Use on the `imagedata` element to set the image depth (height) value in relation to the viewport. The viewport is the available space for the `imageobject`. Learn more about Image Sizing.
contentdepth	Use on the `imagedata` element to set the image depth (height) value and has no effect on the viewport. The viewport is the available space for the `imageobject`. Learn more about Image Sizing.
contentwidth	Use on the `imagedata` element to set the image width value and has no effect on the viewport. The viewport is the available space for the `imageobject`. Learn more about Image Sizing.
continuation	To get a continued numbering in sidebars, see Use Numbering in Sidebars.
label	Use on a topic's `section` element to prevent it being numbered in a PDF output (a value of `0` means no numbering).
language	Use on a `programlisting` element to set the language for a code sample, see Syntax Highlighting.
role	Use the role attribute with specific values to set Paligo to provide particular functionality, see Role Attribute Values
scalefit	Allows an image to be scaled up or down to fit within available space. If `scalefit="1"` the image is scaled (with the same factor in both dimensions) so that the graphic will just fit within the available height or width (whichever is more constraining). If any other image size attribute is specified, those attributes determine the graphic size and `scalefit` will be ignored.
style	Style the background colors for individual individual table cells (`td` or `th`) for PDF output, see Style Table Body (PDF).
tabstyle	Style the `table` element to use compact paragraph spacing, see Set Table Cell Paragraph Spacing.
width	Use on the `imagedata` element to set the image width value in relation to the viewport. The viewport is the available space for the `imageobject`. Learn more about Image Sizing.
xinfo:appid	Use on the `section` element when setting up context-sensitive help, see Context-Sensitive Help. The `@xinfo:` prefix tells that this is an extension attribute.
xinfo:chunk	Use on the `section` element to instruct Paligo to keep a topic as a separate page in HTML outputs, see Create Subsections. The `@xinfo:` prefix tells that this is an extension attribute.
xinfo:keep-together	To control the flow of elements over two pages in PDF outputs, see Soft Page Breaks. The `@xinfo:` prefix tells that this is an extension attribute.
xinfo:keep-with-next	To control the flow of elements over two pages in PDF outputs, see Soft Page Breaks. The `@xinfo:` prefix tells that this is an extension attribute.
xinfo:outname	Use on the `section` element to control the URL for the topic when it is converted into a page for HTML outputs. The value that you enter is used as the URL, see Topic File Names. The `@xinfo:` prefix tells that this is an extension attribute.
xinfo:pagebreak	To set a hard page break in PDF outputs, see Hard Page Breaks. The `@xinfo:` prefix tells that this is an extension attribute.
xlink:href	To make images work as links, see Turn Images and Other Elements into Links.
xlink:show	To override the default link behavior for individual links, see Update Individual Link Behavior.

Tip

To learn how to add an element attribute, see Attributes.

Role Attribute Values

You can use the role attribute with specific values to set Paligo to provide particular functionality. There are many possibilities, including adding class names to HTML outputs, adding extra-responsive features to HTML tables and controlling wrapping in PDF output.

Element attributes panel. The role attribute is added and it has a value of extra-responsive

Tip

If you already have a role attribute, separate the values with a semi-colon.

The following table shows the role attributes and values that you can use in Paligo.

Attribute value	Description
accordion	Use to create a collapsible `section`. The section title is shown and when the user selects it, the section expands to reveal the content, see Accordions (Collapsible Sections).
column-count	Use to set the number of columns in a `sidebar` element in PDFs, see Enable Multi-Columns (PDF).
column-gap	Use to set the amount of space between columns in a `sidebar` element for PDFs, see Enable Multi-Columns (PDF)).
extra-responsive	Use on `table` elements to set them to add a sticky header and column filter to a table for HTML5 outputs, see Enable Column Filter and Sticky Header.
font-size	Use to set the size of the lettering on a verbatim element, such as `programlisting` , see Verbatim (code and software).
<free text>	Can be used on any element and you can enter any text as the value, for example, role: online-image. The value is used as a class name in HTML outputs. This only applies if the HTML layout is set to include the role attribute as a class name, see Classes and Attributes HTML5.
img-thumbnail	Use on `mediaobject` elements to set them as small "thumbnail" images in HTML outputs, see Thumbnail Images.
img-thumbnail-reset	Use on `mediaobject` elements to prevent them from being presented as small "thumbnail" images in HTML outputs, see Thumbnail Images.
multi-publication-portal	Use on `article` elements when publishing multiple publications to the same help center, see Multi-Publication Portal.
notintoc	Use on `section` elements to prevent a topic from appearing in the table of contents in PDF outputs, see PDF Layout Editor Options.
portal-category	Use on the `section` element to create category panels for topics in HTML help center outputs, see Topics for Category Panels.
promoted-content	Use on the `section` element to set a topic as "featured content", see Topics for Featured Content.
reuse-range	Use on `procedure` and `orderedlist` elements when you want the steps/items to continue the numbering sequence of a previous procedure or list, see Reuse Items in a List.
swagger-topic	Use on the `section` element when embedding Swagger/Open API content in Paligo for publishing to: HTML help center, see Embed Swagger OpenAPI Zendesk, see Embed Swagger OpenAPI for Zendesk
top-nav-link	Use on the `section` element to add a link to a topic from the top-navigation menu, see Add Top-Navigation Links to Topics.
wrap-option	Use on verbatim elements, such as `programlisting`, to control line wrapping, see Verbatim (code and software).

Author Remarks

The remark element is a regular DocBook Element and works like an internal comment (author notes) inside the topic. For example it can be used as a tip, an internal instruction or a reminder for other authors. It will only be visible to authors working in the Editor View and not displayed to the end users.

The remark element is not handled via the Element Attributes Panel since it has no profiling values. It is visualized in the enclosing "box" highlighted in yellow with a lock and a green speech bubble.

Add Author Remarks

By default, the remark element comments are not shown in published output. But there is a way to include them in the PDF output, see The Basics of Topic Editing. However it cannot be made to appear in an HTML output.

Note

A remark element has no relation to the Review or Contribution assignments and will not be a part of those.

Place the cursor where the remark element is to be inserted.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Enter Remark and select it from the Element Context Menu.
Enter the internal comment.
Select Save.

Note

If you click on an area outside the remark element, the editor will highlight the enclosing "box" in yellow.

Remove Author Remarks

This section describes how to remove a remark.

Select the Remark element in the topic.
Place the cursor in the Element Structure Menu below the tool bar.
Select the element and choose Delete.
Select Save.

Add Block Elements

To add structural "block" elements to a topic:

Open your topic in the editor.
Position the cursor (also known as the caret) where you want to add a block element. You can position the cursor manually or you can select an element in the element structure menu and choose Go to element. (The element structure menu is immediately below the toolbar, and it shows the position of the currently selected element).

The position of the cursor is important as there are rules that govern where each type of element can be used. For most types of block element, you can place the cursor on the next line, just like you would in a word processing program. But there are some exceptions, for example, you cannot add a table inside a para element.

Paligo will advise you if you try to add an element in a position that is not permitted.
Add the element for the type of content you want to insert. There are several ways to add elements:
- Use the Edit toolbar and Insert toolbar to add commonly used block and inline elements, including paragraphs, images, tables, italicized text, and underlined text.
- Use keyboard shortcuts.
- To display the Element Context Menu, press:
  Windows: Alt + Enter ⏎
  
  Mac: Command ⌘ + Enter ⏎
  At the top of the element context menu, there is a search field that you can use to find an element by name. When you start to type in the field, the list updates to show those elements that are a close match to your entry and are valid at the current position.
  
  Alternatively, you can select one of the most commonly used elements from the top section of the list or scroll down the entire list to find the element you want.
  
  The element context menu only shows the elements that are valid at the position you have selected in the content structure. If you cannot see the element you want, it is because it is not valid at that position. Try selecting a different position.
  
  Note
  
  You can choose your own favorite elements and have those appear at the top of the element structure menu. For details, see Working with Element Context Menu.
Add your content inside the block element. For paragraphs, list items, etc., enter your text. For some types of block element, Paligo prompts you to choose an image, enter a video url, etc.

Add Inline Elements

To add inline elements to the text in a topic:

Open your topic in the editor.
Highlight the content that you want to apply the inline element to.
Add the element for the type of content you want to insert. There are several ways to add elements:
- Use the Edit toolbar and Insert toolbar to add commonly used block and inline elements, including paragraphs, images, tables, italicized text, and underlined text.
- Use keyboard shortcuts.
- To display the Element Context Menu, press:
  Windows: Alt + Enter ⏎
  
  Mac: Command ⌘ + Enter ⏎
  At the top of the element context menu, there is a search field that you can use to find an element by name. When you start to type in the field, the list updates to show those elements that are a close match to your entry and are valid at the current position.
  
  Alternatively, you can select one of the most commonly used elements from the top section of the list or scroll down the entire list to find the element you want.
  
  The element context menu only shows the elements that are valid at the position you have selected in the content structure. If you cannot see the element you want, it is because it is not valid at that position. Try selecting a different position.
  
  Note
  
  You can choose your own favorite elements and have those appear at the top of the element structure menu. For details, see Working with Element Context Menu.

Add a Sequence of UI Options

Abstract

Learn how to use the menuchoice element to add a sequence of options inside a single instruction. For example, "select File → Save".

When you are writing instructions, you may want to tell readers to select several options in a sequence. Paligo XML includes elements that are designed especially for this purpose.

You can either:

Insert a menuchoice element as a container and then add the various user interface elements inside it.

With this approach, Paligo will automatically insert an arrow symbol between the user interface elements in the sequence. For example:
Insert the user interface elements directly into a para, without using menuchoice. Paligo will not generate an arrow icon, so you will need to add text between the user interface elements, for example:

Note

Inserting user interface elements directly into a para, without using menuchoice, can give a better user experience for screen reader users. (If you use menuchoice, screen readers may read out the user interface options and also the arrow symbol).

There are several user interface elements that you can use, including elements for menus, menu items, and keyboard shortcuts. We describe them in the following procedure. But it is up to you to decide how detailed you want your structure to be. You can take a purist approach and use all of the elements as intended, or a simpler approach where you use one element, such as guilabel, to represent all user interface options.

Select the topic or component in the Content Manager to open it in the Editor.

Alternatively, you can Create a Topic and edit that.
Find or add the paragraph that will give the instructions to select a sequence of options. Click in the paragraph at the position where you want the sequence to appear.

If you are going to use the menuchoice element so that Paligo automatically includes an arrow icon between UI elements, continue from step 4.

If you are not going to use the menuchoice element and are going to insert the UI elements directly into the paragraph instead, continue from step 5.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Enter menuchoice element and add it.
Click in the "parent" element:

If you are using the menuchoice element, click in the menuchoice element you added in step 4.

If you are not using the menuchoice element, click in the para element you selected in step 3.
Use the element context menu to add one or more of the following user interface elements:
- guilabel
  
  Use to contain the name of a label. When you have added the element, enter the name inside it.
- guibutton
  
  Use to contain the name of a button. When you have added the element, enter the name inside it.
- guiicon
  
  Use to contain the name of an icon. When you have added the element, enter the name inside it.
- guimenu
  
  Use to contain the name of a menu. When you have added the element, enter the name inside it.
- guimenuitem
  
  Use to contain the name of a menu option. When you have added the element, enter the name inside it.
- guisubmenu
  
  Use to contain the name of a submenu. When you have added the element, enter the name inside it.
- shortcut
  
  Use to contain keyboard shortcut details. When you add the shortcut element, you can add keyboard shortcut elements inside it, including keycap, keycombo, and keysym for keyboard keys and mousebutton for mouse actions.
  
  To learn more about these elements, see the DocBook 5.2 standard (they are listed as children of shortcut).
Repeat the previous step until you have created the structure for every option in the sequence.
Select Save.

You can then publish your content.

Note

To style the user interface elements, use CSS for HTML outputs and the PDF layout editor options for PDF.

For details, see:

Example 35. A sequence of UI options and an alternative keyboard shortcut

Let's say you want to add an instruction that tells users to select a File menu and then a Save option inside that menu. You also want a paragraph that tells them how to use a keyboard shortcut as an alternative.

When you publish, it will look something like this:

Paligo adds the arrow between File and Save automatically, as the structure is set up to use the menuchoice element.

The underlying XML for this is as follows:

<para>When you have completed your design, select 
    <menuchoice>
        <guimenu><emphasis role="bold"><emphasis>File</emphasis></guimenu>
        <guimenuitem><emphasis role="bold"><emphasis>Save</emphasis></guimenuitem>
    </menuchoice>.
</para>
<para>Alternatively, use the keyboard shortcut: 
    <menuchoice>
        <shortcut>
            <keycombo>
               <keycap>Alt</keycap>
               <keycap>S</keycap>
            </keycombo>
        </shortcut>
    </menuchoice>
</para>

So to create it in a topic, you add two para elements for each paragraph.

Inside the first para, you add the text that comes before the menu name and menu option. You then add the menuchoice element as the container and inside that, the guimenu and guimenu item elements. You enter "File" in the guimenu and "Save" in the guimenuitem. As these are not styled as bold automatically by Paligo, you also use the bold toolbar icon on "File" and "Save". In the code, this adds emphasis role=bold to those words.

Inside the second para, you add the text that comes before the keyboard shortcut. You then add the menuchoice element as the container. Inside menuchoice, you add a shortcut element, and inside that keycombo. Inside the keycombo, you add two keycap elements, one for each key that needs to be pressed. Finally, you enter the text for the keys inside the keycap elements, in this case, Alt and S.

Inline Elements and Symbols

There are many elements that you can use on parts of your text inside a paragraph, for example, you can make a word appear italicized by using the emphasis element, see Emphasis. These elements are inside a block element, and so are known collectively as "inline elements".

You can also insert special characters, such as symbols like @ and ©, see Insert Symbols and Special Characters. Technically, these are not inline elements, but they are similar as you can include them inside a block element such as a para.

Note

DocBook 5.1 has many other inline elements you can use in Paligo.

Emphasis

You can add emphasis (italic, bold or underline) to text in various elements, including para,code and parameter. Italicization is used for gentle emphasis and bold is used for heavier emphasis. Underline is a line drawn under the text, often used to create a blank to be filled in by hand or to create a horizontal line.

It is possible to use italic, bold and underline on the content at the same time. However, if using the emphasis attribute, the role value replace the default italicization. The solution is to use the emphasis attribute in combination with the toolbar buttons or keyboard shortcuts.

In Paligo, you can add emphasis in three different ways by using:

The buttons in the Editor Toolbar
Keyboard Shortcuts
The emphasis attribute

Add Emphasis

You can use Keyboard Shortcuts or the buttons in the the Editor Toolbar to add emphasis (such as italic bold and underline) to the content.

Highlight the text that you want to be bold, italic or underline.

1 = Bold, 2 = Italic, 3 = Underline
Select the relevant toolbar buttonOR use keyboard shortcuts:
- Bold: Ctrl + B (Windows) ORCommand ⌘ + B (Mac)
- Italic: Ctrl + I (Windows) ORCommand ⌘ + I (Mac)
- Underline: Ctrl + U (Windows) ORCommand ⌘ + U (Mac)
Select Save.

Add Emphasis Attribute

You can use the Emphasis attribute to make the content bold, italic or underline. When adding the emphasis attribute, the text becomes italicized by default. If adding a role, the value (bold or underline) replace the default italicization.

If you want to use another emphasis when using the emphasis attribute, the solution is to use it in combination with the Toolbar buttons or Keyboard Shortcuts.

Important

You can use emphasis on text that already has an inline element, such as code. But it is important that the emphasis element is outside the inline element, for example:

 <para><emphasis><code>code snippet content goes here</code></emphasis></para>

Highlight the text that you want to be bold, italic or underline.
Press Alt + Enter ⏎ (Windows) or Command ⌘ + Enter ⏎ (Mac) to display the Element Context Menu.
Enter emphasis and select it.

By default the text becomes italicized.
To make it bold or underlined, select the emphasis element or highlight the text that uses it.
Add the role attribute and set its value to bold or underline in the element attributes section.

The italicization will be replaced with the chosen value.
Select Save.

Remove Emphasis

There are two ways to remove content formatting such as italic, bold or underline, either use the button in the Editor Toolbar or use Keyboard Shortcuts.

Highlight the text that you want to remove the formatting from.
Select Remove format in the Toolbar.

OR use the keyboard shortcut:
- Alt + Shift ⇧ + F (Windows)
- Option ⌥ + Shift ⇧ + F (Mac)
Select Save.

Insert Symbols and Special Characters

To insert symbols and special characters in your topics, you can use the toolbar:

If the character you need is not available in that map, you can also insert any character available using the standard method for your operating system, as described e.g here: How to Quickly Type Special Characters on Any Computer, Smartphone, or Tablet.

If the special characters you need are actually part of an equation, you should use an equation or inlineequation element instead, and use the built-in Math Editor.

Articles in this section

Note

Attributes

Style with Attributes

Tip

Add Attributes

Note

Note

Tip

Add Multiple Values to an Attribute

Note

Remove Attributes

Note

Supported Attributes

Caution

Tip

Role Attribute Values

Tip

Author Remarks

Add Author Remarks

Note

Note

Remove Author Remarks

Add Block Elements

Note

Add Inline Elements

Note

Add a Sequence of UI Options

Note

Note

Inline Elements and Symbols

Note

Emphasis

Add Emphasis

Add Emphasis Attribute

Important

Remove Emphasis

Insert Symbols and Special Characters

Related articles