authoring-oak-foundation-and-oxygen by Writing Samples

Oracle Information Development Authoring with OAK Foundation and Oxygen

General Availability, Build 2.1.0 F60978-17 August 2025

Oracle Information Development Authoring with OAK Foundation and Oxygen, General Availability, Build 2.1.0 F60978-17 Copyright © 2023, 2025, Oracle and/or its affiliates. Primary Authors: Colleen Tse, Dee Beck, Olivia Kelly

Contents 1

Learning the OAK Foundation and Oxygen basics What is OAK Foundation?

Repository features

Key product features

Content development workflow

The OAK Foundation authoring environment

What are the OAK Foundation components?

Publication creation

Publication editing

Publication release

Publication preparation

What is a root map?

What root maps do

Why setting the map context is important

Why having the root map open is important

What is a publication?

What publications do

What happens when you open a publication

Why and how often to open publications

What is the publication baseline?

How versions are managed in the publication baseline

How and when the publication baseline is updated

What the Baseline submap does

How the root map, publication, and baseline work together

Why root maps and publications depend on one another

What's the difference between a root map and a publication baseline

What is local storage?

How content references enable the reuse of parts of a topic

How content references work and when to use them

How keys work in content references

How variables enable the reuse of varying phrases

How variables work and when to use them

How keys work in variables

July 31, 2025 Page i of ix

How keys work in DITA 1.2

How conditions enable the reuse of content variations

Which conditional expressions can be defined and how they are evaluated

How the DITAVAL file controls which conditions to include

What the Conditions Subject Scheme map does

How to reuse topics

How to manage content using workflow statuses and versions

What are the workflow statuses and how they work

What is the difference between a version and branch and how they work

When to branch

What is a revision and how revisions work

Strategies for organizing content in folders

Strategies for organizing content in root maps

Strategies for chunking topics

Which level to chunk at

How to code chunks

Strategies for structuring navigation

Why use a flat navigation structure

Ways to flatten the navigation structure

When to use automatically generated links

How the Content Page navigation works

Where chunked topics appear

What appears in the On This Page navigation

Installing and working with OAK Foundation and Oxygen 27 Upgrade to Oxygen 27.1, then upgrade to the latest OAK Foundation version

Install Oxygen 27.1 and OAK Foundation 1.23 or later for the first-time

Upgrade to the latest version of OAK Foundation

Remove OAK Foundation

How to work in Oxygen

OAK Foundation menu

DITA Perspective and recommended views

Editor

Custom elements in the content completion window

Results view

How to work in DITA Maps Manager DITA Maps Manager How to work in the OAK Foundation Workspace

15 15 17

OAK Foundation Workspace

Folder and file management

Predefined and custom search criteria

July 31, 2025 Page ii of ix

When to overwrite or preserve local changes How to work in Manage Baseline

17 17

Manage Baseline

Where to complete tasks

Authoring in OAK Foundation Browse the repository and organize content

Open the OAK Foundation Workspace

Create folders

Create a publication and add content to it

Create a root map

Create a publication

Check out the root map for a new publication

Create and check out content

Create submaps

Create topics

Insert content in maps

Insert chapters in a root map

Insert topics directly in a root map

Insert submaps in a root map

Insert topics in a submap

Check in content

Check in content open in DITA Maps Manager

Check in content open in Oxygen

Edit content for an existing publication

Open a publication and check out its root map

Check out content

Check out submaps

Check out content from Manage Baseline (baseline version)

Edit content

Check in content

Check in content open in DITA Maps Manager

Check in content open in Oxygen

Check in content from Manage Baseline (baseline version)

Release a publication

Validate the root map

Review the publication baseline

Synchronize the publication baseline manually

Set all content in the baseline to Complete

Set the publication to Complete

Prepare a publication for a new release

July 31, 2025 Page iii of ix

Request a part number

Create a version of a root map

Create a version of a publication

Change the root map associated with a publication

Inserting traditional book pieces Create and insert a custom legal notice

Create a custom legal notice topic

Insert a custom legal notice

Create and insert a preface

Create a preface topic

Add the Common Topics conref library topic as a resource

Insert a preface

Create and insert a document summary (book abstract) Create a book abstract topic

Insert a book abstract

Group chapters into parts

Create part topics

Insert parts

Create and insert appendices

Create submaps

Create topics

Insert appendices

Add a glossary

Create the Glossary orientation topic

Create a Glossary submap

Insert a glossary

Create and insert terms in the glossary

Create glossary terms and their definitions

Insert glossary terms in a glossary

Insert an inline link to a glossary term (xref)

Build an index

Insert index entries

Insert see or see also index entries

Working with content in publications Create content

Create a root map

Create a publication

Create submaps

July 31, 2025 Page iv of ix

Create topics Create a new publication from an existing one

Check out content

Open a publication and check out its root map

Check out submaps

Check out content from Manage Baseline (baseline version)

Check out content from the Workspace (latest version)

Enter book metadata for multipage and letter-style publications

Specify document authors for multipage and letter-style publications

Insert content in maps

Insert chapters in a root map

Insert topics directly in a root map

Insert submaps in a root map

Insert topics in a submap

Check in content

Check in content open in DITA Maps Manager

Check in content open in Oxygen

Check in content from Manage Baseline (baseline version)

Check in content from the Workspace (latest version)

Check in content from Manage Versions (previous version)

Undo changes to checked out content

Combine (chunk) topic sets in HTML output

Set static file names for topics

Copy content objects

Move content

Move a folder

Move a content object

Delete content in maps

Spell-check files globally

Open a publication and its root map

Check the spelling of all topics in a map

Check in content from Oxygen

Add unknown words to the spell-checker

Find or replace text globally

Open a publication and its root map

Find and replace text across all topics in a map

Check in content from Oxygen

Developing topic content Code examples Insert code examples

1 1

July 31, 2025 Page v of ix

Insert code examples with a title

Set the programming language of code examples

Show a Run in Live SQL button in SQL code examples

Hide the Copy button in code examples

Align code examples to the page margin in PDF output

Comments

Insert external comments in draft output (draft-comments)

Insert internal comments (XML comments)

Footnotes

Insert footnotes

Create multiple links to the same footnote text

Images

Add and insert screen shots, diagrams, or flowcharts

Add images to OAK Foundation

Create image descriptions

Insert an image and image description

Add and insert inline images

Add inline images to OAK Foundation

Insert inline images and alternative text

Update images

Scale large images to fit the page in PDF output

Inline links

Insert to another topic in the same publication (xref)

Insert to a topic in a different publication (olink)

Insert to a topic that also works in the PDF output (lookup URL)

Insert to an external web page (external link)

Inline text formatting

Format inline text

Format numerals with periods or commas

Lists

Insert numbered lists (ol)

Insert bulleted lists (ul)

Insert indented lists (sl)

Insert lists of items and descriptions (dl)

Notes

Insert notes, tips, cautions, and warnings Related topics Insert in a map (reltable) Insert links in a relationship table Insert in a topic (related-links) Tabbed interfaces Insert tabbed interfaces in task steps

20 21 21 22 24 26 26

July 31, 2025 Page vi of ix

Insert tabbed interfaces in concepts or reference topics Tables

Insert tables (table)

Insert tabular content (simpletable)

Insert tables of options and descriptions in tasks (choicetable)

Add columns or rows to tables

Change the width of columns in tables (table)

Change the width of columns in tables (simpletable, choicetable)

Align tables to the page margin in PDF output

Add a heading row to tables

34 35

Insert numbered steps in a task (steps)

Insert task steps as a bulleted list (steps-unordered)

Insert task steps as a paragraph (steps-informal)

Reusing content Insert content references for content reuse

Create conref library topics

Add a conref library topic as a resource

Insert a content reference

Insert variables for content reuse

Create a set of variable library topics

Add a variable library topic as a resource

Insert a variable

Control which conditions to include in a publication

Define conditions for publications

Apply conditional settings to a publication

Remove conditional settings from a publication

Conditionalize content

Conditionalize an entire topic or submap

Conditionalize content within a topic

Conditionalize a row in a table

Control how conditions look when viewed in the Editor

Apply styles to conditional text when viewed in the Editor

Show conditional text styles or attributes in the Editor

Reuse topics in a publication

Insert tables with titles (table)

Task steps

Versioning content & managing the publication baseline Change the workflow status of content

July 31, 2025 Page vii of ix

Change the workflow status of maps, topics, images, and other content

Change the workflow status of a publication

Create a version or branch of content

Create a version of a publication

Create a version of a root map

Create a version of a submap, topic, image, or other content

Create a version of a DITAVAL file

Change the root map associated with a publication

Change the version of content associated with a publication

Change the DITAVAL file associated with a publication

Synchronize the publication baseline manually

Automatically complete the publication baseline

Compare different versions or revisions of a content object

View and restore revisions

Searching for content in OAK Foundation Find the DITAVAL file associated with a publication

Find the root map associated with a publication

Find where objects are located in OAK Foundation

Find the repository location of maps open in DITA Maps Manager

Find the repository location of content open in Oxygen

Find the repository location of content in the publication baseline

Find which publications use specific maps, topics, and images

Search for content by metadata

Search for objects checked out by you

View all available versions of a content object

View all content in a publication

View the audit history of content

Default preferences in Oxygen

Frequently asked questions

General OAK Foundation FAQs

B-1

Migration FAQs

B-2

Authoring and object management FAQs

B-4

Schematron rules in Oxygen

July 31, 2025 Page viii of ix

Troubleshooting Cannot download Oxygen

D-1

Cannot find or run the Setup program

D-1

Could not connect to a license server

D-1

Request access to OAK Foundation

D-1

Validate and correct DITA files

D-2

Validate the root map

D-2

Validate a topic or submap

D-2

Correct duplicate ID errors

D-3

Correct XML validation errors

D-3

Correct missing key definition warnings

D-3

Correct Schematron warnings

D-4

Tools & Software not appearing in Uno

D-4

Troubleshoot build issues using the DITA-OT log

D-4

Locating errors in the DOT log

D-4

Tracking down missing cross-references

D-5

View the OAK Foundation version

D-5

Get help

D-6

XML refactoring Separate sections into standalone topics

E-1

Replace an element with another

E-3

July 31, 2025 Page ix of ix

1 Learning the OAK Foundation and Oxygen basics Oracle Authoring Kit (OAK) Foundation is a content repository integrated with Oxygen, which together provide a DITA-based authoring solution for User Assistance Developers. Before you begin If you would like to learn more about DITA, review the following sections on Writing Best Practices: •

Editing and writing standards – Provide basic information on writing for DITA, and topicoriented and minimalist writing

•

Writing resources – External resources with more in-depth information on DITA and writing best practices.

The basics of authoring with OAK Foundation includes these concepts: •

How the authoring environment works.

•

What is a root map, publication, and publication baseline and what do they do.

•

What's local storage.

•

How to reuse content using content references, variables, or conditions.

•

How to manage your content using workflow statuses and versioning.

What is OAK Foundation? Oracle Authoring Kit (OAK) Foundation is an enterprise-grade content management system developed in-house using Oracle technologies such as Oracle XML database. It provides UA teams who publish content to Oracle Help Center (docs.oracle.com) a standard and central system for storing and managing documentation source files.

Repository features OAK Foundation has many repository features that sets itself apart from other content management systems. •

Architecture: Built using Oracle technologies with REST web services on top of Oracle XML database.

•

XML Aware: XML-aware database for searching and managing DITA XML topics, maps, and publications.

•

Content: Designed to store DITA XML source files as well as images, zip, and other needed file types.

•

Unified: Repository features accessible from Oxygen XML Author and integrated with InfoDev tools for simplified content publishing.

July 31, 2025 Page 1 of 49

Chapter 1

What is OAK Foundation? •

Flexible: As business needs change, features can be enhanced or added without extensive rework or vendor limitations.

Key product features OAK Foundation provides many of the same product features as leading content management systems, in addition to ones designed specifically to support the authoring and publishing of Oracle content. New features and enhancements are constantly being added to ensure that stakeholder needs are addressed.

User Experience and Performance • •

Responsive and stable Use of Redwood components and design

Workspace • •

• •

Content Features •

•

Access repository actions via OAK Foundation menus built into Oxygen Complete bulk operations on map hierarchies, including global search and replace

• •

•

Version and Revision Management

Publication and Baseline Management

Built for DITA XML • Check in and check out content via a single or • bulk operation Assign workflow status to repository objects Search objects by metadata

Object versioning and branching View and restore previous revisions of objects

Publishing and Review

Reuse Management

Administration

Apply conditions to DITA • XML content • Preview filtered content while authoring • Validate content against condition sets in Oxygen Support for DITA 1.2 keys

SSO and OIM support Full API, including Web Service APIs Console and log files for troubleshooting

Build from Jarvis and DocBuilder Workflow status automatically moved from Complete to Released on promote to Production in Jarvis Send publications to Oracle Review for feedback and collaboration

• • • •

•

View and specify object versions in publications via a baseline UI Autocomplete baseline capabilities

Content development workflow Use Oxygen to create and author content, OAK Foundation to version and manage content, and Jarvis to publish content to Oracle Help Center. OAK Foundation works with both Oxygen and Jarvis.

July 31, 2025 Page 2 of 49

Chapter 1

The OAK Foundation authoring environment

The OAK Foundation authoring environment The OAK Foundation authoring environment includes Oxygen, the OAK Foundation Workspace, and the OAK Foundation database.

What are the OAK Foundation components? OAK Foundation components includes Oxygen where you create and edit content, the OAK Foundation Workspace where you access and act on content, and the OAK Foundation database where content is stored and retrieved. Local storage is a temporary location on your computer that contains the content you have opened or checked out. The OAK Foundation custom functionality is installed via Oxygen add-ons. The Oxygen integration includes custom buttons and menu items, authoring templates, CSS style sheets, XML schemas, and transformation scenarios. The Workspace and database are installed via these add-ons.

Publication creation Publications are created using the root map that you want to associate with the publication. Before you create a publication, the root map you want to use must already exist and be checked in. When you create a publication, the root map you select is associated with the publication. System files associated with the publication are copied locally and the root map is opened. The root map is opened in DITA Maps Manager by default. Set the Context to <Current map> (the root map). Check out the root map and you're ready to create and check out content, then insert it in the root map. When you're done, check in the root map and other content.

July 31, 2025 Page 3 of 49

Chapter 1

The OAK Foundation authoring environment

Publication editing When you want to edit content for a publication, always open the publication first. Before you edit content for a publication, always open the publication, the associated root map is automatically opened. The root map is opened in DITA Maps Manager by default. Set the Context to <Current map> (the root map). All publication content is copied locally. Any content that is already checked out isn't overwritten. Check out the root map as needed. Now you're ready to edit the root map, submaps, or topics for the publication. When you're done, check in all content.

Publication release When your content has been finalized and you're ready to publish content to Production, release the publication. Validate the root map to find any content issues that might block publishing. Review the publication baseline to make sure that it's referencing the correct versions of content and that there are no references to inactive content. Synchronize the baseline to remove any content that is no longer being referenced. Set all content to the Complete workflow status. You can set all content being referenced in the publication to complete in Manage Baseline, and the publication itself in the Workspace.

July 31, 2025 Page 4 of 49

Chapter 1

What is a root map?

Publication preparation After releasing a publication to Production, prepare it for a new release. Request a new part number revision, create a version of the publication and the root map, then edit the properties of the publication with the new root map version.

What is a root map? A root map is the top-level map for a publication that defines the hierarchical structure of the submaps and topics within it. A root map references the additional resources it needs to resolve references. The Resources and System topic groups at the end of a root map contain different types of resources:

July 31, 2025 Page 5 of 49

Chapter 1

What is a root map? •

The Resources group manages resource files. Typically, the Resources group includes conref and variable library topics, but other types of resource files can be referenced here.

•

The System group manages system-generated files including the Baseline submap (which is the local copy of the publication baseline) and Conditions Subject Scheme map (which defines the condition names and values).

Caution Never edit, delete, or move the System group or any items within it.

What root maps do Root maps form the basis of a publication. You manage the content of a publication from the root map. A root map can be a map with a root element of <bookmap> or <map>, depending on the publication type. Map templates for different types of publications are set up using the appropriate map type. For example, multipage and letter-style guides use bookmaps and solutions and article publications use maps. Root maps are managed in Oxygen using DITA Maps Manager.

July 31, 2025 Page 6 of 49

Chapter 1

What is a root map?

Why setting the map context is important Setting the map context to the root map establishes the key space, which helps resolve references and avoid validation errors. Always open maps in DITA Maps Manager, so that references in the maps resolve. When working with a root map, make sure that Context is set to <Current map> (the root map) to avoid validation errors. In this example, Context is set to <Current map> (the root map), so all references in the root map resolve. (The root map is Authoring with OAK Foundation v10.)

When working in a submap, make sure that Context is set to the associated root map. In the submap below, Context is set to <Current map> (the submap), so we see validation errors (in red) in the submap.

July 31, 2025 Page 7 of 49

Chapter 1

What is a root map?

When Context is changed to the root map (Authoring with OAK Foundation v10), the topic references in the submap resolve.

Why having the root map open is important When you are working in topics with references, having the root map open in DITA Maps Manager helps resolve references and avoid validation errors. Why to open Always open publication when editing content, so that the associated root map is opened in DITA Maps Manager by default. Having the root map open helps make sure that references in topics resolve. References include related links, images, cross-references to other topics in the publication, content references and variables. For the image reference in the topic below, a "Key not found" validation error (in red) is shown because the root map isn't open in DITA Maps Manager.

July 31, 2025 Page 8 of 49

Chapter 1

What is a root map?

Now that the root map (Authoring with OAK Foundation) is open in DITA Maps Manager and Context is set to the named root map, the image reference resolves and the image appears inline.

Exceptions to the rule While we recommend that you always open the publication and root map as a best practice when editing content, it isn't needed when: •

You're writing content and don't need to insert any references into the content.

•

Content you're updating has existing references in it and you're okay seeing validation errors appear inline.

July 31, 2025 Page 9 of 49

Chapter 1

What is a publication? •

You're creating new content and adding it to OAK Foundation.

What is a publication? Publications act as a blueprint for a single, unique document. A publications is a configuration file that stores the blueprint information. Publication GUIDs begin with a "P" to distinguish them from other content objects.

What publications do Publications allow you to publish different documents from the same content by defining a different blueprint for each document. Publications define the following: •

Where to publish the document.

•

Which conditional text to include in the document.

•

Which objects and which versions of these objects to include in the document.

•

Which root map the publication is based on.

What happens when you open a publication When you open a publication, all content associated with it is copied locally and the associated root map is opened. Content that is already in local storage or is checked out is not copied locally, allowing the publication to open more quickly and avoiding overwriting work in progress. The version and revision of each object in local storage is compared to the baseline determine which objects to copy. Files associated with the publication including the root map, Baseline submap, Condition subject scheme, and DITAVAL condition file are exceptions and are copied to local storage every time you open a publication.

July 31, 2025 Page 10 of 49

Chapter 1

What is the publication baseline?

Why and how often to open publications You need to open publications, so references within it resolve. How often you need to open depends on a number of factors. While always opening the publication is a best practice, not all situations call for it. Why to open Resolving references is the task most impacted by the OAK Foundation authoring environment. Because OAK Foundation and Oxygen currently lack a direct connection, resolving references to other files in the OAK Foundation Database while authoring content is only possible when you have a local copy of those files. To support this, opening an OAK Foundation publication makes local copies of all content used in the publication. How often to open How often you'll need to open a publication depends largely on these factors: •

How many people are working on the publication.

•

Whether there's any shared content in the publication.

•

How long it's been since you have worked on the publication.

If you're the only person working on a publication, you only need to open the publication when you first start updating it (as long as the local files aren't deleted from local storage). If you're one of many people contributing to the same publication, you need to open the publication frequently to keep it in sync with changes being made by others. •

As a best practice, you need to open the publication at the beginning of every work session. For example, if each person works in a separate chapter, making changes to one chapter wouldn't effect another chapter. In this case, opening the publication at the beginning of the day allows you to see the recent changes made by others and keeps your view of the publication is sync with the work others have done.

•

Depending on how the changes others are making effect your work, you might need to open the publication more often. For example, if multiple people are working in the same chapter, you need to open the publication more often, so that you can see each others changes.

If you're working on a publication that reuses content with other publications, you need to open the publication whenever the shared content is changed or versioned, so that the updates are reflected in your publication. For example, if a content reference library that you reference has been updated since you opened the publication, those changes won't be reflected in your local storage until you open the publication again. If you haven't worked on a publication for awhile, you need to open the publication again, so that you are working with the latest publication, including updated content, new topics, updated baseline, etc.

What is the publication baseline? The baseline identifies all content objects for a publication by their GUID and version.

July 31, 2025 Page 11 of 49

Chapter 1

What is the publication baseline?

How versions are managed in the publication baseline Versions can be automatically or manually selected in the publication baseline depending on where you create versions. You can always manually select a previous version or branch when needed. Automatic selection When you create versions from Manage Baseline, the publication baseline is automatically updated with the latest version or branch. For example, if you create version 3 of a topic from version 1, version 3 is automatically selected because it's the latest version.

If you create branch 1.2 from branch 1.1, it's selected because it's the latest version on that branch.

Manual selection When you create versions from the OAK Foundation Workspace or other dialogs, you must update the baseline with new versions or branches after you create them. For example, if you create version 2 in the Workspace, the publication baseline is not affected. You must select the new version in the baseline, then save it to include the version in the publication baseline.

July 31, 2025 Page 12 of 49

Chapter 1

What is the publication baseline?

Autocomplete selections You can apply the latest version or the latest released version to all each object individually or to all objects in the publication baseline using autocomplete. •

Latest available versions – The highest available version or branch of all objects. For example, topic version 2, submap version 1.1, and image version 1 are selected because they are the latest version of these objects.

•

Latest released versions – The highest available version or branch of all objects that are in a Released status. For example, topic version 1.1, submap version 1.1, and image version 1 are selected because they are the latest released versions.

July 31, 2025 Page 13 of 49

Chapter 1

What is the publication baseline?

How and when the publication baseline is updated Depending on what you are doing and how, the publication baseline is updated automatically or must be manually synchronized. All content objects must be checked in before you can manually synchronize the publication baseline. If you...

The publication baseline...

You need to..

Insert object references using Oxygen Insert dialogs

Is automatically updated with the latest version

Have the root map open in DITA Maps Manager

Insert or change object references in Text view

Must be manually synchronized

Sync the baseline, then open the publication again.

Remove topics or images

Must be manually synchronized

Sync the baseline, then open the publication again.

Create versions from Manage Baseline Is automatically updated with the newly created version

Click Save to apply the new version to the baseline

Create versions from the Workspace or Must be manually updated with the newly created version other dialogs

Select the newly created version in the baseline, then click Save to apply the new version to the baseline.

Undo a checkout after inserting references to objects

Sync the baseline, then open the publication again.

Must be manually synchronized

What the Baseline submap does The Baseline submap is a system-generated file that associates GUIDs from the OAK Foundation Database with the XML files in local storage (called indirect key-based addressing). A Baseline submap is automatically created when you create a publication. The Baseline submap is automatically updated as references are added to the root map. The Baseline submap is updated when you save or refresh (reload) the root map. The Baseline submap is a key definition map that enables references to resolve by linking all content IDs referenced in the root map with the file names in local storage.

July 31, 2025 Page 14 of 49

Chapter 1

What is the publication baseline?

The connections (or key definitions) made by the Baseline submap do the following: •

Enable references to resolve using GUIDs in Oxygen.

•

Allow GUIDs assigned in SDL to be retained and resolved within OAK Foundation.

The image shows a software interface window titled "DITA Maps Manager." The root map titled "Authoring with OAK Foundation and Oxygen" is open within this window. Under the backmatter element in the root map, there are two topic groups titled "System" and "Resources." Under the System group, the Baseline submap titled "Baseline - "Authoring with OAK Foundation and Oxygen" appears. Under the Baseline submap, all submaps and topics referenced in the root map, all images referenced in topics, and the Conditions Subject Scheme map are listed. Under the Resources group, all content reuse libraries are listed. The Baseline submap is automatically added to every root map under <backmatter> in a System group. The Baseline submap lists every submap and topic referenced in the root map, every image referenced in topics, and the Conditions Subject Scheme map. Under the Resources group, all content reuse libraries are listed.

July 31, 2025 Page 15 of 49

Chapter 1

How the root map, publication, and baseline work together

Caution Never edit, delete, or move the System group or the Baseline submap.

How the root map, publication, and baseline work together Root maps and publications depend on one another. Root maps and baselines are similar but have important differences.

Why root maps and publications depend on one another Root maps define the topic hierarchy (which topics to include and in which order) in a publication. Publications define the baseline (which versions of these topics) to include in the root map.

July 31, 2025 Page 16 of 49

Chapter 1

How the root map, publication, and baseline work together Publications always have an associated root map. A root map can be associated with multiple publications.

The same root map can be associated with multiple pubs. Update the root map associated with a publication in the publication properties (not in the baseline).

What's the difference between a root map and a publication baseline Root maps define the topic hierarchy of a publication. The publication baseline defines which version of topics and other referenced content to include in the publication. Root maps define the topic hierarchy or which topics to include and in which order they appear in a publication. Here are the topics included in the Lesson 1 root map. You can see topics that appear at the top level (Pre-Training Evaluation, Lesson 1: Learning the OAK Foundation and Oxygen Basics, The OAK Foundation authoring environment, The OAK Foundation authoring tools, Root maps, and Publications), topics nested under those topics (for example, What is a publication? is nested under Publications), and so on. Pre-Training Evaluation Lesson 1: Learning the OAK Foundation and Oxygen Basics 1 The OAK Foundation authoring environment What are the OAK Foundation components? Where to complete tasks 2 The OAK Foundation authoring tools How to work in Oxygen OAK Foundation menu

July 31, 2025 Page 17 of 49

Chapter 1

How the root map, publication, and baseline work together DITA Perspective and recommended views Editor Custom elements in the content completion window Results view How to work in DITA Maps Manager DITA Maps Manager How to work in the OAK Foundation Workspace OAK Foundation Workspace Folder and file management Predefined and custom search criteria How to work in Manage Baseline Manage Baseline 3 Root maps What is a root map? What root maps do Why setting the map context is important? Why having the root map open is important? 4 Publications What is a publication? What publications do What happens when you open a publication? The publication baseline includes not only all topics referenced in the root map, but the root map itself, any submaps referenced in the root map, and all images and libraries referenced in the topics. Here's the baseline for the Lesson 1 publication and root map. Where the root map simply references the What are the OAK Foundation components? topic. The baseline references version 4 of the topic. Because this topic references an image (oakf-componentArchitecture) and image description (oakf-componentArchitecture) these objects are also in the baseline and a specific version of each is selected. While you can reference the same content object multiple times in a publication, only one version of any object can be included in the baseline. For example, while many topics reference the Doc Processes Conrefs library topic, only one version can be in the baseline. basics-root-map, Version 2 Custom elements in the content completion window, Version 3 DITA Maps Manager, Version 3 DITA Perspective and recommended views, Version a Doc Processes Conrefs, Version 7 Editor, Version 3 Folder and file management, Version 1 How to work in DITA Maps Manager, Version 9 How to work in Manage Baseline, Version 1 How to work in Oxygen, Version 6 How to work in the OAK Foundation Workspace, Version 7 icon_filter, Version 1 icon_newfile, Version 1 icon_open_editor, Version 1 icon_refresh, Version 1 icon_save, Version 1 icon-add-folder, Version 1 icon-dmm-settings, Version 1 icons_prode_mote, Version 1 Learning the OAK Foundation basics, Version 8 Lesson 1: Learning the OAK Foundation basics, Version 10 lesson1Map, Version 8 Authoring with OAK Foundation and Oxygen F60978-17 Copyright © 2023, 2025, Oracle and/or its affiliates.

July 31, 2025 Page 18 of 49

Chapter 1

What is local storage? Manage Baseline, Version 1 OAK Foundation menu, Version 3 OAK Foundation Workspace, Version 1 OAKF Logo, Version 2 oakf-componentArchitecture, Version 3 (image description) oakf-componentArchitecture, Version 8 (image) oakf-customElementContextMenu, Version 7 oakf-DITAPerspective, Version 1 oakf-DMM, Version 1 oakf-DMM-editorPrompt, Version 1 oakf-listOpenObjects, Version 1 oakf-manage-baseline, Version 2 oakf-OAKfoundationMenu, Version 2 oakf-oxygenReloadIcon, Version 1 oakf-PublicationStructure, Version 3 oakf-PublicationStructure, Version 3 oakf-RootMapComponents, Version 3 oakf-rootMapOpen-imageResolved, Version 1 oakf-scrollArrows, Version 1 oxygenEditor, Version 2 oxygenlcon, Version 1 oxygen-results, Version 2 Predefined and custom search criteria, Version 4 Pre-Training evaluation, Version 1 Results view, Version 2 rootmapguid, Version 1 rootMap-TopicMissingContext, Version 2 rootMap-TopicWithContext, Version 2 submap-missingContext, Version 2 Submap-withContext2, Version 2 tagsDisplayModelcon, Version 1 The OAK Foundation authoring environment, Version 5 Unit 2 - The OAK Foundation authoring tools, Version 1 Unit 3 - Root maps, Version 2 Unit 4 – Publications, Version 2 What are the OAK Foundation components?, Version 4 What happens when you open a publication, Version 1 What is a publication?, Version 4 What is a root map?, Version 4 What publications do, Version 4 What root maps do, Version 5 Where to complete tasks, Version 7 Why having the root map open is important, Version 4 Why setting the map context is important, Version 3

What is local storage? Local storage is a temporary location on your computer that stores OAK Foundation content, so that Oxygen can access it. When you complete these actions from the OAK Foundation Workspace, content is copied from the OAK Foundation Database to the local storage directory on your computer: •

Opening a publication.

•

Checking out content.

July 31, 2025 Page 19 of 49

Chapter 1

How content references enable the reuse of parts of a topic •

Opening content.

How content references enable the reuse of parts of a topic Use content references for content that can be reused as-is without changes.

How content references work and when to use them Content references allow you to insert the same content (that is, sentences or paragraphs) into multiple topics. If you need swap out a phrase in different publications (for example, Windows versus Linux), use variables. Create conref library topics for similar types of shared content and name the libraries accordingly. For example, names like "Library for Task Steps in Database Products" or "Library for Notes in Getting Started Guides“ describe the contents. Using conref libraries, you can maintain shared content in one place and apply it to multiple topics and across different documents. For example, you might need to use the same steps across multiple tasks, place the same warning in multiple topics within a document, share common feature descriptions across multiple products, or maintain links to all of the books for a product.

How keys work in content references To use keys for content references, you must define the shared content in conref library topics, add the conref libraries to the root map, then insert the content references in topics. Shared content is defined in conref library topics using an element ID. Set an ID on the element that you want to reference. Create conref library topics for similar types of shared content and name the libraries accordingly; for example, "Library for Task Steps in Database Products" or "Library for Notes in Getting Started Guides." Before you can reference the shared content in topics, you must add the conref library under the Resources group in the root map.

July 31, 2025 Page 20 of 49

Chapter 1

How content references enable the reuse of parts of a topic

July 31, 2025 Page 21 of 49

Chapter 1

How variables enable the reuse of varying phrases

How variables enable the reuse of varying phrases Use variables for phrases that change when the surrounding content stays the same.

How variables work and when to use them Use variables to swap out a phrase in different publications (for example, Windows versus Linux). If you want to insert the same content (that is., phrases, sentences, or paragraphs) into multiple topics, use content references. Variables are small pieces of content that vary depending on the publishing context; for example, an operating system variable can be set to "Windows" in one document and "Linux" in another. You can publish the same topic with different variable definitions in multiple documents. The reference to the variable identifier remains constant within the topic and the variable value is set based on which variable definition is available in the root map.

Note Instead of setting conditions on phrases (that is, small group of words, less than a sentence), use variables to include different text in different publications.

How keys work in variables To use keys for variables, you must create a set of variable libraries, add the variable library to the root map, insert the key definition for the library, then insert the variable in a topic. Variables are defined in variable library topics using a library key, element ID, and the variable text itself. Create variable libraries in sets with a separate library for each version of the variable text. For example, create an operating system set with a library for Windows variables and a library for Linux variables. Use the same library key for all libraries in a set (for example, var_os). Similarly, give each instance of the same variable the same ID in each library. For example, assign a "control-panel" ID to the "Control Panel" variable in the Windows library and the "Gnome Control Center" variable in the Linux library. Add the relevant variable library under the Resources group in the root map, then define the key for that library. The library key is added to the end of the library name; for example, "Library for Operating System Variables for Windows {var_os}." Now you can insert the variable using the library key and element ID you defined in the variable library. To use a different variable value, add a different variable library to the root map, define the same library key, and the new value appears in topics.

July 31, 2025 Page 22 of 49

Chapter 1

How variables enable the reuse of varying phrases

July 31, 2025 Page 23 of 49

Chapter 1

How keys work in DITA 1.2

How keys work in DITA 1.2 Since OAK Foundation uses indirect key addressing to insert references, you might find it helpful to watch this overview of how keys work in DITA 1.2 before working with content references (conrefs) and variables. Start at 4:06 - 33:22 Introduction to Keys and Conkeys - DCL Learning Series

How conditions enable the reuse of content variations Conditions allow you to create unique documents from the same source content. By setting conditions on content, you can include or exclude specific topics or submaps from a root map or specific text within topics to create different publications from the same source content.

July 31, 2025 Page 24 of 49

Chapter 1

How conditions enable the reuse of content variations Always apply conditions to entire elements. If you apply a condition to a text fragment, it's automatically wrapped in a <ph> element, but conditionalized fragments cause translation difficulties.

Which conditional expressions can be defined and how they are evaluated OAK Foundation supports simple conditions, multiple conditions, and compound conditions. OAK Foundation uses custom conditional attributes to support a broader range of conditions than those is supported in DITA by default. Expression Type

Definition

Included When

Excluded When

Simple

1 value in 1 condition

Value is included

Value is excluded

Multiple

Multiple values in 1 condition

At least 1 value is included

All values are excluded

Compound

Include more than 1 expression: simple, multiple, or both

All values are included

Any value is excluded

Simple condition example If this conditional text is applied: <li condition-platform="windows">RAM – 2GB</li> <li condition-platform="linux">RAM –256MB</li> And the associated DITAVAL includes one value and excludes the other: <prop action="exclude" att="condition-platform" val="linux"/> <prop action="include" att="condition-platform" val="windows"/> Then, the conditional content for the included value is shown: <li condition-platform="windows">RAM – 2GB</li> And the conditional content for the excluded value is hidden: <li condition-platform="linux">RAM –256MB</li> Multiple conditions example If this conditional text is applied: <li condition-platform="windows linux">Server display card -- 1024x768</li> And the associated DITAVAL includes either value: <prop action="include" att="condition-platform" val="linux"/> <prop action="exclude" att="condition-platform" val="windows"/> Then, the conditional content is included.

July 31, 2025 Page 25 of 49

Chapter 1

How conditions enable the reuse of content variations But if the DITAVAL excludes both values: <prop action="exclude" att="condition-platform" val="linux"/> <prop action="exclude" att="condition-platform" val="windows"/> Then, the conditional content is excluded. Compound conditions example If this conditional text is applied: <li condition-platform="linux" condition-install_type="grid">Runlevel – 3 or 5</li> And the associated DITAVAL includes both values: <prop action="include" att="condition-install_type" val="grid"/> <prop action="include" att="condition-platform" val="linux"/> Then, the conditional content is included. But if the DITAVAL excludes either value: <prop action="exclude" att="condition-install_type" val="grid"/> <prop action="include" att="condition-platform" val="linux"/> Then, the conditional content is excluded.

How the DITAVAL file controls which conditions to include OAK Foundation uses the DITAVAL file to define which conditional text to include in a publication. The Conditions template is a DITAVAL file that lists all conditions and their values. All conditions excluded by default using<prop action="exclude"/>. Make sure to leave this line in your DITAVAL file; otherwise, any condition that isn't listed will be included. The DITAVAL file uses this format to define conditions:<prop action="exclude|include"att="condition<name>" val="<value>"/>; for example, <prop action="exclude" att="condition-platform" val="windows"/>. Although the Conditions template lists all conditions, let's look at the Installation Type and Platform conditions that apply to shared Server Hardware Requirements topic. <val> <prop action="exclude"/>  <prop action="exclude" att="condition-install_type" val="client"/> <prop action="exclude" att="condition-install_type" val="grid"/> <prop action="exclude" att="condition-install_type" val="rac"/> <prop action="exclude" att="condition-install_type" val="si"/>  <prop action="exclude" att="condition-platform" val="aix"/> <prop action="exclude" att="condition-platform" val="hp-ux"/> <prop action="exclude" att="condition-platform" val="linux"/> <prop action="exclude" att="condition-platform" val="macintosh"/>

July 31, 2025 Page 26 of 49

Chapter 1

How conditions enable the reuse of content variations <prop action="exclude" att="condition-platform" val="solaris"/> <prop action="exclude" att="condition-platform" val="unix"/> <prop action="exclude" att="condition-platform" val="windows"/> Leave all conditions in the DITAVAL file even if you aren’t using them. Conditions that are applied, but not in the DITAVAL file are included.

What the Conditions Subject Scheme map does The Conditions Subject Scheme map defines all conditions and their values. Conditions must be defined in this subject scheme map by the DocEng group before they can be applied to content. The Conditions Subject Scheme map not only makes our custom conditions available in Oxygen, but also extends support for multiple conditions. When you create a publication, the subject scheme map is automatically added to the root map.

July 31, 2025 Page 27 of 49

Chapter 1

How to reuse topics

Caution Never edit, delete, or move the System group, Baseline submap, or the Conditions Subject Scheme map.

How to reuse topics The method to reuse topics varies depending on whether you are referencing them in the same publication or a different one. When you want to reuse a topic that you don't own, coordinate the reuse with the content owner. If the topic is reused in...

And the content is...

Then, use this method...

The same publication

Yours

Set the copy-to attribute on the <topicref> using a value of <Descriptor>-<GUID_string>.dita. Here's a code snippet:

<topicref keyref="GUID-981071D2-9575-4105-9FD2E480FC33EBB3" copy-to=reuse-GUID-D665DDDEA0FE-476C-9BBC-9242892F1968.dita" format="dita"> The same publication

Someone else's

Contact the content owner and check for items that might impact its reuse: • Inline links – A link to a topic in another publication might not be valid for your publication. Ask the owner to remove the link, move the link to a relationship table, or apply a condition to hide the link in your publication. • Conditions – The topic might use a condition that your publication doesn't. Add the condition to your publication. • Variables – If you need to use a different variable value, then ask the owner to create another variable library topic with the value you need. Check with your information architect about your team's variable libraries.

A different publication

Yours

Reference the topic as you normally would.

July 31, 2025 Page 28 of 49

Chapter 1

How to manage content using workflow statuses and versions

If the topic is reused in...

And the content is...

Then, use this method...

A different publication

Someone else's

How to manage content using workflow statuses and versions Used together, workflow statuses and content versioning allow you to manage content during development and release and across releases.

What are the workflow statuses and how they work Workflow statuses allow you to track the readiness of content for release. Workflow statuses apply to publications, root maps, submaps, topics, library topics, images, and image descriptions. Other types of files can be stored in the OAK Foundation Database and some are included when publishing, but these non-DITA files don't use workflow statuses. Administrators can override any status. Active workflow states Active workflow states are required. There's one editable, working state (In Progress) and two frozen, final states (Complete and Released). All objects must be set to Complete before you can build publications to final UAT or directly to Stage. After the successful promotion to production, the state of all objects including the publication is changed from Complete to Released.

July 31, 2025 Page 29 of 49

Chapter 1

How to manage content using workflow statuses and versions

Inactive workflow states Inactive workflow states are optional. Content can become inactive for any number of reasons, such as it's become outdated or obsolete, or it was created and never used. Inactive content is still available and can be versioned at any time and used again. If you have a large amount of inactive content, using the inactive states help you avoid accidentally referencing outdated content and filter out content you don't need. You can move In Progress, Complete, or Released content objects to Inactive or InactiveReleased states, respectively. If you need to use inactive content in the future, its state lets you know whether content was release-ready. You can move between In Progress or Complete to Inactive without versioning. You must version or branch objects in Inactive-Released to edit the content. You cannot publish content with inactive workflow states.

July 31, 2025 Page 30 of 49

Chapter 1

How to manage content using workflow statuses and versions

What is the difference between a version and branch and how they work Versions and branches not only allow you to track changes made to content over time, but they also enable you to manage the current and previous states of content independently. You can version publications, root maps, submaps, topics, libraries, images, and image descriptions. When you create a version or branch, you are capturing the state of the content at a specific point in time; for example, for a previous project milestone or release or for the version of content sent to reviewers. To preserve the state of the content, you must freeze the object by changing its workflow status to Complete. Remember, you can always create a new version or branch of content after you set it to Complete. Using versions and status you can restore previous versions of documents whether they were released internally or externally; for example, to restore content to a previously released state or to view what content was included in a review. You can create a new version from another version or branch. You can create a new branch from another branch or version. The content in the new version or branch reflects the content in the version or branch you started from. Numbers are incremented from the highest existing version or branch number. •

Version numbers are single-digit numbers: 1, 2, 3... 10... 100, etc.

•

Branches use one-place, decimal numbers: 1.1, 1.2, 1.3... 1.10... 1.100, etc.

For example, if the latest version is 3 and you create a new version from version 1, then version 4 is created and it reflects the contents of version 1. If the latest branch is 1.3 and you create a new branch from version 1, then branch 1.4 is created and it reflects the contents of version 1.

Similarly, if the latest version is 3 and you create a new version from version 2, then version 4 is created and it reflects the contents of version 2. If you create a new branch from version 2 which has no branches, then branch 2.1 is created and it reflects the contents of version 2.

July 31, 2025 Page 31 of 49

Chapter 1

How to manage content using workflow statuses and versions

For example, if the latest branch is 1.3 and you create a new version from branch 1.2, then version 4 is created and it reflects the contents of branch 1.2. If the latest branch is 1.3 and you create a new branch from branch 1.2, then branch 1.4 is created and it reflects the contents of branch 1.2.

Similarly, if the latest version is 3 and you create a new version from branch 1.3, then version 4 is created and it reflects the contents of branch 1.3. If the latest branch is 1.3 and you create a new branch from it, then branch 1.4 is created and it reflects the contents of branch 1.3.

July 31, 2025 Page 32 of 49

Chapter 1

How to manage content using workflow statuses and versions

When to branch The content from the version or branch that you are versioning is copied to the new version or branch. When choosing whether to version or to branch content, consider questions like the following: •

Which version or branch represents the state of content you need to update?

•

Which release does the updated content apply to?

For example, to update release 1.0 after release 2.0 has already been delivered, create a branch from version 1 to create branch 1.1. Branch 1.1 is a copy of version 1, so your update is based on the content delivered for release 1.0. To update release 4.0 following release 3.0, create a version from version 3 to create version 4. Version 4 is a copy of version 3, so your update is based on the content delivered for release 3.0. In Chronological Order

In Version Order

For this release

From this version

Created this version

For this release

From this version

Created this version

Release 1.0

––

Release 1.0

––

Release 2.0

Release 1.1

1.2

Release 1.1

1.1

Release 2.0

Release 3.0

Release 2.1

2.1

Release 2.1

2.1

Release 2.2

2.1

2.2

Release 4.0

Release 3.0

Release 2.2

2.1

2.2

Release 4.0

July 31, 2025 Page 33 of 49

Chapter 1

Strategies for organizing content in folders

Note For simplicity, the release and versions numbers used in the table above are aligned. Version and branch numbers do not need to match release numbers or vice versa.

What is a revision and how revisions work A revision is created each time a version or branch of content is checked in, its properties are changed, or the publication baseline is changed. Revisions allow you to restore content from a different point in time within a specific version or branch. For example, if you want to revert the work you did on a particular version of content today, you can restore a previous revision within that version from another day. Revisions allow you to view history of properties changes over time. Publication revisions allow you to restore the previous states of the baseline. When you restore a revision, a new revision is created, and the source revision is preserved. Revisions track changes and restoring is a change, so it's also tracked.

Strategies for organizing content in folders You can organize content in folders in the Workspace in any way you like. By object type You can organize content by object type keeping each type in a separate folder, so that all publications are in a Publications folder, all root maps and submaps in a Maps folder, etc., but there is no technical requirement to do this.

July 31, 2025 Page 34 of 49

Chapter 1

Strategies for organizing content in folders

Group objects logically You can group objects that logically belong together in the same folder. For example, you can keep the publication and the associated root map and DITAVAL file in a Publication Resources folder. You can store content with the same object type, but different purposes in different folders. For example, you can keep topics like tasks and concepts in a Topics folder and image description topics in an Image Descriptions folder.

Using subfolders You can further organize content in subfolders for logical groupings like chapters.

July 31, 2025 Page 35 of 49

Chapter 1

Strategies for organizing content in folders

Using the title property If you prefer a flatter folder structure, you can add a descriptive label to the title property of content objects. Adding a label in this way allows you to group content by that label with sorting content within the same folder. For example, adding a chapter label to the title property of topics groups topics by chapter within the Topics folder.

July 31, 2025 Page 36 of 49

Chapter 1

Strategies for organizing content in root maps

Related Topics •

Create folders

Strategies for organizing content in root maps You can organize content in root maps by referencing only topics, only submaps, or both. Topics Referencing only topics in root maps is a simple and valid approach, but can quickly become hard to manage as topics are added even for relatively small documents.

July 31, 2025 Page 37 of 49

Chapter 1

Strategies for organizing content in root maps

Submaps Consider using a only-submaps approach where you reference only submaps in the root map and only insert topics in submaps. We recommend this approach because it's easier to move or reuse sets of topics when they are in submaps especially in large documents.

July 31, 2025 Page 38 of 49

Chapter 1

Strategies for organizing content in root maps

Submaps themselves can contain only topics or nested submaps and topics.

July 31, 2025 Page 39 of 49

Chapter 1

Strategies for organizing content in root maps

Submaps allow you to: •

Organize content by chapters or smaller groups of topics.

•

Reuse a group of topics.

•

Reorganize content within a document.

•

Set conditions on a group of topics.

•

Coordinate multiple writers working on the same document by isolating topics by assignment.

Topics and submaps Like submaps, root maps can use a combination of topics and submaps:

July 31, 2025 Page 40 of 49

Chapter 1

Strategies for chunking topics

Related Topics •

Create a root map

•

Create submaps

•

Create topics

Strategies for chunking topics The Content Pages template was designed to use chunking to display topics sets together. If you chunk at the chapter-level, consider setting the chunk attribute at a lower level. Read more on strategies for picking which level to chunk at and how to code chunks.

Which level to chunk at Ideally, chunk at the first-level under the chapter orientation topic. For example, all chapters in this guide are chunked at the first-level topic under each chapter orientation topic:

July 31, 2025 Page 41 of 49

Chapter 1

Strategies for chunking topics

If it isn't feasible to chunk at the first-level, chunk at the same level throughout the book or across a chapter and at the highest level possible. For example, this chapter is chunked at the second-level topic. If it isn't feasible to chunk all chapters in this guide at the second-level, chunk at the same level within each chapter.

July 31, 2025 Page 42 of 49

Chapter 1

Strategies for chunking topics

How to code chunks Where to set the chunk attribute depends on whether a publication uses topics or submaps as chapters. In a publication that uses chapters as topics, set the chunk attribute on first-level topics (or lower) in the main map: <chapter href="GUID" format="dita"> <topicmeta><navtitle>Chapter Topic Title</navtitle></topicmeta> <topicref chunk="to-content" href="GUID" format="dita"> <topicmeta><navtitle>Parent Topic Title</navtitle></topicmeta> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> </topicref> <topicref chunk="to-content" href="GUID" format="dita"> <topicmeta><navtitle>Parent Topic Title</navtitle></topicmeta> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> </topicref> </chapter> In a publication with chapters as submaps, set the chunk attribute on the first-level topics (or lower) in each submap: <map id="GUID"> <topicmeta><navtitle>Chapter Topic Title</navtitle></topicmeta> <topicref chunk="to-content" href="GUID" format="dita"> <topicmeta><navtitle>Parent Topic Title</navtitle></topicmeta> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> </topicref> <topicref chunk="to-content" href="GUID" format="dita">

July 31, 2025 Page 43 of 49

Chapter 1

Strategies for structuring navigation <topicmeta><navtitle>Parent Topic Title</navtitle></topicmeta> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> </topicref> </map> Do not set the chunk attribute under another chunked topic. Doing so causes build failures. For example, the first-level topic is chunked, so the second-level topic underneath it cannot also be chunked. <topicref chunk="to-content" href="GUID" format="dita"> <topicmeta><navtitle>Parent Topic Title</navtitle></topicmeta> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> <topicref chunk="to-content" href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> </topicref> <topicref href="GUID" format="dita"> <topicmeta><navtitle>Child Topic Title</navtitle></topicmeta> </topicref> </topicref>

Strategies for structuring navigation The Content Page template includes different navigation panes for multiple-chapter versus single-page guides. Multiple-chapter guides include left and right navigation panes. The left pane includes the parent topic of a chunked topic set or non-chunked topics. The right pane shows the child topics in a chunked topic set and only appears for chunked topics. Single-page guides only include the right navigation pane. All topics are chunked automatically and the right pane shows the child topics.

July 31, 2025 Page 44 of 49

Chapter 1

Strategies for structuring navigation

Why use a flat navigation structure The higher the level that the chunk attribute is set, the flatter the navigation structure will be. It's easier to scan A flat navigation structure is easier to scan.

Even a short list is easier to scan when it's flat. Compare the nested entries to the updated flat structure in the table below.

July 31, 2025 Page 45 of 49

Chapter 1

Strategies for structuring navigation

Table 1-1

Nested versus flat navigation

BEFORE: Nested

AFTER: Flat

Biology Anatomy Skeleton Senses Coat Tail Health Lifespan Reproduction Neutering Inbreeding depression

Biology Anatomy Health Reproduction Inbreeding depression

It supports findability and discovery A flat navigation structure makes what's available and where to find it apparent. Not only does a flat structure support findability, but it also supports discovery of new information. See how a flat structure affects findability by answering the following questions. Where would you look for the following information in Table 2 below: •

How to restore a pluggable database under Back Up and Recovery or Pluggable Databases?

•

How to connect to a pluggable database under Connect or Pluggable Databases?

Table 1-2

Chapter with nested categories

BEFORE: Chapter with categories

Manage Pluggable Databases DB Systems Connect Monitor Events Backup and Recovery Oracle Data Guard Association When the categories are removed: •

Is it easier to find how to restore and connect to a pluggable database in the table below?

•

Did you find content you didn't know existed?

July 31, 2025 Page 46 of 49

Chapter 1

Strategies for structuring navigation

Table 1-3

Chapters for each category

AFTER: Separate chapters for each category

Manage Pluggable Databases About Pluggable Databases Clone a Pluggable Database Refresh a Pluggable Database Convert a Refreshable Clone to a Regular Pluggable Database Restore a Pluggable Database Relocated a Pluggable Database Create a Pluggable Database Stop a Pluggable Database Start a Pluggable Database Delete a Pluggable Database Get Connection Strings for a Pluggable Database SQL Worksheets Manage DB Systems Check the Status of a DB System Start a DB System Stop a DB System Reboot a DB System Scale a DB System Change the Shape of a DB System Clone a DB System Manage Tags for the DB System Manage Licenses on a DB System Move a DB System to Another Compartment Terminate a DB System View Work Request for the DB System Manage Connect Overview of Connecting to a DB System Connect to a Database using SQL*Net Connect to a Database with a Public IP by Using SSH Tunneling Connect to a Database by Using SSH and the Bequeath Protocol Troubleshoot Connection Issues Manage Serial Console Connection to the DB System Manage Monitor Monitor Base Database Service Available Metrics for Base Database Service Resources View Metrics for Base Database Service Resources Monitor using Database Management Service Manage Database Management for Base Database Service Resources View Performance Hub Metrics for Base Database Service Resources Monitor using Oracle Enterprise Manager Monitor a Database with Enterprise Manager Express Monitor a Database with Enterprise Manager Database Control Manage Events Manage Diagnostics Collection for the DB System Database Service Events Incident Logs and Trace Files Event Types for Base Database Service Remediation for Database Service Events Manage Backup and Recovery

July 31, 2025 Page 47 of 49

Chapter 1

How the Content Page navigation works

Table 1-3

(Cont.) Chapters for each category

AFTER: Separate chapters for each category

Back Up and Recovery in Base Database Service Back Up a Database Using the Console Back Up a Database to Object Storage using RMAN Recover a Database using the Console Recover a Database from Object Storage using RMAN Backup Recover a Database from the OCI Classic Object Store Manage Oracle Data Guard Association Use Oracle Data Guard on a DB System Enable Oracle Data Guard on a DB System Perform Database Switchover and Failover Edit the Oracle Data Guard Association Reinstate a Database Terminate an Oracle Data Guard Association on a DB System Use Oracle Data Guard with the Database CLI

Ways to flatten the navigation structure Flattening the navigation structure can be done using various methods and can be done iteratively. Replace chapter-level chunking For books that are chunked at the chapter level, move the chunk attribute to the first-level (or lower) and publish the content to see how navigation changes. For books with more than a few nested levels of topics, the right navigation might not reveal all levels and might benefit from chunking at a lower level. Remove organizational categories For chapters that contain organizational categories with nested content, consider creating separate chapters for each category to flatten the navigation. Refactor the content into standalone topic sets As content is being updated consider ways to refactor it into a standalone topic set. Creating logical sets of topics that always need to stay together helps flatten the navigation structure by surfacing overly nested content.

When to use automatically generated links Automatically generated or manually added parent-child links can be removed because they are duplicated in the right navigation. To remove automatically generated links select None or No Family in Generate Child Links (Jarvis) or Auto-Gen Links (DocBuilder). Links are removed from HTML and PDF output. Obviously, any parent-child links that were manually added must also be removed manually.

How the Content Page navigation works What appears on the navigation tree (left side bar) and on the "On this page" (right side bar). Authoring with OAK Foundation and Oxygen F60978-17 Copyright © 2023, 2025, Oracle and/or its affiliates.

July 31, 2025 Page 48 of 49

Chapter 1

How the Content Page navigation works

Where chunked topics appear Parent and child topics in chunked topic sets appear in different navigation panes. Parent topics appear in the navigation tree in the left side bar. Up to three levels of nested child topics appear in the On This Page navigation in the right side bar. Parent topics and all levels of child topics appear in the middle content pane. Navigation Tree (left side bar)

Content Pane

On this page (right side bar)

Chapter Topic Parent Topic Parent Topic

Parent Topic Child Topic Child Topic Child Topic

Parent Topic Title Child Topic Title Child Topic Title Child Topic Title

What appears in the On This Page navigation Different levels of child topics appear depending on the HTML structure. How many levels appear in the On This Page navigation Up to three levels of nested child topic titles can appear in the On This Page navigation. The number of nested levels depends on how heading 2, 3, and 4 tags are assigned in the HTML. If h2 is used as the page title, then only two levels of nested topics (h3 and h4) appear in the On This Page navigation on the right side bar. Which headings appear in the On This Page navigation Titles of parent and child topics appear in the On This Page navigation on the right side bar. However, section titles do not appear; sections are used to organize content within topics, not for navigation.

July 31, 2025 Page 49 of 49

2 Installing and working with OAK Foundation and Oxygen 27 Before installing or upgrading OAK Foundation, review which version of Oxygen is supported. You can use Oxygen 17.1 with SDL Knowledge Center at the same time as Oxygen 27 with OAK Foundation. Use the Check Out With command in SDL Knowledge Center to open content in Oxygen 17.1. To get started with OAK Foundation, review how to work with the main interface components and which components you can use to complete different tasks. System requirements •

Oxygen XML Author 27.0 and OAK Foundation 1.22 or later

•

Oxygen XML Author 27.1 and OAK Foundation 1.23 or later

•

Windows operating systems only

Upgrade to Oxygen 27.1, then upgrade to the latest OAK Foundation version Upgrade from Oxygen 24.1 or 27.0 to version 27.1 using your existing license, then upgrade the OAK Foundation add-ons to the latest version. Before you begin •

If you are upgrading from Oxygen 27.0, your existing license is still valid; no action is needed.

•

If you are upgrading from Oxygen 24.1, find your Oxygen 24.1 license in an email message from SOFTWARE-COMPLIANCE_WW. If you can't find it, send the SGN number from the About dialog box (Help menu) to Danny Yip.

•

If your team uses an Oxygen license server, request VPN SSO with Lab Access entitlement. For detailed steps, see How to request account/entitlement/role via OIM.

Download Oxygen 27.1 1.

Connect to VPN.

In Chrome or Firefox, go to https://uno.oraclecorp.com/uno/. If you aren't already authenticated, you'll be prompted to log in.

Click Tools & Software.

In Find Software, enter "oxygen", then press Enter.

Select Oxygen XML Author or Oxygen XML Editor.

July 31, 2025 Page 1 of 21

Chapter 2

Upgrade to Oxygen 27.1, then upgrade to the latest OAK Foundation version

If prompted, download and install dssm.exe. The DSSM program installs silently. 6.

For Oxygen XML Author, select 27.1_Windows_x64_Named. For Oxygen XML Editor 27.1_Windows_x64_Floating, then click the Download icon.

Install Oxygen 27.1 7.

Run the Setup program, following the prompts. Be sure to remove the previous version and select the file associations used by OAK Foundation. a.

Click Uninstall to remove version 24.1 or 27.0.

July 31, 2025 Page 2 of 21

Chapter 2

Upgrade to Oxygen 27.1, then upgrade to the latest OAK Foundation version

Select file associations for XML, DITAMAP, and DITAVAL Documents.

When the installation is done, select Run Oxygen XML Author, then click Finish.

July 31, 2025 Page 3 of 21

Chapter 2

Upgrade to Oxygen 27.1, then upgrade to the latest OAK Foundation version

Oxygen opens. Upgrade to the latest version of OAK Foundation 8.

If you're prompted to import the previous add-ons, click Review and Import.

Select the OAK Foundation add-ons, then click Import. •

OAK Foundation DITA framework

•

OAK Foundation DITAMAP framework

•

OAK Foundation plug-in

July 31, 2025 Page 4 of 21

Chapter 2

Upgrade to Oxygen 27.1, then upgrade to the latest OAK Foundation version

10. Accept the license agreements, then click Import. 11. Close and reopen Oxygen.

Enter your license key If you are upgrading from Oxygen 27.0, go to step 13. 12. In Oxygen 27.1, select Register from the Help menu. a.

Select Use a license key.

Paste your licensing key in the license registration box, then click OK.

July 31, 2025 Page 5 of 21

Chapter 2

Upgrade to Oxygen 27.1, then upgrade to the latest OAK Foundation version

Remove add-ons for Oxygen 24.1 or 27.0 13. If prompted, select to remove the Oxygen 24.1 or 27.0 add-ons. Keep the version 17.1

add-ons.

14. Close and reopen Oxygen.

July 31, 2025 Page 6 of 21

Chapter 2

Install Oxygen 27.1 and OAK Foundation 1.23 or later for the first-time

Install Oxygen 27.1 and OAK Foundation 1.23 or later for the first-time Install Oxygen 27.1 and the latest version of OAK Foundation for the first-time. Use your existing version 17.1, 24.1, or 27.0 license – if you have one – or request a 27.1 license. If you are using Oxygen 17.1 with SDL, keep version 17.1 installed. Before you begin •

Log in to OIM and request access the DOCENG_OAKF_USER entitlement only. For detailed steps, see How to request account/entitlement/role via OIM.

•

For new Oxygen users, ask Danny Yip for a 27.1 license. You'll receive an email message from SOFTWARE-COMPLIANCE_WW with a license key.

•

For existing Oxygen users, use your version 17.1, 24.1, or 27.0 license provided in an email message from SOFTWARE-COMPLIANCE_WW. If you can't find this message, send the SGN number from the About dialog box (Help menu) to Danny Yip.

•

If your team uses an Oxygen license server, request VPN SSO with Lab Access entitlement. For detailed steps, see How to request account/entitlement/role via OIM.

Download Oxygen 27.1 1.

Connect to VPN.

In Chrome or Firefox, go to https://uno.oraclecorp.com/uno/. If you aren't already authenticated, you'll be prompted to log in.

Click Tools & Software.

In Find Software, enter "oxygen", then press Enter.

Select Oxygen XML Author or Oxygen XML Editor.

July 31, 2025 Page 7 of 21

Chapter 2

Install Oxygen 27.1 and OAK Foundation 1.23 or later for the first-time If prompted, download and install the DSSM Setup program (dssm.exe). It is installed in the background. 6.

For Oxygen XML Author, select 27.1_Windows_x64_Named. For Oxygen XML Editor 27.1_Windows_x64_Floating, then click the Download icon.

Install Oxygen 27.1 7.

Run the Setup program and follow the prompts, but don't remove version 17.1. a.

Select file associations for XML, DITAMAP, and DITAVAL Documents.

When the installation is done, select Run Oxygen XML Author, then click Finish.

July 31, 2025 Page 8 of 21

Chapter 2

Install Oxygen 27.1 and OAK Foundation 1.23 or later for the first-time

Oxygen opens. Install the latest version of OAK Foundation 8.

In Oxygen 27.1, select Install new add-ons from the Help menu.

In Show add-ons from, enter "https://oxygen-addons.doceng-oci.oraclecorp.com/ updateSite.xml".

10. Select the following add-ons, then click Next.

•

OAK Foundation DITA framework

•

OAK Foundation DITAMAP framework

•

OAK Foundation plug-in

July 31, 2025 Page 9 of 21

Chapter 2

Install Oxygen 27.1 and OAK Foundation 1.23 or later for the first-time

11. Accept the license agreements, then click Install. 12. Close and reopen Oxygen.

Enter your license key 13. In Oxygen 27.1, select Register from the Help menu. a.

Select Use a license key.

Paste your licensing key in the license registration box, then click OK.

July 31, 2025 Page 10 of 21

Chapter 2

Upgrade to the latest version of OAK Foundation

14. Close and reopen Oxygen.

The OAK Foundation menu appears in Oxygen 27.1.

Upgrade to the latest version of OAK Foundation When new versions of the OAK Foundation add-ons are available, you'll be prompted to install them the next time you open Oxygen. 1.

In Oxygen, select Check for add-on updates from the Help menu.

Select all of the add-ons, then click Update. •

OAK Foundation DITA framework

•

OAK Foundation DITAMAP framework

•

OAK Foundation plug-in

Accept the license agreements, then click Install.

Close and reopen Oxygen.

Remove OAK Foundation Typically you can upgrade from a previous version to the latest version of OAK Foundation,but you can remove the associated add-ons as needed. 1.

In Oxygen, select Manage add-ons from the Help menu.

Select all OAK Foundation add-ons, then click Uninstall.

Restart Oxygen.

July 31, 2025 Page 11 of 21

Chapter 2

How to work in Oxygen

How to work in Oxygen Oxygen is your main interface for creating and editing content for OAK Foundation. Oxygen can be optimized for DITA and customized to suit your preferences.

OAK Foundation menu The Oxygen add-ons for OAK Foundation installs OAK Foundation, customizes Oxygen, and integrates it with OAK Foundation. After you install the add-ons, you'll see the OAK Foundation menu and other custom menus and dialogs throughout Oxygen. To see the version of the build you're using, select About from the OAK Foundation menu.

DITA Perspective and recommended views The DITA Perspective is a predefined layout in Oxygen for authoring in DITA that is configured by default when you install OAK Foundation. It includes the DITA Maps and DITA menus and common DITA views like DITA Maps Manager, Attributes, and Elements.

July 31, 2025 Page 12 of 21

Chapter 2

How to work in Oxygen

Tips for working in the DITA perspective •

To add additional views, select Show View from the Window menu.

•

Your custom layout is saved between sessions.

•

To restore the default layout, select Reset Layout from the Window menu.

Editor The Editor is where you edit root maps, submaps, and topics. You can view content in different formats, including as element or attribute tags or as plain text. You can select different levels of markup to show in tags in Author mode. Author mode allows you to work with content using the commands in the DITA menu or from context menus.

July 31, 2025 Page 13 of 21

Chapter 2

How to work in Oxygen

Tips for working with the Editor •

Select different levels of markup shown from Full Tags with Attributes to No Tags from the

toolbar icon.

•

Maximize the Editor by selecting Maximize Editor Area from the Window menu, then deselect it to return to your normal layout.

•

To use the DITA menu, you must be in Author mode.

Custom elements in the content completion window The content completion window in Oxygen allows you to insert elements for OAK Foundation in maps and topics. When you press ENTER from a map or topic in the Editor, a content completion window lists valid elements based on the cursor location. OAK Foundation elements begin with an orange diamond. Make sure to select these custom elements when using the content completion window.

Results view The Results view shows the results of certain actions including validation, checking spelling, or search results.

July 31, 2025 Page 14 of 21

Chapter 2

How to work in DITA Maps Manager

How to work in DITA Maps Manager DITA Maps Manager in Oxygen is your main tools for working with maps, including the root map for a publication and submaps in the root map.

DITA Maps Manager Whenever you open a map, always open it in DITA Maps Manager, then set the map context correctly. Always open maps in DITA Maps Manager By default, maps always open in DITA Maps Manager. If you change this default preference, you might be prompted to choose DITA Maps Manager or the Editor every time you open a map. If you don't want to choose every time, you can set maps to always open in DITA Maps Manager. You can always change your preference for opening maps later.

Always set the map context when opening maps Map context must be set correctly for references in maps and topics to resolve. Context always points to the root map, but it is set differently for root maps and submaps. •

When you open a root map, set Context to <Current map>, which is the root map.

July 31, 2025 Page 15 of 21

Chapter 2

How to work in DITA Maps Manager •

When you open a submap, set Context to the root map by selecting its name.

References in DITA Maps Manager You can insert, move, or remove submap or topic references from DITA Maps Manager. •

Use the Append Child command to nest a submap or topic under another reference.

•

Use the Insert Before or Insert After commands to add a submap or topic as a peer to another reference.

•

You can move submaps or topics easily using drag-and-drop.

•

Use the Remove References command or press the Delete key to remove a submap or topic.

DITA Maps Manager and the Editor While DITA Maps Manager is the starting point for maps, the Editor is another tool you can use to work with maps. •

Save your changes using Ctrl+S – When you make changes to maps, it's important to save them in the tool you used to make them. To make sure your changes are saved correctly, press Ctrl+S.

•

Go directly to references within maps – When a map is open in both DITA Maps Manager and the Editor, you can select any reference in DITA Maps Manager to go to that element in the Editor.

•

Refresh to see your changes – To refresh (reload) a map, click

•

View topic titles – To show the topic titles instead of file names in DITA Maps Manager, click

•

or press F5.

, then select Show topic titles.

Switch between open objects – To scroll between open objects, click the backward or forward arrows: To select the open objects from a list, click the list icon, then select an object:

•

Open a map in the other tool – When open in DITA Maps Manager, double-click the root map to open it in the Editor. When open in the Editor, right-click the file tab, then select Open in DITA Maps Manager view.

•

Separate commands and buttons – The toolbar buttons inside DITA Maps Manager apply only to maps. The toolbar buttons and commands in Oxygen apply to content open in the Editor.

July 31, 2025 Page 16 of 21

Chapter 2

How to work in the OAK Foundation Workspace

How to work in the OAK Foundation Workspace The OAK Foundation Workspace is a file browser where you organize content and view important details like release labels and status, and a search engine for finding content in OAK Foundation.

OAK Foundation Workspace You access OAK Foundation from Oxygen. The Workspace is the main interface for OAK Foundation and where you'll complete most of your content management tasks. Tips for working with content in the Workspace in the left or right pane, respectively.

•

To view recently added folders or files, click

•

You can use toolbar buttons or context menus to manage folders and files. Click a toolbar button or right-click the desired item, then select a command from the context menu. For example, to add a folder under another folder, select the folder, then click that folder, then select Create Folder.

or right-click

Folder and file management Organize the folders and files stored in OAK Foundation from the Workspace. You can store any type of file in any folder; folders are not restricted by file type. You can create and move folders and delete any folders that are empty.

Predefined and custom search criteria You can find content from the Workspace using a variety of predefined or custom criteria. Predefined search criteria includes common metadata like title, GUID, and workflow status. You can define custom metadata in Changes or Release Label in the properties dialogs of content objects when they are checked in. To make full use of these custom metadata fields, define and follow consistent labeling and naming conventions.

When to overwrite or preserve local changes When the version of a content object in local storage differs from the same version stored in the OAK Foundation Database, you are prompted on whether to overwrite or preserve your local version. If you choose to overwrite, any changes made to your local version are lost and the database version is downloaded to local storage. If you choose to preserve the local version, it remains in local storage and becomes the working copy.

How to work in Manage Baseline The Manage Baseline dialog is where you manage the publication baseline by defining which version of content to include in a publication. Authoring with OAK Foundation and Oxygen F60978-17 Copyright © 2023, 2025, Oracle and/or its affiliates.

July 31, 2025 Page 17 of 21

Chapter 2

Where to complete tasks

Manage Baseline Manage Baseline is the interface for managing the publication baseline, which defines which version of content to include in a publication. You access the Manage Baseline dialog for a publication from the Workspace.

Tips for managing versions in Manage Baseline •

Use to work with the baseline version of content, including changing workflow status and opening and checking out content.

•

Use to create and apply new versions of content to the baseline. When you version content in Manage Baseline the new version is applied to the baseline and saved locally, so that you can start working with that version immediately.

•

Use to select previous versions of content to the baseline. When you select a different version in Manage Baseline, the selected version is applied to the baseline and saved locally, so that you can start working with that version immediately.

•

The Baseline submap is a local, system copy of the publication baseline referenced in the root map, but never edit the Baseline submap directly.

Where to complete tasks The tasks for authoring content are essentially the same regardless of whether you are working in OAK Foundation or another content management system. The main difference between content management systems is the tool you use to complete each task. Tool and Task Open the OAK Foundation Workspace.

Steps 1.

In Oxygen, select Open Workspace from the OAK Foundation menu.

July 31, 2025 Page 18 of 21

Chapter 2

Where to complete tasks

Tool and Task Open the Manage Baseline window. Browse and organize content. Search for content. Create a map or topic.

Create a publication.

Open content from a map. Open content from the Workspace. Open a topic, then... Check it out. Check out maps. Check out the latest version of content. Check out the baseline version of content.

Steps In the Workspace, right-click a publication, then select Manage Baseline.

In the Workspace, right-click the folder that you want to add a subfolder to, then select Create folder. In the Workspace, click the Search tab. 1.

In Oxygen, select Create New from the OAK Foundation menu.

Select the appropriate map or topic template under Maps or Topics.

Enter a descriptive name in Title, then click Next.

Go to the folder where you want to save the map or topic.

Select Check out and open, then click Create.

In the Workspace, right-click a root map, then select Create Publication.

The publication and root map are opened.

In DITA Maps Manager, double-click the content object in the map to open it in the Editor.

In the Workspace, right-click multiple content objects, then select Open.

In DITA Maps Manager, double-click the topic in the map to open it in the Editor.

In Oxygen, select Check Out from the OAK Foundation menu.

In DITA Maps Manager, right-click the map, then select Check Out from the OAK Foundation menu. In the Workspace, right-click up to 10 content objects, then select Check Out and Open.

In the Workspace, right-click the associated publication, then select Manage Baseline.

Right-click up to 10 content objects, then select Check Out and Open

In DITA Maps Manager, right-click the location, then select Append Child Map Reference Insert submaps or topics. or Topic Reference. Check in open content objects one at a time. Check in the latest version of content. Check in the baseline version of content. Change status of content.

In Oxygen, select Check In from the OAK Foundation menu.

In the Workspace, right-click one or more content objects, then select Check In.

In the Workspace, right-click the associated publication, then select Manage Baseline.

Right-click one or more content objects, then select Check In.

In the Workspace, right-click one or more content objects, then select Change Status.

Select a status, then click Change Status.

July 31, 2025 Page 19 of 21

Chapter 2

Where to complete tasks

Tool and Task Create a version or branch content.

Steps 1.

In the Workspace or Manage Baseline, right-click one or more content objects, then select Create Version.

Select whether to create a new version or branch.

Select Check out and open as needed, then select Create.

Select a different version 1. of an object.

Manage the publication baseline. Restore a previous revision.

In the Workspace or Manage Baseline, right-click the content object, then select Manage Versions.

Select the version or branch you want

In Manage Baseline, select a different version of content in the Version column.

Click Save.

To restore a revision of the current version: 1.

In the Workspace, right-click a content object, then select View Revisions.

Right-click the revision to restore, then select Restore Revision.

To restore a revision of a previous version:

Create a conref library topic.

Insert a conref library topic as a resource.

Insert a content reference.

Create a variable library topic.

In the Workspace, right-click a content object, then select View Versions.

Right-click the version, then select View Revisions.

Right-click the revision to restore, then select Restore Revision.

In Oxygen, select Create New from the OAK Foundation menu.

Select the appropriate conref library template under Library Topics.

Enter a descriptive name in Title, then click Next.

Go to the folder where you want to save the library.

Select Check out and open, then click Create.

In DITA Maps Manager, right-click Resources under backmatter, then select Insert After, Topic Reference.

Browse to the library topic or enter its GUID in Keyref, then click Insert.

In Oxygen, select Content Reuse from the DITA menu.

Select Key as the content source, then browse to the conref library.

Select the desired content from the table, then click Insert and Close.

In Oxygen, select Create New from the OAK Foundation menu.

Select the appropriate variable library template under Library Topics.

Enter a descriptive name in Title, then click Next.

Go to the folder where you want to save the library.

Select Check out and open, then click Create.

Enter a key name for the library in <othermeta>. Use the same key name for each peer library.

Create the content you want to reuse within <ph> elements and assign id attributes to each. Use the same ID for each peer variable.

July 31, 2025 Page 20 of 21

Chapter 2

Where to complete tasks

Tool and Task Insert a variable library topic as a resource.

Insert a variable.

Create a DITAVAL file to define the conditions for a publication.

Apply conditions to a publication. Apply a condition to content within a topic Apply a condition to an entire submap or topic

Steps 1.

In DITA Maps Manager, right-click Resources under backmatter, then select Insert After, Topic Reference.

Browse to the library topic or enter its GUID in Keyref, then click Insert.

With the <topicref> selected, select Insert Define Keys from the DITA menu.

Enter the key name you entered in the library topic, then click Save.

In Oxygen, select Content Reuse from the DITA menu.

Select Key as the content source, then browse to the conref library.

Select the desired content from the table, then click Insert and Close.

In Oxygen, select Create New from the OAK Foundation menu.

Select the Conditions template under Maps.

Enter a descriptive name in Title, then click Next.

Go to the folder where you want to save the library.

Select Check out and open, then click Create.

In the Workspace, right-click the publication, then select Properties.

Browse to the DITAVAL file you want to associated with the publication.

In Oxygen, select the element you want to conditionalize.

In the Attributes view, select the condition attribute and value you want to apply.

In Oxygen, select the <topicref> or other reference element you want to conditionalize.

In the Attributes view, select the condition attribute and value you want to apply.

July 31, 2025 Page 21 of 21

3 Authoring in OAK Foundation Creating publications and adding content to them and editing content for existing publications follow slightly different workflows.

Browse the repository and organize content Browse and organize content in OAK Foundation using the Workspace.

Open the OAK Foundation Workspace Browse and search the content repository using the OAK Foundation Workspace. You must authenticate via Oracle SSO to work with content in OAK Foundation. You must reauthenticate periodically.

•

In Oxygen from the OAK Foundation menu, select Open Workspace. If you aren't already authenticated, you'll be prompted to log in. If you are authenticated, You can close this window now appears in the browser. The OAK Foundation Workspace opens.

Create folders Create, rename, and move folders as needed. You can save any object type in any folder. You can delete empty folders as needed. We recommend keeping the publication, root map, and DITAVAL file (if used) in a Publication Resources folder and storing other object types in separate folders by type.

In the Workspace, right-click the folder that you want to add a subfolder to, then select Create folder.

Enter a name for the folder, excluding special characters, such as dashes (-), then click OK.

July 31, 2025 Page 1 of 13

Chapter 3

Create a publication and add content to it

Create a publication and add content to it Make sure to follow the publication creation workflow when creating a publication and adding content to it. Before you create a publication, the root map that you want to use must be checked in. When you create a publication, the root map you selected is associated with the publication. Check out the root map in DITA Maps Manager and you're ready to create and insert submaps or topics in the root map. When you're done, check in your newly created content. 1.

Create a root map.

Create a publication.

Check out the root map for a new publication.

Create and check out content.

Insert content in maps

Check in content.

Related Topics •

Publication creation

Create a root map You must create a root map before you can create a publication. You must create a publication before you can insert references into a root map. When creating content, you must use a Document Engineering template, which assigns a GUID needed to add files to OAK Foundation. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Under Maps, select a root map template, such as Bookmap or Bookmap (Letter-style) under DB Maps.

In Title, enter a descriptive name for the root map, then click Next.

Browse to the folder where you want to save the root map.

Clear Check out and Open, then click Create.

Create a publication Before you can create a publication, the root map you want to use must be checked in. When you create a publication, the root map is associated with the publication. 1.

In the Workspace, right-click a root map, then select Create Publication.

On the Pub Details tab, enter metadata for the publication. a.

In Title, enter the document title; for example, "Database Administrator Guide". This field is required and appears on Books interface pages.

In Release Label, enter a standardized label used to identify the current version of the publication. This field is optional.

In Pub Type, select the type of publication: Book (for multipage books) or Letter (for single page or letter-style books).

July 31, 2025 Page 2 of 13

Chapter 3

Create a publication and add content to it

In Part Number, enter the part number for the publication.

In Doc ID, enter the five-character doc ID associated with the part number.

Click Create. The publication is saved in the same folder as the root map and opened. The root map opens in DITA Maps Manager by default.

In DITA Maps Manager, set Context to <Current map> (the root map).

Check out the root map for a new publication When you create a publication, the associated root map is opened. You can then check it out, so that you can insert submaps or topics in it. root map, then under

OAK Foundation, select

In DITA Maps Manager, right-click the Check Out .

In DITA Maps Manager, set Context to <Current map> (the root map).

Create and check out content Create each new submap and topic using the associated Document Engineering template. You can check out content (excluding publications) immediately after you create it.

Create submaps Use submaps to organize topics within a root map. Newly created submaps are checked out and opened by default. When creating content, you must use a Document Engineering template, which assigns a GUID needed to add files to OAK Foundation. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Under Maps, select a submap template , such as Submap under DB Maps.

In Title, enter a descriptive name for the submap, then click Next.

Browse to the folder where you want to save the submap.

Select Check Out and Open, then click Create. The submap is checked out and opened in DITA Maps Manager by default.

In DITA Maps Manager, set Context to the named root map.

Create topics Use topics to convey a standalone concept, task, or reference materials. Newly created topics are checked out and opened by default. When creating content, you must use a Document Engineering template, which assigns a GUID needed to add files to OAK Foundation. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Select a topic template under Topics.

Enter a descriptive name for the topic in Title, then click Next.

Browse to the folder where you want to save the topic.

July 31, 2025 Page 3 of 13

Chapter 3

Create a publication and add content to it 5.

Select Check Out and Open, then click Create. The topic is checked out and opened in Oxygen.

Enter the topic content.

Insert content in maps Although we recommend organizing topics in submaps, then inserting those submaps into the root map, you can also insert topics directly in root maps.

Insert chapters in a root map You can insert a topic or a submap as a chapter. The first topic in a chapter is typically an orientation topic. In the output, the orientation topic title is the chapter title. An orientation topic typically contains only a short description. If you chunk your content, you won't need to include autogenerated links to the child topics because they automatically appear in the right navigation pane. 1.

In DITA Maps Manager, right-click where you want to insert a chapter, then under Insert Before or Insert After, select Chapter.

Browse to a topic or a submap or enter its GUID in Keyref, then click Insert. The XML code for a chapter is inserted. Here's a code snippet of a chapter-level topic: <chapter keyref="GUID" format="dita"> <topicmeta> <navtitle>Insert a chapter topic in a root map</navtitle> </topicmeta> </chapter> Here's a code snippet of a chapter-level submap: <chapter keyref="GUID" format="ditamap"> <topicmeta> <navtitle>Insert a chapter submap in a root map</navtitle> </topicmeta> </chapter>

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the root map, then under the menu, select Check In.

OAK Foundation

Insert topics directly in a root map You can insert topics directly in a root map when you are not using submaps. 1.

under Append Child, Insert Before, or Insert After

Browse to the topic or enter its GUID in Keyref, then click Insert.

July 31, 2025 Page 4 of 13

Chapter 3

Create a publication and add content to it The XML code for a topic reference is inserted. Here's a code snippet of a topic reference to a topic: <topicref keyref="GUID" format="dita" <topicmeta> <navtitle>Insert topics in a root map</navtitle> </topicmeta> </topicref> 3.

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the root map, then under the menu, select Check In.

OAK Foundation

Insert submaps in a root map Organizing topic sets into submaps and inserting them in the root map makes it easier to manage content especially in large documents. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager, right-click where you want to insert a submap, then under Append Map Reference. Child, select

Browse to a submap or enter its GUID in Keyref, then click Insert. The XML code for a submap is inserted. Here's a code snippet example of a map reference: <mapref keyref="GUID"> <topicmeta> <navtitle>Insert submaps in a map</navtitle> </topicmeta> </mapref>

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the Check In.

root map, then under

OAK Foundation, select

Insert topics in a submap Although you can insert topics directly in root maps, consider inserting submaps in root maps, then inserting topics in those submaps. Steps 1.

In the submap, right-click where you want to insert the topic, then under Append Child, Insert Before, or Insert After, select Topic Reference.

Browse to the topic or enter its GUID in Keyref, then click Insert.

July 31, 2025 Page 5 of 13

Chapter 3

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the submap, then under the select Check In.

OAK Foundation menu,

Check in content You can check in multiple content objects at once or one at a time.

Check in content open in DITA Maps Manager You can check in multiple content objects at once or one at a time from DITA Maps Manager. If the Check In command isn't available, the selected object is not checked out, so it cannot be checked in. 1.

To check in objects one at a time: a.

In DITA Maps Manager, right-click an object, then under the menu, select Check In.

Enter a meaningful comment, then click Check In.

OAK Foundation

To check in multiple objects at once: a.

In DITA Maps Manager, right-click the desired object, then under the Foundation menu, select Check In.

Enter a meaningful comment that applies to all content or clear Use for all remaining files to enter unique comments for each content object.

Click Check In.

OAK

Check in content open in Oxygen You can check in multiple content objects at once or one at a time from Oxygen. If the Check In command isn't available, the selected object is not checked out, so it cannot be checked in. 1.

To check in objects one at a time: a.

In Oxygen from the OAK Foundation menu, select Check In.

Enter a meaningful comment, then click Check In.

To check in multiple objects at once: a.

In the Editor, right-click an open tab, then select Close All or other relevant command.

Select Check in file and keep Apply to all remaining files selected, then click OK.

Enter a meaningful comment that applies to all content or clear Use for all remaining files to enter unique comments for each content object.

July 31, 2025 Page 6 of 13

Chapter 3

Edit content for an existing publication d.

Click Check In.

Edit content for an existing publication Make sure to follow the publication editing workflow when editing content for an existing publication. Before you edit content for a publication, always open the publication; the associated root map is automatically opened. Check out the root map or submaps to insert or reorganize content. Check out topics to edit them. When you're done, check in your updated content. 1.

Open a publication and check out its root map.

Check out content.

Edit content.

Check in content.

Related Topics •

Publication editing

Open a publication and check out its root map When you open a publication, the associated root map is opened and a copy of all objects in the publication including the Baseline submap are saved to local storage. You can check out the root map at the same time if you need to insert or reorganize content in it. These local copies are needed to resolve references in the root map associated with the publication. Setting the correct map context helps prevent validation errors and resolve key references throughout the root map. 1.

In the Workspace, right-click the publication, then select Open.

When prompted whether to check out the root map, click Check Out. The publication is opened. The root map opens in DITA Maps Manager by default.

Set Context to <Current map> (root map).

Check out content You can check out up to 10 content objects at once or one at a time. You can version content in a frozen status (Complete or Released) when you check it out.

Check out submaps When you check out a submap, set the Context to the named root map in DITA Maps Manager. You can version a frozen submap (Complete or Released state) when you check it out. submap, then select Check Out from the

In DITA Maps Manager, right-click the Foundation menu.

If the content is in Complete or Released status, create a version: a.

Select New latest version or New branch.

Keep Check out and open selected.

Click Create.

OAK

July 31, 2025 Page 7 of 13

Chapter 3

Edit content for an existing publication 3.

In DITA Maps Manager, set Context to the named root map.

Check out content from Manage Baseline (baseline version) When you check out content from Manage Baseline, you are working with the baseline version of content. You can check out up to 10 content objects and open them in Oxygen, so that you can edit them. You can version content in a frozen status (Complete or Released) when you check it out. 1.

In the Workspace, right-click a publication, then select Manage Baseline.

In Manage Baseline, select up to 10 content objects.

Right-click the selection, then select Check Out and Open.

If the content is in the Complete or Released status, create a version: a.

Select New latest version or New branch.

Keep Check out and open selected.

Click Create.

Edit content Edit the content in a publication by editing the submaps and topics in the root map. •

To build out a traditional book by adding the pieces to a root map; see Inserting traditional book pieces.

•

To use DITA elements and attributes when writing content, see Developing topic content.

Check in content You can check in multiple content objects at once or one at a time.

To check in objects one at a time: a.

In DITA Maps Manager, right-click an object, then under the menu, select Check In.

Enter a meaningful comment, then click Check In.

OAK Foundation

To check in multiple objects at once: a.

In DITA Maps Manager, right-click the desired object, then under the Foundation menu, select Check In.

Enter a meaningful comment that applies to all content or clear Use for all remaining files to enter unique comments for each content object.

Click Check In.

OAK

July 31, 2025 Page 8 of 13

Chapter 3

Release a publication

To check in objects one at a time: a.

In Oxygen from the OAK Foundation menu, select Check In.

Enter a meaningful comment, then click Check In.

To check in multiple objects at once: a.

In the Editor, right-click an open tab, then select Close All or other relevant command.

Select Check in file and keep Apply to all remaining files selected, then click OK.

Enter a meaningful comment that applies to all content or clear Use for all remaining files to enter unique comments for each content object.

Click Check In.

Check in content from Manage Baseline (baseline version) When you check in content from Manage Baseline, you are working with the baseline version of content. You can check in multiple content objects at once or one at a time. To check in all checked out content, sort Manage Baseline by locked status. 1.

In the Workspace, right-click the publication, then select Manage Baseline.

Right-click the content objects, then select Check In.

Enter a meaningful comment that applies to all content or clear Use for all remaining files to enter unique comments for each content object.

Click Check In.

Release a publication When you're ready to publish your final content, check that the baseline includes the correct versions, synchronize the baseline, set all content to Complete, then set the publication to Complete. 1.

Validate the root map

Review the publication baseline.

Synchronize the publication baseline manually

Set all content in the baseline to Complete.

Set the publication to Complete.

Related Topics •

Publication release

July 31, 2025 Page 9 of 13

Chapter 3

Release a publication

Validate the root map It's important to validate the root map before releasing and publishing. Issues caught by this check must be fixed in the content and might not be reported during publishing. Outstanding Schematron issues are also reported. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager, select the tab for the root map.

Press F5 to reload the map.

In Oxygen from the DITA Maps menu, select Validate and Check for Completeness.

Select Batch validate referenced DITA resources.

Select these checks:

•

Report links to topics not referenced in DITA maps – Finds topics that are referenced by other topics, but not referenced in the root map. For example, topics defined in relationship tables that are not referenced in the root map.

•

Report multiple references to the same topic – If selected, finds where a topic is referenced multiple times in the root map without a unique copy-to attribute.

•

Check for duplicate topic IDs within the DITA map context – Finds any topics that have the same ID within the root map.

•

Report table layout problems – Finds issues within table elements; for example, if a row has fewer cells than columns.

•

Identify possible conflicts in profile attribute values – Finds conditions used in topics that are not defined in the DITAVAL file.

Click Check. Issues are returned in the Results pane.

Review the publication baseline Typically you will release the latest version of content, but there are times when you need to release previous versions of content with a publication. Regardless, before you release a publication, review the versions in the baseline to make sure that you are including the correct content. 1.

In the Workspace, right-click a publication, then select Manage Baseline.

Check for newer versions:

Sort by the Latest column, so that any rows set to "No" appear at the top.

Select different versions in the Version column as needed.

If you selected different versions, click Save to apply those version selections to the baseline.

Check metadata fields for content that belongs to a different release:

July 31, 2025 Page 10 of 13

Chapter 3

Release a publication

Sort by columns you are using to flag content for this release, including Release Label, Changes, Keyword, Feature Number, or Bug Number

Select different versions in the Version column as needed.

If you selected different versions, click Save to apply those version selections to the baseline.

Check for objects with inactive statuses: a.

Sort by the Status column, so that any rows set to "Inactive" or "Inactive-Released" appear at the top.

Remove any inactive content from the associated maps and topics before you continue the release process.

Synchronize the publication baseline manually Typically, the publication baseline in Manage Baseline is updated automatically; however, there are times when you must synchronize it manually. Before you begin Check in all content objects that are in the baseline. Steps 1.

In the Workspace, right-click the publication, then select Manage Baseline.

Click the

Sync with Map icon.

The baseline is updated with all objects being referenced in the root map.

Set all content in the baseline to Complete Before you can promote a publication to Production, all content in the baseline needs to have a Complete or Released status. You need to set all In-Progress content to Complete. Content that has already been published to Production is set to Released as part of the publishing process. Typically, this task is done for the Final UAT or Direct to Stage build. You can change the status of one or more objects at a time. When you change the status of multiple objects, the change is made only to objects with the same starting status. 1.

In the Workspace, right-click the publication, then select Manage Baseline.

Right-click the desired content objects, then select Change Status.

If the objects you selected are in multiple states, select the starting status you want to change in the Selected Status.

Select the status you want to update the content with in New Status.

Sort by the Status column and confirm that all content is set to Complete or Released.

Set the publication to Complete Before you set the publication to Complete, all content in the baseline needs to have a Complete or Released status. 1.

In Oxygen from the OAK Foundation menu, select Open Workspace.

Right-click the publication, then select Change Status.

July 31, 2025 Page 11 of 13

Chapter 3

Prepare a publication for a new release 3.

Click Change Status to set the publication to "Complete."

Prepare a publication for a new release When you're ready to start working on a new release, request a part number revision, version the root map and publication, then associate the new root map version with the new publication version. 1.

Request a part number.

Create a version of a root map.

Create a version of a publication.

Change the root map associated with a publication.

Related Topics •

Publication preparation

Request a part number Request a new base part number and doc ID for documents that have never been assigned a part number. Request a part number revision for a document that is on docs.oracle.com and is being updated for a release. 1.

To request a new base part number, see How to request a part number and doc ID.

To request a part number revision, see How to request a part number revision.

Create a version of a root map Create a version or branch of a root map. To associate the new version with a publication, you need to select that version in the properties of the publication. 1.

In the Workspace, right-click the root map, then... a.

To start from the latest version, select Create Version.

To start from a previous version, select Manage Versions, right-click the desired version, then select Create Version.

Select New latest version or New branch.

To immediately check out the new version, select Check out and open.

Click Create.

Create a version of a publication You can a create a version or branch of a publication. 1.

In the Workspace, right-click the publication, then... a.

To start from the latest version, select Create Version.

To start from a previous version, select Manage Versions, right-click the desired version, then select Create Version.

Select New latest version or New branch.

Click Create.

July 31, 2025 Page 12 of 13

Chapter 3

Prepare a publication for a new release

Change the root map associated with a publication When you version the root map associated with a publication, you need to select that version in the properties of the publication; you cannot change the root map version in the publication baseline. You can associate a different root map for a publication in the same way. 1.

In the Workspace, right-click the publication, then select Properties.

On the Root Map tab, select the root map:

•

To select a different version of the root map, select the appropriate version number .

•

To select a different root map, click version is selected.

Browse to select it. By default, the latest

Click Save.

July 31, 2025 Page 13 of 13

4 Inserting traditional book pieces Prefaces, abstracts, parts, appendices, glossaries, and indexes are parts of traditional books and can be added to root maps as needed. The standard legal notice is added to publications at build time; you can add custom legal notices as needed.

Create and insert a custom legal notice If Oracle Legal requires a custom legal notice for a product, create a topic using the text provided by the Legal team and insert it the front matter of the root maps of product documents.

Create a custom legal notice topic If directed by Legal, create a topic with the provided legal notices. Newly created topics are checked out and opened by default. When creating content, you must use a Document Engineering template, which assigns a GUID needed to add files to OAK Foundation. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Under Topics, select Common Topics, then select the Orientation topic template .

In Title, enter a descriptive name, then click Next.

Go to the folder where you want to save the topic.

Select Check out and open, then click Create. The content object opens in Oxygen.

Enter the topic content.

In Oxygen from the OAK Foundation menu, select Check In.

Insert a custom legal notice Insert a custom legal notice topic in the front matter of the root map. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager, right-click frontmatter at the top of the root map, then under Append Child, select Notices.

Browse to the custom legal notice topic or enter its GUID in Keyref, then click Insert.

In DITA Maps Manager, right-click the custom legal notice topic that you just inserted, then select Edit Properties.

July 31, 2025 Page 1 of 14

Chapter 4

Create and insert a preface 4.

Click Attributes, then select "required" in the importance attribute. The XML code for a custom legal notice is inserted. Here's the code snippet for a reference to a notice: <frontmatter> <notices keyref="GUID-FBFCEB4F-30EB-4D65-8CE5-2F11CFB41704" format="dita" importance="required"> <topicmeta> <navtitle>Custom Legal Notice</navtitle> </topicmeta> </notices> </frontmatter>

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the Check In.

root map, then under

OAK Foundation, select

Create and insert a preface Use the About This Content template to create a preface quickly. This preface template contains all potential sections, some that you customize, like Audience and standard ones that have been inserted as content references, like Conventions. You can delete any section that doesn't apply to your content. You must add the Common Topics conref library topic as a resource, so that the content references in the preface template resolve.

Create a preface topic Optionally, use a preface to introduce the document including its scope, audience, and conventions. When creating content, you must use a Document Engineering template, which assigns a GUID needed to add files to OAK Foundation. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Under Topics, select Common Topics, then select the About This Content topic template.

In Title, enter "About This Content" or another descriptive name, then click Next.

Go to the folder where you want to save the topic.

Select Check out and open, then click Create. The content object opens in Oxygen.

Follow the instructions in the template to add content about the document, then remove any unneeded sections.

In Oxygen from the OAK Foundation menu, select Check In.

July 31, 2025 Page 2 of 14

Chapter 4

Create and insert a preface

Add the Common Topics conref library topic as a resource The "About this content" used to create a preface references content in the Common Topics conref library, so this library must be added to the root map of your publication as a resource. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager under backmatter at the bottom of the root map, right-click Resources, then under Append Child, select Topic Reference.

Click Browse, select the Conrefs for Common Topics Templates library topic under System/Common/Libraries, then click Insert. The library topic is added to the Resources group. Here's a code snippet of a conref library inserted as a resource in a root map: <topicgroup processing-role="resource-only"> <topicmeta> <navtitle>Resources</navtitle> </topicmeta> <topicref keyref="GUID-80783511-8CF0-4AB2-9C1A-6BBEA6F30D42" format="dita"> <topicmeta> <navtitle>Conrefs for Common Topics Templates</navtitle> </topicmeta> </topicref> </topicgroup>

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the Check In.

root map, then under

OAK Foundation, select

Insert a preface Insert a preface in multi-chapter guides as needed. Don't insert a preface in single chapter (letter-style) guides. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager, right-click frontmatter at the top of the root map, then under Append child, select Preface.

Browse to the About this content topic or enter its GUID in Keyref, then click Insert.

July 31, 2025 Page 3 of 14

Chapter 4

Create and insert a document summary (book abstract) The XML code for the preface is inserted. Here's a code snippet for a reference to a preface: <preface keyref="GUID-EDCD53DA-8A4D-4C74-94DD-A02AFED85941" format="dita"> <topicmeta> <navtitle>About this content</navtitle> </topicmeta> </preface> 3.

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the root map, then under the menu, select Check In.

OAK Foundation

Create and insert a document summary (book abstract) You can summarize the contents of a document (book abstract) and have it appear on the Title and Copyright Information page in HTML output.

Create a book abstract topic Optionally, use a book abstract to summarize the contents of a document. When creating content, you must use a Document Engineering template, which assigns a GUID needed to add files to OAK Foundation. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Under Topics, select Common Topics, then select Concept.

In Title, enter "Abstract", then click Next.

Go to the folder where you want to save the topic.

Select Check out and open, then click Create. The topic opens in Oxygen.

Leave the short description blank.

In the body text, enter one or two sentences inside a <p> element that starts with "Documentation that describes..." or "Documentation for <audience> that describes..."

In Oxygen from the OAK Foundation menu, select Check In.

Insert a book abstract You can insert a book abstract in the front matter to summarize the contents of a document. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager, right-click frontmatter at the top of the root map, then under Append Child, select Book Abstract.

July 31, 2025 Page 4 of 14

Chapter 4

Group chapters into parts 2.

Browse to the Abstract topic or enter its GUID in Keyref, then click Insert. The XML code for a book abstract is inserted. Here's the code snippet for a reference to a book abstract: </booklists> <bookabstract keyref="GUID-C0319FBB-6BFE-4185-8A58-75E7A23B7E5B"/></frontmatter>

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the Check In.

root map, then under

OAK Foundation, select

Group chapters into parts Use parts to divide the chapters of a guide into logical groupings. Large guides can benefit from adding parts as an additional level of organization.

July 31, 2025 Page 5 of 14

Chapter 4

Group chapters into parts

Create part topics Use part topics to organize chapters into logical groups. The "Part" label and number are added automatically. Newly created topics are checked out and opened by default. When creating content, you must use a Document Engineering template, which assigns a GUID needed to add files to OAK Foundation. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Under Topics, select Common Topics, then select the Orientation topic template.

In Title, enter a descriptive name, then click Next.

July 31, 2025 Page 6 of 14

Chapter 4

Create and insert appendices 4.

Go to the folder where you want to save the topic.

Select Check out and open, then click Create. The content object opens in Oxygen.

Enter the topic content.

In DITA Maps Manager, right-click the Check In.

root map, then under

OAK Foundation, select

Insert parts Use parts to organize chapters into groups. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager, right-click the last chapter , then under Insert After, select Part.

Browse to the part orientation topic or enter its GUID in Keyref, then click Insert. The XML code for a part is inserted. Here's a code snippet of a topic reference to a part orientation topic: </chapter> <part keyref="GUID" format="dita"> <topicmeta> <navtitle>Part</navtitle> </topicmeta> </part>

Drag-and-drop chapters into the associated Part.

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the root map, then under the menu, select Check In.

OAK Foundation

Create and insert appendices You can insert appendices as topics or submaps in root maps.

In Oxygen from the OAK Foundation menu, select Create New.

Under Maps, select a submap template , such as Submap under DB Maps.

July 31, 2025 Page 7 of 14

Chapter 4

Create and insert appendices 3.

In Title, enter a descriptive name for the submap, then click Next.

Browse to the folder where you want to save the submap.

Select Check Out and Open, then click Create. The submap is checked out and opened in DITA Maps Manager by default.

In DITA Maps Manager, set Context to the named root map.

In Oxygen from the OAK Foundation menu, select Create New.

Under Topics, select a topic template.

In Title, enter a descriptive name for the topic, then click Next.

Enter the topic content.

In Oxygen from the OAK Foundation menu, select Check In.

Insert appendices You can insert one or more appendices in a root map. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager, right-click backmatter at the bottom of the root map, then under Insert Before, select Appendices.

In DITA Maps Manager, right-click Appendices, then under Append Child, select Appendix.

Browse to the appendix submap or orientation topic or enter its GUID in Keyref, then click Insert. The XML code for the appendix or appendices is inserted. Here's a code snippet for a single appendix submap: </chapter> <appendices> <appendix keyref="GUID" format="ditamap"> <topicmeta> <navtitle>Troubleshooting</navtitle> </topicmeta> </appendix> </appendices> <backmatter>

July 31, 2025 Page 8 of 14

Chapter 4

Add a glossary Here's a code snippet for a single appendix orientation topic: </chapter> <appendices> <appendix keyref="GUID" format="dita"> <topicmeta> <navtitle>Troubleshooting</navtitle> </topicmeta> </appendix> </appendices> <backmatter> 4.

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the root map, then under the menu, select Check In.

OAK Foundation

Add a glossary Before you can start adding glossary terms to a glossary, you need to create a submap to hold the terms and a topic to provide the Glossary title, then insert the Glossary submap under the back matter in the root map .

Create the Glossary orientation topic Create a topic that provides the heading for the list of glossary terms. When creating content, you must use a Document Engineering template, which assigns a GUID needed to add files to OAK Foundation. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Select the Orientation template under Topics/Common Topics.

Enter "Glossary" in Title, then click Next.

Go to the folder where you want to save the topic.

Select Check out and open, then click Create. The topic opens in Oxygen.

Enter "Glossary" as the topic title.

In Oxygen from the OAK Foundation menu, select Check In. Enter a meaningful comment. The selected content is checked in.

Create a Glossary submap Create a submap to store the glossary terms. When creating content, you must use a Document Engineering template, which assigns a GUID needed to add files to OAK Foundation. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Select a submap template under Maps.

Enter "Glossary" in Title, then click Next.

July 31, 2025 Page 9 of 14

Chapter 4

Add a glossary 4.

Go to the folder where you want to save the map, then click Create.

Insert a glossary To include a glossary in a publication you need to insert a submap with the Glossary orientation topic in the associated root map. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager under backmatter at the bottom of the root map, right-click booklists, then under Append Child, select Glossary List.

Browse to the Glossary submap or enter its GUID in Keyref, then click Insert. The XML code for a Glossary submap is inserted. Here's the code snippet for a reference to a submap. <backmatter> <booklists> <glossarylist keyref="GUID-E8EFBB63-352E-43CF-AD62-1168B8137061"> <topicmeta> <navtitle>Glossary</navtitle> </topicmeta> </glossarylist> </booklists>

In DITA Maps Manager, right-click the Glossary entry, then under the menu, select Check Out.

OAK Foundation

In DITA Maps Manager, right-click the Glossary submap, then under Append Child, select Map Reference.

Browse to the Glossary topic or enter its GUID in Keyref, then click Insert. The XML code for the Glossary orientation topic is inserted. Here's the code snippet for a map reference: <topicref keyref="GUID" format="dita"> <topicmeta> <navtitle>Glossary</navtitle> </topicmeta> </topicref> </map>

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the root map, then under the menus, delect Check In .

OAK Foundation

July 31, 2025 Page 10 of 14

Chapter 4

Create and insert terms in the glossary

Create and insert terms in the glossary Create each new glossary entry topic using the associated Document Engineering template, insert them into the glossary submap, then create links to them from topics where the terms are introduced.

Note To resolve references and prevent validation messages, open the publication when inserting or removing submaps or topics in a root map.

Create glossary terms and their definitions Create a glossary entry topic for each individual glossary term and definition. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Select Glossary Entry under Topics/Common Topics.

Enter the glossary term in Title, then click Next.

Go to the folder where you want to save the topic.

Select Check out and open, then click Create. The topic opens in Oxygen.

Enter the glossary term in <glossterm>.

Enter the definition in <glossdef>.

In Oxygen from the OAK Foundation menu, select Check In. Enter a meaningful comment. The selected content is checked in.

Insert glossary terms in a glossary Insert glossary terms in alphabetic order in the glossary. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

Check out the Glossary submap and open it in DITA Maps Manager.

July 31, 2025 Page 11 of 14

Chapter 4

Build an index 5.

Set the map context to the named root map.

Steps 1.

In DITA Maps Manager, right-click where you want to add the glossary term in the Glossary submap, then underAppend Child, Insert Before, or Insert After, select Topic Reference .

Browse to a glossary term topic or enter its GUID in Keyref, then click Insert. The XML code for a glossary term is inserted. Here's a code snippet of a topic reference to a glossary term topic: <topicref keyref="GUID" format="dita"> <topicmeta><navtitle>Glossary Term</navtitle></topicmeta> </topicref>

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the submap, then under the select Check In.

OAK Foundation menu,

Insert an inline link to a glossary term (xref) Insert a cross-reference to create an inline link in the topic where you introduce a glossary term to the glossary entry where you define the term. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

In Oxygen, place the cursor where you want to insert the glossary term, press Enter, then select xref (cross reference).

Select Key, then click the Key icon.

Select the target glossary term.

Click Insert and Close. The XML code for a cross reference is inserted. The glossary term is displayed as the link text. Here's a code snippet of a cross reference to a glossary term: <xref keyref="GUID"/>

In Oxygen from the OAK Foundation menu, select Check In.

Build an index An index can help readers find information quickly.

July 31, 2025 Page 12 of 14

Chapter 4

Build an index

Insert index entries You can add first- and second-level index entries to topics. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open the topic in the Editor.

Steps 1.

In Oxygen, place the cursor inside keyword in the prolog, press Enter, then select indexterm.

Enter the first-level index term. The XML code for an index entry is inserted. Here's a code snippet for an index term: <prolog> <metadata> <keywords> <indexterm>index entries</indexterm> </keywords> </metadata> </prolog>

To create a second-level index entry, place the cursor inside the first-level indexterm, press Enter, then select indexterm.

Enter the second-level index term. The XML code for an index entry is inserted. Here's a code snippet for a nested index term: <prolog> <metadata> <keywords> <indexterm>index entries <indexterm>inserting</indexterm> </indexterm> </keywords> </metadata> </prolog>

In Oxygen from the OAK Foundation menu, select Check In.

Insert see or see also index entries You can create index entries that reference preferred (see) or related (see-also) index terms used elsewhere in the index. Before you begin Authoring with OAK Foundation and Oxygen F60978-17 Copyright © 2023, 2025, Oracle and/or its affiliates.

July 31, 2025 Page 13 of 14

Chapter 4

Build an index 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

In Oxygen, place the cursor inside the indexterm, press Enter, then select index-see or index-see-also.

Enter the related or preferred term. The XML code for a see or see also index entry is inserted. Here's a code snippet for these index entries: <prolog> <metadata> <keywords><indexterm>index terms<index-see>index entries</index-see></indexterm> <indexterm>index entries<index-see-also>indexes</index-see-also></indexterm> </keywords> </metadata> </prolog>

In Oxygen from the OAK Foundation menu, select Check In.

July 31, 2025 Page 14 of 14

5 Working with content in publications You can take various actions on content including combining (or chunking) topic sets together, making copies of content objects, finding and replacing content in a publication, and checking the spelling of content in a publication.

Create content Create root maps, submaps, and topics using the provided Document Engineering templates. Create publications by selecting the root map you want to associate with the publication.

In Oxygen from the OAK Foundation menu, select Create New.

Under Maps, select a root map template, such as Bookmap or Bookmap (Letter-style) under DB Maps.

In Title, enter a descriptive name for the root map, then click Next.

Browse to the folder where you want to save the root map.

Clear Check out and Open, then click Create.

Create a publication Before you can create a publication, the root map you want to use must be checked in. When you create a publication, the root map is associated with the publication. 1.

In the Workspace, right-click a root map, then select Create Publication.

On the Pub Details tab, enter metadata for the publication.

In Title, enter the document title; for example, "Database Administrator Guide". This field is required and appears on Books interface pages.

In Release Label, enter a standardized label used to identify the current version of the publication. This field is optional.

In Pub Type, select the type of publication: Book (for multipage books) or Letter (for single page or letter-style books).

In Part Number, enter the part number for the publication.

In Doc ID, enter the five-character doc ID associated with the part number.

Click Create. The publication is saved in the same folder as the root map and opened. The root map opens in DITA Maps Manager by default.

July 31, 2025 Page 1 of 14

Chapter 5

Create a new publication from an existing one 4.

In DITA Maps Manager, set Context to <Current map> (the root map).

In Oxygen from the OAK Foundation menu, select Create New.

Under Maps, select a submap template , such as Submap under DB Maps.

In Title, enter a descriptive name for the submap, then click Next.

Browse to the folder where you want to save the submap.

Select Check Out and Open, then click Create. The submap is checked out and opened in DITA Maps Manager by default.

In DITA Maps Manager, set Context to the named root map.

In Oxygen from the OAK Foundation menu, select Create New.

Under Topics, select a topic template.

In Title, enter a descriptive name for the topic, then click Next.

Enter the topic content.

In Oxygen from the OAK Foundation menu, select Check In.

Create a new publication from an existing one Create a new publication from an existing one when they share the same root map. The new publication has a unique PGUID and properties, is associated with the same root map as the original, and is associated with the same DITAVAL file. Although the new publication has its own baseline, it starts with the same baseline as the original. If you are creating a publication for a new release, we recommend versioning the original publication instead. 1.

In the Workspace, right-click the desired publication, then select Duplicate Object.

Update the title.

Click Browse to save the copy to a different folder than the original.

Click Duplicate to create the new publication.

In the Workspace, right-click the new publication, then select Properties.

On the Conditions tab, click Browse to select the DITAVAL file associated with the new publication. By default, the latest version is selected.

July 31, 2025 Page 2 of 14

Chapter 5

Check out content 7.

Click Save.

Check out content You can check out up to 10 content objects at once or one at a time. You can version content in a frozen status (Complete or Released) when you check it out.

In the Workspace, right-click the publication, then select Open.

When prompted whether to check out the root map, click Check Out. The publication is opened. The root map opens in DITA Maps Manager by default.

Set Context to <Current map> (root map).

Check out submaps When you check out a submap, set the Context to the named root map in DITA Maps Manager. You can version a frozen submap (Complete or Released state) when you check it out. 1.

In DITA Maps Manager, right-click the Foundation menu.

If the content is in Complete or Released status, create a version:

submap, then select Check Out from the

Select New latest version or New branch.

Keep Check out and open selected.

Click Create.

OAK

In DITA Maps Manager, set Context to the named root map.

In the Workspace, right-click a publication, then select Manage Baseline.

In Manage Baseline, select up to 10 content objects.

Right-click the selection, then select Check Out and Open.

If the content is in the Complete or Released status, create a version: a.

Select New latest version or New branch.

July 31, 2025 Page 3 of 14

Chapter 5

Enter book metadata for multipage and letter-style publications b.

Keep Check out and open selected.

Click Create.

Check out content from the Workspace (latest version) When you check out content from the Workspace, you are working with the latest version of content. You can check out up to 10 content objects and open them in Oxygen, so that you can edit them. You can version content in a frozen status (Complete or Released) when you check it out. 1.

In the Workspace, select up to 10 content objects from the same folder.

Right-click the selection, then select Check Out and Open.

If the content is in Complete or Released status, create a version: a.

Select New latest version or New branch.

Keep Check out and open selected.

Click Create.

Enter book metadata for multipage and letter-style publications In the root map, enter the product name, document title, and other metadata that describes the document. Don't delete unused book metadata elements because all are used by self-publishing to create the HTML and PDF output. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

In DITA Maps Manager, double-click the

root map to open it in the Editor.

In DITA Maps Manager, double-click the

root map to open it in the Editor.

Enter the self-publishing metadata for the document as needed. •

<booklibrary> – Enter the full product name; for example, "Oracle Database." This information is required and used by self-publishing.

•

<mainbooktitle> – Enter the document title; for example, "Database Administrator Guide." This information is required and used by self-publishing.

•

<booktitlerelease> – Enter the product release information, for example, "Release 15.2." This information is optional and used by self-publishing when provided.

•

<booktitleplatform> – Enter the platform information; for example, "for Linux." This information is optional and used by self-publishing when provided.

•

<published> – Leave blank or enter the month and year that the publication is being published for your reference only. Don't delete this element; it is used by selfpublishing.

•

<copyrfirst> – Leave blank or enter the first copyright year for your reference only. Don't delete this element; it is used by self-publishing.

July 31, 2025 Page 4 of 14

Chapter 5

Specify document authors for multipage and letter-style publications •

<copyrlast> – Leave blank or enter the most recent copyright year for your reference only. Don't delete this element; it is used by self-publishing.

•

<bookpartno> – Leave blank or enter the part number for the publication for your reference only. Don't delete this element; it is used by self-publishing.

•

<organization> – Leave this information as-is. Don't delete this element; it is used by selfpublishing.

Press Ctrl+S to save your changes.

In the Editor, close the root map.

In DITA Maps Manager, right-click the Check In.

root map, then under

OAK Foundation, select

Related Topics •

Create a root map

Specify document authors for multipage and letter-style publications If you want to credit the authors and contributors of a document, enter their names in the root map. You can enter the names of primary authors, contributing authors, or contributors (an individual or team who provided significant information). If there are many contributors, use the team name. Make sure to only include names of those who are current Oracle employees at the time of publication. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

In DITA Maps Manager, double-click the

Enter the author metadata for the document as needed.

root map to open it in the Editor.

•

<author> – Enter the first and last name of primary authors.

•

<author type="contributor"> – Enter the first and last name of contributing authors.

•

<author type="other"> – Enter the first and last or team name of contributors.

Delete unused author elements. This information is optional and used by self-publishing when provided.

Press Ctrl+S to save your changes.

In the Editor, close the root map.

In DITA Maps Manager, right-click the Check In.

root map, then under

OAK Foundation, select

Related Topics •

Create a root map

July 31, 2025 Page 5 of 14

Chapter 5

Insert content in maps

Insert content in maps Although we recommend organizing topics in submaps, then inserting those submaps into the root map, you can also insert topics directly in root maps.

Insert chapters in a root map You can insert a topic or a submap as a chapter. The first topic in a chapter is typically an orientation topic. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

In the output, the orientation topic title is the chapter title. An orientation topic typically contains only a short description. If you chunk your content, you won't need to include autogenerated links to the child topics because they automatically appear in the right navigation pane. Steps 1.

In DITA Maps Manager, right-click where you want to insert a chapter, then under Insert Before or Insert After, select Chapter.

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the root map, then under the menu, select Check In.

OAK Foundation

Insert topics directly in a root map You can insert topics directly in a root map when you are not using submaps. Before you begin 1.

Open the publication.

July 31, 2025 Page 6 of 14

Chapter 5

Insert content in maps 2.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager, right-click where you want to insert the topic, then under Append Child, Insert Before, or Insert After, select Topic Reference.

Browse to the topic or enter its GUID in Keyref, then click Insert. The XML code for a topic reference is inserted. Here's a code snippet of a topic reference to a topic: <topicref keyref="GUID" format="dita" <topicmeta> <navtitle>Insert topics in a root map</navtitle> </topicmeta> </topicref>

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the root map, then under the menu, select Check In.

OAK Foundation

Insert submaps in a root map Organizing topic sets into submaps and inserting them in the root map makes it easier to manage content especially in large documents. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager, right-click where you want to insert a submap, then under Append Child, select Map Reference.

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the Check In.

root map, then under

OAK Foundation, select

July 31, 2025 Page 7 of 14

Chapter 5

Check in content

Insert topics in a submap Although you can insert topics directly in root maps, consider inserting submaps in root maps, then inserting topics in those submaps. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

Check out the submap and open it in DITA Maps Manager.

Set the map context to the named root map.

Steps 1.

In the submap, right-click where you want to insert the topic, then under Append Child, Insert Before, or Insert After, select Topic Reference.

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the root map, then under the menu, select Check In.

OAK Foundation

Check in content You can check in multiple content objects at once or one at a time.

To check in objects one at a time: a.

In DITA Maps Manager, right-click an object, then under the menu, select Check In.

Enter a meaningful comment, then click Check In.

OAK Foundation

To check in multiple objects at once: a.

In DITA Maps Manager, right-click the desired object, then under the Foundation menu, select Check In.

OAK

July 31, 2025 Page 8 of 14

Chapter 5

Check in content b.

Enter a meaningful comment that applies to all content or clear Use for all remaining files to enter unique comments for each content object.

Click Check In.

To check in objects one at a time: a.

In Oxygen from the OAK Foundation menu, select Check In.

Enter a meaningful comment, then click Check In.

To check in multiple objects at once: a.

In the Editor, right-click an open tab, then select Close All or other relevant command.

Select Check in file and keep Apply to all remaining files selected, then click OK.

Enter a meaningful comment that applies to all content or clear Use for all remaining files to enter unique comments for each content object.

Click Check In.

In the Workspace, right-click the publication, then select Manage Baseline.

Right-click the content objects, then select Check In.

Enter a meaningful comment that applies to all content or clear Use for all remaining files to enter unique comments for each content object.

Click Check In.

Check in content from the Workspace (latest version) When you check in content from the Workspace, you are working with the latest version of content. You can check in multiple content objects at once or one at a time. To check in all checked out content, sort the Workspace by locked status. 1.

In the Workspace, right-click the content objects, then select Check In.

Enter a meaningful comment that applies to all content or clear Use for all remaining files to enter unique comments for each content object.

Click Check In.

Check in content from Manage Versions (previous version) If you are working with a previous version of content, check it out from Manage Versions. You can check in one content object at a time.

July 31, 2025 Page 9 of 14

Chapter 5

Undo changes to checked out content 1.

In the Workspace, right-click the content object, then select Manage Versions.

In Manage Versions, right-click the version, then select Check In.

Enter a meaningful comment.

Click Check In.

Undo changes to checked out content You can undo the changes made to one or more content objects. 1.

To undo changes made to content open in Oxygen:

•

In the Editor, select Undo Checkout from the OAK Foundation menu.

Changes made to the selected content object are ignored. 2.

To undo changes made to the latest version of content: a.

Open the Workspace.

Select the desired content objects, right-click the selection, then select Undo Checkout.

Changes made to the selected content objects are ignored. 3.

To undo changes made to the baseline version of content: a.

In the Workspace, right-click the associated publication, then select Manage Baseline.

Select the desired content objects, right-click the selection, then select Undo Checkout.

Changes made to the selected content objects are ignored.

Combine (chunk) topic sets in HTML output Use DITA chunking to combine sets of XML topics into a single HTML page. In a root map that uses chapters as topics, set the chunk attribute on first-level topics (or lower) in the main map. In a rootmap with chapters as submaps, set the chunk attribute on the firstlevel topics (or lower) in each submap. Do not set the chunk attribute under another chunked topic. Doing so causes build failures. 1.

In DITA Maps Manager, right-click the parent topic, then select Edit Properties.

On the Attributes tab, select to-content in the chunk attribute.

Set static file names for topics You can enter a file name for a topic that doesn't change regardless of its topic title or title property. 1.

In the Workspace or other dialog box, right-click the topic you want to set a file name for, then select Properties.

In HTML File Name, enter the desired file name, then click Save.

July 31, 2025 Page 10 of 14

Chapter 5

Copy content objects

Copy content objects You can make a copy of any topic, map, library topic, and publication, save the duplicate object to the same or different location as the original, then immediately check out and open the new object. 1.

In the Workspace, right-click the desired content object, then select Duplicate Object.

Update the title.

Click Browse to save the copy to a different folder than the original.

Select Check out and open this object after duplication.

Click Duplicate to make a copy of the selected content. The topic opens in Oxygen.

Move content You can move everything under a folder or individual content objects from one location to another.

Move a folder You can move a folder and any folders or content objects in that folder to a different location. 1.

In the Workspace, right-click a folder, then select Move to Folder.

Browse to the new folder location, then click Select. That folder and any folders or content under it are moved to the location you chose.

Move a content object You can move individual content objects to a different location one-at-a-time. 1.

In the Workspace, right-click a content object, then select Move to File.

Browse to the new folder location, then click Select. The object is moved to the location you chose.

Delete content in maps You can delete topics or maps referenced in submaps and root maps. The steps differ when you remove content in DITA Maps Manager versus the Editor. •

In DITA Maps Manager, right-click the item you want to delete, then select Remove References.

•

In DITA Maps Manager, select the items you want to delete, then press the Delete key.

•

In the Editor, select the <topicref> elements you want to delete, then press the Backspace or Delete key.

July 31, 2025 Page 11 of 14

Chapter 5

Spell-check files globally

Spell-check files globally To check the spelling of all topics in a map, open the publication to make the files available in local storage before running the spell-checker. Check out topics as needed, then check in your changes all directly in Oxygen.

Open a publication and its root map When you open a publication, the associated root map is opened and a copy of all objects in the publication including the Baseline submap are saved to local storage. These local copies are needed to resolve references in the root map associated with the publication. Setting the correct map context helps prevent validation errors and resolve key references throughout the root map. 1.

In the Workspace, right-click the publication, then select Open.

When prompted whether to check out the root map, click Open. The publication is opened. The root map opens in DITA Maps Manager by default.

In DITA Maps Manager, set Context to <Current map> (the root map).

Check the spelling of all topics in a map After you open the publication, you can check the spelling of all topics in a map without checking out anything. Review the matches, then check out only topics that require changes. In the Results view, evaluate each misspelled word then open and check out the needed topics to replace, ignore, or learn the unrecognized words. 1.

In Oxygen from the Edit menu, select Check Spelling in Files.

Under Scope, select Current DITA map hierarchy.

Under Options in File Filter, select *.xml.

Click Check All.

In the Results pane, review each occurrence of the text by double-clicking rows with the highlighted word or string. The corresponding topic opens with misspelled words underlined in red.

For each topic that needs to be changed, from the OAK Foundation menu, select Check Out.

Check in content from Oxygen You can check in any content object from Oxygen that is checked out and open in the Editor.

•

In Oxygen from the OAK Foundation menu, select Check In. Enter a meaningful comment. The selected content is checked in.

July 31, 2025 Page 12 of 14

Chapter 5

Add unknown words to the spell-checker

Add unknown words to the spell-checker You can add words to the spell-checker, so that they are recognized as correct. These words can include those specific to Oracle products or third-party technologies. You can view the list of learned words or delete them from the spell-checker as needed. 1.

In Oxygen, open or check out the individual topics with unknown words you want to add.

From the Edit menu, select Check Spelling.

When an unknown word is found, click Learn. To view the list of learned word or delete them, go to Editor / Spell Check / Dictionaries in the Preferences dialog (Options | Preferences).

When you spell-check individual files (Check Spelling) or a set of files (Check Spelling in Files), words you add are recognized as correct.

Find or replace text globally To find or replace text across all topics in a map, open the publication to make the files available in local storage before searching for a word or string. Check out topics as needed, then check in your changes all directly in Oxygen.

In the Workspace, right-click the publication, then select Open.

When prompted whether to check out the root map, click Open. The publication is opened. The root map opens in DITA Maps Manager by default.

In DITA Maps Manager, set Context to <Current map> (the root map).

Find and replace text across all topics in a map After you open the publication, you can find text across all topics in a map without checking out anything. Review the matches, then check out topics that require changes. 1.

In Oxygen from the Find menu, select Find/Replace in Files.

Select Ignore extra whitespaces, so that all instances of a text string are found.

Clear Enable XML search options when searching for text strings.

Enter the word or string that you want to find or replace. For information on using regular expressions, see Oxygen Help.

Select search options like Case sensitive as needed. For more information, see Oxygen Help.

Under Scope, select Current DITA map hierarchy.

Click Find All.

July 31, 2025 Page 13 of 14

Chapter 5

Find or replace text globally 8.

In the Results pane, review each occurrence of the text by double-clicking rows with the highlighted word or string. The corresponding topic opens with the text string highlighted in yellow.

For each topic that needs to be changed, from the OAK Foundation menu, select Check Out.

10. If the content is frozen, create a version: a.

Select New latest version or New branch.

Keep Check out and open selected.

Click Create.

Check in content from Oxygen You can check in any content object from Oxygen that is checked out and open in the Editor.

•

In Oxygen from the OAK Foundation menu, select Check In. Enter a meaningful comment. The selected content is checked in.

July 31, 2025 Page 14 of 14

6 Developing topic content While you can use standard DITA elements to develop topic content, how to use common and custom elements is covered here.

Code examples You can create examples of programming code with or without titles, set the programming language to highlight the syntactic components, hide the default copy button, or set large examples to span the width of the page.

Insert code examples You can insert code snippets for different programming languages to copy verbatim or use as examples. Enter the code exactly how you want it to appear. Line breaks and spaces are preserved. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the code example, press Enter, then select codeblock.

To enter a line break, press Enter, then select Insert New Line.

Copy and paste the code or enter it manually. Here's a code example: <codeblock> java -XX:OnError="cat hs_err_pid%p.log | mail support@example.com" MyApp </codeblock>

In Oxygen from the OAK Foundation menu, select Check In.

Insert code examples with a title You can include a title with code examples when needed for clarity, to provide a list of examples in the front matter of a guide, or to cross-reference the example. Enter the code exactly how you want it to appear. Line breaks and spaces are preserved. Before you begin Authoring with OAK Foundation and Oxygen F60978-17 Copyright © 2023, 2025, Oracle and/or its affiliates.

July 31, 2025 Page 1 of 38

Chapter 6

Code examples 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor inside the closing topic type element, press Enter, then select example.

Press Enter again, select title, then enter a descriptive title for the example.

Enter descriptive text above the code example using valid elements like <p> as needed.

With the cursor after the closing title element, press Enter, then select codeblock.

To enter a line break, press Enter, then select Insert New Line.

Copy and paste the code or enter it manually.

Enter descriptive text below the code example using valid elements like <p> as needed. Here's a code example with a title and descriptive text: <example id="example_cqz_2l4_nfc"> <title>Execute a user-supplied script or command </title> <p>In this example, the contents of the fatal error log file are mailed to a support alias when a fatal error occurs.</p> <codeblock id="codeblock_r4k_5l4_nfc">java -XX:OnError="cat hs_err_pid%p.log | mail support@example.com" MyApp</codeblock> <p>Where string is a single command or a list of commands separated by semicolons. Within this string, all occurrences of %p are replaced with the current PID.</p> </example> </taskbody>

In Oxygen from the OAK Foundation menu, select Check In.

Set the programming language of code examples You can select the programming language of code examples, so that the syntactic components appear in different colors in the output making it easier to read. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Right-click the codeblock element, then select Edit Attributes.

In Name, enter outputclass.

July 31, 2025 Page 2 of 38

Chapter 6

Code examples 3.

In Value, select or enter the programming language: language-apache

language-javascript

language-bash

language-json

language-bourne

language-makefile

language-c

language-markdown

language-coffeescript

language-nginx

language-cpp

language-objectivec

language-csharp

language-perl

language-css

language-php

language-diff

language-python

language-http

language-ruby

language-ini

language-sql

language-java

language-xml

Here's a code example for Java: <codeblock outputclass="language-java"> java -XX:OnError="cat hs_err_pid%p.log | mail support@example.com" MyApp </codeblock> 4.

In Oxygen from the OAK Foundation menu, select Check In.

Show a Run in Live SQL button in SQL code examples You can link code examples of the SQL programming language to Oracle Live SQL, so that the examples can be run in the live SQL runtime environment. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Right-click the codeblock element, then select Edit Attributes.

In Name, enter outputclass.

In Value, enter "liveSQLbutton" after "language-sql" separated by a space.

July 31, 2025 Page 3 of 38

Chapter 6

Code examples Here's a code example for SQL with a Run in Live SQL button: <codeblock outputclass="language-sql liveSQLbutton"> DECLARE -- Associative array indexed by string: TYPE population IS TABLE OF NUMBER -- Associative array type INDEX BY VARCHAR2(64); -- Indexed by string city_population population; -- Associative array variable i VARCHAR2(64); -- Scalar variable BEGIN -- Add elements (key-value pairs) to associative array: city_population('Smallville') := 2000; city_population('Midland') := 750000; city_population('Megalopolis') := 1000000; -- Change value associated with key 'Smallville': city_population('Smallville') := 2001; -- Print associative array: i := city_population.FIRST; -- Get first element of array WHILE i IS NOT NULL LOOP DBMS_Output.PUT_LINE ('Population of ' || i || ' is ' || city_population(i)); i := city_population.NEXT(i); -- Get next element of array END LOOP; END; / </codeblock> 4.

In Oxygen from the OAK Foundation menu, select Check In.

Hide the Copy button in code examples For code examples that aren't suitable for copying, you can hide the Copy button from appearing in the output. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Right-click the codeblock element, then select Edit Attributes.

In Name, select outputclass.

In Value, enter nocopybutton. If a programming language value exists, then separate the values with a space; for example, "language-java nocopybutton".

Click OK.

July 31, 2025 Page 4 of 38

Chapter 6

Comments Here's a code example with the Copy button hidden: <codeblock outputclass="language-java nocopybutton"> java -XX:OnError="cat hs_err_pid%p.log | mail support@example.com" MyApp </codeblock> 5.

In Oxygen from the OAK Foundation menu, select Check In.

Align code examples to the page margin in PDF output You can set code examples to start at the page margin instead of being indented under the body text in the PDF output. In the HTML output, horizontal scrolling is always enabled when the lines don't fit inside the content area. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Right-click the codeblock element, then select Edit Attributes.

In Name, enter expanse.

In Value, enter page. Here's a code example aligned to the page margin:

<codeblock expanse="page"> java -XX:OnError="cat hs_err_pid%p.log | mail support@example.com" MyApp </codeblock> 4.

In Oxygen from the OAK Foundation menu, select Check In.

Comments You can insert comments that appear in draft output (draft comments) or only in the source (XML comments).

Insert external comments in draft output (draft-comments) You can enter comments for reviewers or other stakeholders. You can display draft comments in draft output. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

July 31, 2025 Page 5 of 38

Chapter 6

Footnotes 4.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert a draft comment.

Press Enter, then select draft-comment.

Enter text or other elements for the draft comment. Here's a code snippet of a draft comment. <draft-comment author="Dee Beck">When should users insert a draft comment?</draft-comment>

In Oxygen from the OAK Foundation menu, select Check In.

Insert internal comments (XML comments) You can enter comments are for internal notes. XML comments don't appear in the output.

Note If XML comments don't appear, then set the Show XML comments preference. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the XML comment or select the text to wrap in an XML comment.

Press Enter, then select comment.

Enter text for the XML comment. Here's a code snippet of an XML comment:

In Oxygen from the OAK Foundation menu, select Check In.

Footnotes Use a footnote for supplementary information that is not appropriate to be included in the flow of the content. The footnote content is not critical to understanding the content, but provides extra information that may be useful to some readers. Authoring with OAK Foundation and Oxygen F60978-17 Copyright © 2023, 2025, Oracle and/or its affiliates.

July 31, 2025 Page 6 of 38

Chapter 6

Footnotes

Insert footnotes Insert footnotes within elements such as lists, paragraphs, and tables to provide supplementary information below the element. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the footnote, press Enter, then select fn.

Enter the footnote text: Here's a code snippet of a footnote: <p>Always wear a seatbelt. <fn>Some jurisdictions allow a medical exemption from wearing a seat belt in exceptional circumstances.</fn> </p>

In Oxygen from the OAK Foundation menu, select Check In.

Create multiple links to the same footnote text Create multiple links to the same footnote text by adding an ID to the fn element a crossreference. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Right-click the fn element, then select Generate ID.

Create a cross-reference that points to the footnote: a.

Place the cursor where you want to insert the footnote, press Enter, then select xref (cross-reference).

Click the Keys icon.

Select the same topic that you have checked out, then click OK.

July 31, 2025 Page 7 of 38

Chapter 6

Images d. 3.

In the Insert Cross-Reference dialog box, in the list of target elements, select the topic (at the top of the list), and click Insert and close.

Set the type attribute of the <xref> element to fn: a.

Right-click the <xref> element, then select Edit Attributes.

In Name, enter type.

In Value, enter fn.

In Oxygen from the OAK Foundation menu, select Check In.

Images Add and insert screen shots, diagrams, and icons or other inline images.

Add and insert screen shots, diagrams, or flowcharts Images like screen shots, diagrams, or flowcharts that appear separately from text require an image description topic, which is inserted at the same time as the image.

Add images to OAK Foundation Add screen shots, diagrams, flowcharts, or other images to OAK Foundation, so that you can insert them into topics. Bitmap images (BMP, GIF, JPEG, JPG, PNG, TIF, and TIFF formats) are used online (HTML) and in print (PDF). 1.

In the Workspace, right-click the folder where you want to save the image, then select Add File.

Select the image file from your local folder. The image is added to OAK Foundation.

Create image descriptions An image description must describe all aspects of the image; that is, it must be equivalent to the information in the image. Readers with visual impairments use screen reader software to access the image descriptions. An image description topic is required for all images except icons. If you use an image more than once, then use the same image description topic. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Select Image Description under Topics/Common Topics.

Enter a descriptive name in Title, then click Next.

Go to the folder where you want to save the topic.

Select Check out and open, then click Create. The topic opens in Oxygen.

Follow the instructions in the template to describe the content of the corresponding image.

In Oxygen from the OAK Foundation menu, select Check In. Enter a meaningful comment.

July 31, 2025 Page 8 of 38

Chapter 6

Images The selected content is checked in.

Insert an image and image description Insert a screen shot or diagram in bitmap format such as PNG and the associated image description topic. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

In Oxygen, place the cursor where you want to insert the image, press Enter, then select image.

Browse to the image or enter its GUID in Image.

In Figure title, enter an optional title.

Browse to the associated image description topic or enter its GUID in Long Desc.

Leave Width, Height, and Scale blank. In the HTML output, the image is scaled for you. The width and height are scaled proportionately. In the PDF file, the width within the body text is 5.33 inches and the maximum width is 6.417 inches. The maximum height for an image (without a title) is 9.25 inches. The maximum height for a figure (with a title) is 9.0 inches. If an image is too large in the PDF output, then see Scale large images to fit the page in PDF output.

Select new line (break).

In Alignment, don't change the default value, left.

Select Wide image display to display an image within the page margins instead of within the text area. This option doesn't apply to an image that's inserted in a step, a list item, a table, or a note.

Click Insert. Here's a code snippet of an image with a long description: <image placement="break" keyref="GUID" align="left"> <longdescref keyref="GUID"/> </image>

10. From the OAK Foundation menu, select Check In.

Add and insert inline images Images like icons and buttons that appear on the same line as text require alternative text, which you enter when you insert the image.

July 31, 2025 Page 9 of 38

Chapter 6

Images

Add inline images to OAK Foundation Add an icon, button, or other inline image in bitmap format such as PNG to OAK Foundation. Bitmap images (BMP, GIF, JPEG, JPG, PNG, TIF, and TIFF formats) are used online (HTML) and in print (PDF). 1.

In the Workspace, right-click the folder where you want to save the images, then select Add File.

Select the PNG or other bitmap file from your local folder. The image is added to OAK Foundation.

Insert inline images and alternative text Insert an inline image in bitmap format such as PNG and provide a short description of the image as alternative text. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

In Oxygen, place the cursor where you want to insert the image, press Enter, then select image.

Browse to the image or enter its GUID in Image.

In Alternative text, enter a short description of the inline image.

In Height, enter a value between 14 and 19 px as needed.

Leave Width and Scale blank.

Select inline.

Click Insert. Here's a code snippet of an inline image with alternative text: <image placement="inline" keyref="GUID" height="14px" id="image_id"> <alt>Short description of the inline image</alt> </image>

From the OAK Foundation menu, select Check In.

Update images You can update screen shots, diagrams, flowcharts, and inline images via Local Storage. Using Local Storage in this way is limited to images as a short-term workaround. Do not use this method to update other content. Authoring with OAK Foundation and Oxygen F60978-17 Copyright © 2023, 2025, Oracle and/or its affiliates.

July 31, 2025 Page 10 of 38

Chapter 6

Inline links Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open the topic in the Editor.

Steps 1.

Capture the updated image.

Create a new version of the image; see Create a version or branch of content.

Check out this version of the image, which copies it to Local Storage; see Check out content.

Save the updated image to Local Storage (C:\Users\<Your Name>\AppData\Local\OAKF\oakf_local_storage_prod) and overwrite the new version of the image.

Check in the image; see Check in content.

With the topic tab selected in the Editor, press F5 to see the updated image inline.

Scale large images to fit the page in PDF output You can automatically scale large images in the PDF output. Use for atypical situations where images are correctly sized in the HTML output, but don't fit in the PDF output. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Right-click the image element, then select Edit Attributes.

In Name, enter scalefit.

In Value, enter yes.

In Oxygen from the OAK Foundation menu, select Check In.

Inline links You can create inline links to topics in the same publication or different publication, or to an external web page. The link syntax differs depending the link target.

July 31, 2025 Page 11 of 38

Chapter 6

Inline links

Insert an inline link to another topic in the same publication (xref) Insert a cross-reference to create an inline link to another topic in the same publication. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the cross-reference, press Enter, then select xref (cross-reference).

Select Key, then click the Key icon.

Select the target topic.

Select Topic in Show elements of type, then select the topic element row.

Click Insert and Close. The XML code for a cross-reference is inserted. The topic title appears as the link text. Here's a code snippet of a cross-reference to a topic: <xref keyref="GUID-63FFB773-1924-4644-BCFB-BFEAFC041558" />

In Oxygen from the OAK Foundation menu, select Check In.

Insert an inline link to a topic in a different publication (olink) Insert a cross-reference as an olink to create an inline link to a topic in a different publication. The olink syntax uses the doc ID of the target publication and the GUID of the target topic. To define an olink, you need the doc ID for the publication. You can select the target topic or manually enter the topic GUID. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the cross-reference, press Enter, then select xref (olink).

To select the target topic:

July 31, 2025 Page 12 of 38

Chapter 6

Inline links a.

Select Assemble from Doc ID and topic GUID.

Click

Click Insert.

Browse, select the target topic, then click OK.

The XML code for cross-reference using the olink syntax is inserted. The topic title appears as the link text. Here's a code snippet of cross-reference to a topic in a different publication: <xref href="olink:DBLDR-GUID-63FFB773-1924-4644-BCFB-BFEAFC041558" format="html" scope="external">Cancel an On-Demand Build</xref> 3.

To enter the topic information manually: a.

Enter the link text you want to appear in Navigation Title.

Select Enter targetptr.

Enter the doc ID and the topic GUID separated by a hyphen; for example, DBLDRGUID-63FFB773-1924-4644-BCFB-BFEAFC041558.

Click Insert. The XML code for cross-reference using the olink syntax is inserted. The topic title appears as the link text. Here's a code snippet of cross-reference to a topic in a different publication: <xref href="olink:DBLDR-GUID-63FFB773-1924-4644-BCFB-BFEAFC041558" format="html" scope="external">Cancel an On-Demand Build</xref>

In Oxygen from the OAK Foundation menu, select Check In.

Insert an inline link to a topic that also works in the PDF output (lookup URL) Insert an inline link to content on Oracle Help Center as a lookup URL, so that the link works in both the HTML and PDF output. Lookup URL syntax uses the context and ID of the target topic. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the inline link, press Enter, then select (external link).

To enter the context and ID and create a lookup URL: a.

xref

Enter the title of the content page in Navigation Title.

July 31, 2025 Page 13 of 38

Chapter 6

Inline links b.

Select Universal Syntax.

Enter the context in ctx.

Enter the target topic ID in id.

Click Insert. The XML code for an inline link as a lookup URL is inserted. The navigation title appears as the link text. Here's a code snippet of a cross-reference to a topic in another publication: <xref href="http://docs.oracle.com/pls/topic/lookup?ctx=en/internal/ua-knowledge-center/authoring/oakfoundation &id=OAKFM-GUID-1DD49E90-0436-46F7-A80A-B14B2584414F" format="html" scope="external">Lookup URL to topic in another publication</xref>

To enter the full lookup URL: a.

Enter the title of the web page in Navigation Title.

Select URL.

Enter the lookup URL using this syntax: https://docs.oracle.com/pls/topic/lookup?ctx=<context>&id=<target_ID>

Click Insert. The XML code for an external link is inserted. The navigation title appears as the link text. Here's a code snippet of a lookup URL to an interface page: <xref href="https://docs.oracle.com/pls/topic/lookup?ctx=clouds&id=IOTJP" format="html" scope="external">Inline link defined as a lookup URL</xref>

In Oxygen from the OAK Foundation menu, select Check In.

Insert an inline link to an external web page Insert an external link to create an inline link to a resources outside of the current publication. Resources can include web pages or content on Oracle Help Center. External links can be defined using a unilink, lookup URL, or static web address. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the external link, press Enter, then select (external link).

To enter a unilink:

xref

July 31, 2025 Page 14 of 38

Chapter 6

Inline links a.

Enter the title of the web page in Navigation Title.

Select unilink.

Enter the topic ID defined in Universal Linking.

Click Insert. The XML code for an inline link is inserted. The navigation title appears as the link text. Here's a code snippet of a unilink that resolves to a web page: <xref href="unilink:oakf-roadmap-timeline" format="html" scope="external"> Release timeline</xref>

To enter the context and ID and create a lookup URL: a.

Enter the title of the web page in Navigation Title.

Select Universal Syntax.

Enter the context in ctx.

Enter the target topic ID in id.

Click Insert. The XML code for an inline link is inserted. The navigation title appears as the link text. Here's a code snippet of a lookup URL that references content on Oracle Help Center: <xref href="http://docs.oracle.com/pls/topic/lookup?ctx=en/internal/ ua-knowledge-center/authoring/sdl/&id=OXYGN-GUID-1D90FC0D-E72E-4929AAE6-6CBA252080EB" format="html" scope="external">SDL Knowledge Center</xref>

To enter the full lookup URL: a.

Enter the title of the web page in Navigation Title.

Select URL.

Enter the lookup URL using this syntax: https://docs.oracle.com/pls/topic/lookup?ctx=<context>&id=<target_ID>

To enter a static web address: a.

Enter the title of the web page in Navigation Title.

Select URL.

Enter the web address.

Click Insert.

July 31, 2025 Page 15 of 38

Chapter 6

Inline text formatting The XML code for an inline link is inserted. The navigation title appears as the link text. Here's a code snippet of a cross-reference to a static URL: <xref href="https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/author-dita.html" format="html" scope="external">DITA AuthoringEdit</xref> 6.

In Oxygen from the OAK Foundation menu, select Check In.

Inline text formatting Format inline text by wrapping the text with a semantic element (preferred) or typographic element.

Format inline text When possible use a semantic element like <uicontrol> over a typographic one like <b>. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Select the inline text you want to format, press Enter, then select the desired inline element.

In Oxygen from the OAK Foundation menu, select Check In.

Format numerals with periods or commas Wrap a numeral in the ph (phrase) element, and set the dir (direction) attribute to ltr (left to right) if the number contains a period or a comma. The ph element and the ltr attribute value are needed for translation into languages that are written from right to left, to preserve the location of the period or comma relative to the numerals. Even if your publication isn't being translated currently, wrap numerals with periods or commas for possible future translation. The ph element doesn't change the formatting of the numeral. Don't use the ph element if a numeral is enclosed in the codeblock or codeph element. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

July 31, 2025 Page 16 of 38

Chapter 6

Lists 6.

Open and check out the topic in the Editor.

Steps 1.

Select the numeral that contains a period or comma, press Enter, then select ph.

Right-click the <ph> element, then select Edit Attributes.

In Name, select dir.

In Value, select ltr. Here's a code snippet with formatting: <p>This value is <ph dir="ltr">1.1</ph> megabytes.</p>

In Oxygen from the OAK Foundation menu, select Check In.

Lists Lists help organize, clarify, and emphasize information. Use numbered lists when the order is significant or when a series is suggested. Use unnumbered lists when the order is not significant and all items are of equal importance. Using coordinate conjunctions (stringing together lots of words, phrases, or clauses joined by "and" or "or") can make it difficult to understand the meaning of a sentence. To clarify meaning and make information easier to scan, replace coordinate conjunctions with lists.

Insert numbered lists (ol) Use ordered, numbered lists for items whose sequence is important. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want the list, press Enter, then select ol.

Enter the list item.

Press Enter, then select New li.

Enter another list item. Here's an code snippet of an ordered list: <ol> <li>Open the publication.</li> <li>Open the root map in DITA Maps Manager.</li> <li>If used, open the submap in DITA Maps Manager.</li> <li>Set the map context to the named root map.</li>

July 31, 2025 Page 17 of 38

Chapter 6

Lists <li>Open the topic.</li> </ol> 5.

In Oxygen from the OAK Foundation menu, select Check In.

Insert bulleted lists (ul) Use unordered, bulleted lists for items whose sequence is not important. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the list, press Enter, then select ul.

Enter the list item.

Press Enter, then select New li.

Enter another list item. Here's an code snippet of an unordered list: <ul> <li>License Restrictions Warranty/Consequential Damages Disclaimer</li> <li>Restricted Rights Notice</li> <li>Hazardous Applications Notice</li> <li> Trademark Notice</li> <li>Third-Party Content, Products, and Services Disclaimer</li> </ul>

In Oxygen from the OAK Foundation menu, select Check In.

Insert indented lists (sl) Use simple lists to indent items whose sequence is not important. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the list, press Enter, then select sl.

July 31, 2025 Page 18 of 38

Chapter 6

Lists 2.

Enter the list item.

Press Enter, then select New sli.

Enter another list item. Here's an code snippet of a simple list: <sl> <sli>Publication</sli> <sli>Root map</sli> <sli>Submaps</sli> <sli>Topics</sli> <sli>Libraries</sli> <sli>Images</sli> <sli>Image definitions</sli> </sl>

In Oxygen from the OAK Foundation menu, select Check In.

Insert lists of items and descriptions (dl) Use a definition list to insert a list of items and descriptions, like a list of terms and their definitions. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the list, press Enter, then select dl.

Enter the term in the dt element

Enter the definition in the dd element, .

To enter more than one description, add another dd element, and enter another description.

After the closing dd element, press Enter, then select New dlentry. Here's an code snippet of a definition list: <dl> <dlentry> <dt>Accessibility</dt> <dd>Documentation is accessible when the content imparts the same information to the user who has a disability as it does to the user who does not have a disability.</dd> <dd>Your documentation must be accessible regardless of how a user navigates through it.</dd> </dlentry> </dl> <dl> <dlentry>

July 31, 2025 Page 19 of 38

Chapter 6

Notes <dt>A1-assisted authoring</dt> <dd>Use AI-assisted authoring tools in Oracle Cloud to transcribe recordings, run editorial prompts, and create draft content in a secure authoring environment.</dd> </dlentry> </dl> <dl> <dlentry> <dt>Content findability</dt> <dd>Create findable content, understand user needs, and present content in a format that your readers and search engines can easily consume.</dd> </dlentry> </dl> 6.

In Oxygen from the OAK Foundation menu, select Check In.

Notes Use notes to draw attention to important information.

Insert notes, tips, cautions, and warnings You can insert different types of notes to expand on or call attention to a particular point. Avoid inserting notes in tables. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert a note, press Enter, then select note.

Enter the note text.

Right-click the <note> element, then select Edit Attributes.

In Name, select type.

In Value, select the note type: Option Description caution Indicates the possibility of damage to a program, system, or data. When used in a task, the caution notice should precede the step where the risk occurs. note

Provides important hints, guidance, or advice.

tip

Provides advice.

warning Indicates a potential hazard to people. When used in a procedure, the warning notice should precede the step where the risk occurs. In the output, the warning notice is shown in bold. Use warning notices only for hazards to people.

July 31, 2025 Page 20 of 38

Chapter 6

Related topics Here's a code snippet of a tip with a single paragraph: <note type="tip">Alternatively, you can display this window by entering <codeph>show symbols</codeph> at the command line.</note> Here's a code snippet of a caution with more than one paragraph: <note type="caution"> <p>Always use Oracle Fail Safe Manager to bring databases online and offline.</p> <p>Using other tools can result in unintended server failover or jeopardize the integrity of your database.</p> </note> 6.

In Oxygen from the OAK Foundation menu, select Check In.

Related topics Use related topics to link between topics within the same subject matter. Related topics can be inserted in maps, topics, or both and will appear in the same location in the publishing content regardless. Using related topics is preferred over inline links to support readability. Inserting related topics in maps is preferred over topics to support content reuse.

Insert related topics in a map (reltable) Insert a relationship table in a root map or submap to define related topic links. You can create one-way or two-way linking relationships. You can create multiple relationship tables to help organize content as needed. Before you begin 1.

Open the publication.

Check out the root map as needed and open it in DITA Maps Manager.

Set the map context to <Current map>.

If used, check out the submap as needed and open it in DITA Maps Manager.

Set the map context to the named root map.

Steps 1.

In DITA Maps Manager, double-click the

In the Editor, place the cursor before the closing <bookmap> or <map> element, press Enter, then select reltable (wizard).

To define one-way links from the source topics to the target topics:

•

root map to open it in the Editor.

Set "sourceonly" and "targetonly" in the linking attribute of the <relcolspec> elements in the Source and Target columns, respectively. Here's a code snippet of a relationship table with one-way linking: <reltable> <relheader> <relcolspec linking="sourceonly"> <title>Source</title> </relcolspec>

July 31, 2025 Page 21 of 38

Chapter 6

Related topics <relcolspec linking="targetonly"> <title>Target</title> </relcolspec> </relheader> 4.

To define two-way links between source and target topics:

•

Set "normal" in the linking attribute of the <relcolspec> elements in the Source and Target columns, respectively. Here's a code snippet of a relationship table with two-way linking: <reltable> <relheader> <relcolspec linking="normal"> <title>Source</title> </relcolspec> <relcolspec linking="normal"> <title>Target</title> </relcolspec> </relheader>

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the Check In.

root map, then under

OAK Foundation, select

Insert links in a relationship table You can create related links to topics in the same publication or a different publication, or link to an external web page in a relationship table. The link syntax differs depending the link target. Before you begin 1.

Open the publication.

Check out the root map as needed and open it in DITA Maps Manager.

Set the map context to <Current map>.

If used, check out the submap as needed and open it in DITA Maps Manager.

Set the map context to the named root map.

Steps 1.

In DITA Maps Manager, double-click the

root map to open it in the Editor.

To link to topics in the same publication (topicref): 2.

Place the cursor in the appropriate relationship table cell, press Enter, then select topicref (wizard).

Browse to a topic or enter its GUID in Keyref, then click Insert. The XML code for a topic reference is inserted. The topic title appears as the navigation title. Here's a code snippet of a topic reference to a topic in the same publication: <relcell> <topicref keyref="GUID" format="dita"> <topicmeta> <navtitle>Topic in this publication</navtitle>

July 31, 2025 Page 22 of 38

Chapter 6

Related topics </topicmeta> </topicref> </relcell> To link to topics in a different publication (olink): 4.

Place the cursor in the appropriate relationship table cell, press Enter, then select (wizard).

To select the target topic: a.

Select Assemble from Doc ID and topic GUID.

Enter the doc ID.

Browse to the target topic or enter its GUID in Topic GUID, then click Insert.

olink

The XML code for topic reference using the olink syntax is inserted. The topic title appears as the link text. Here's a code snippet of related topic link to a topic in a different publication: <relcell> <topicref href="olink:DBLDR-GUID-63FFB773-1924-4644-BCFB-BFEAFC041558" format="html" scope="external"> <topicmeta> <navtitle>Create an On-Demand Build</navtitle> </topicmeta> </topicref> </relcell> 6.

To enter the topic information manually: a.

Enter the link text you want to appear in Navigation Title.

Select Enter targetptr.

Enter the doc ID and the topic GUID separated by a hyphen, then click Insert. The XML code for topic reference using the olink syntax is inserted. The topic title appears as the link text. Here's a code snippet of related topic link to a topic in a different publication: <relcell> <topicref href="olink:DBLDR-GUID-50F6FCBD-9571-415B-BA23-EE255EE97915" format="html" scope="external"> <topicmeta> <navtitle>Cancel an On-Demand Build</navtitle> </topicmeta> </topicref> </relcell>

To link to an external web page (anchorref): 7.

Place the cursor in the appropriate relationship table cell, press Enter, then select anchorref (wizard).

Enter the title of the web page in Navigation Title.

Select URL.

10. Enter the web address, then click Insert.

July 31, 2025 Page 23 of 38

Chapter 6

Related topics The XML code for anchor reference is inserted. The navigation title appears as the link text. Here's a code snippet of related topic link to a web page: <relcell> <anchorref href="https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/author-dita.html" format="html" scope="external"> <topicmeta> <navtitle>DITA Authoring</navtitle> </topicmeta> </anchorref> </relcell> 11. Press Ctrl+S to save your changes. 12. In DITA Maps Manager, right-click the

root map, then under

OAK Foundation, select

Check In.

Insert related topics in a topic (related-links) Insert links to related topics in a topic using the <related-links> element. The link syntax differs depending on the link target. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor after the closing body element like <conbody>, press Enter, then select related-links.

To link to a topic in the same publication: 2.

Place the cursor inside the <related-links> element, press Enter, then select reference).

Select Key, then click the Key icon.

Select the target topic.

Select Topic in Show elements of type, then select the topic element row.

Click Insert and Close.

link (cross-

The XML code for a related topic link is inserted. The topic title appears as the link text. Here's a code snippet of a related topic link to a topic in the same publication: <related-links> <link keyref="GUID"/> </related-links> To link to a topic in a different publication:

July 31, 2025 Page 24 of 38

Chapter 6

Related topics 7.

Place the cursor inside the <related-links> element, press Enter, then select

To select the target topic:

link (olink).

Select Assemble from Doc ID and topic GUID.

Browse to the target topic or enter its GUID in Topic GUID, then click Insert. The XML code for a related topic using the olink syntax is inserted. The topic title appears as the link text. Here's a code snippet of a related topic link to a topic in a different publication: <related-links> <link href="olink:DBDLR-GUID-63FFB773-1924-4644-BCFB-BFEAFC041558" format="html" scope="external"> <linktext>Cancel an On-Demand Build</linktext> </link> </related-links>

To enter the topic information manually: a.

Enter the link text you want to appear in Navigation Title.

Select Enter targetptr.

Enter the doc ID and the topic GUID separated by a hyphen, then click Insert The XML code for a related topic using the olink syntax is inserted. The topic title appears as the link text. Here's a code snippet of a related topic link to a topic in a different publication: <related-links> <link href="olink:DBDLR-GUID-63FFB773-1924-4644-BCFB-BFEAFC041558" format="html" scope="external"> <linktext>Cancel an On-Demand Build</linktext> </link> </related-links>

To link to an external web page: 10. Place the cursor inside the <related-links> element, press Enter, then select

link (external

link). 11. Enter the title of the web page in Navigation Title. 12. Select URL. 13. Enter the web address, then click Insert.

The XML code for a related topic link is inserted. The topic title appears as the link text. Here's a code snippet of a related topic link as an web address: <related-links> <link href="https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/author-dita.html" format="html" scope="external"> <linktext>DITA Authoring</linktext> </link> </related-links> 14. Press Ctrl+S to save your changes. 15. In DITA Maps Manager, right-click the root map, then select Check In from the OAK

July 31, 2025 Page 25 of 38

Chapter 6

Tabbed interfaces

Tabbed interfaces You can present code examples for multiple programming languages on named tabs called tabbed interfaces. The element structure differs for different topic types. Tabbed interfaces appear the HTML output. In PDF output, the labels on the tabs are displayed as subheadings. The content in a tabbed interface shouldn't be lengthy or cause readers to scroll much. The labels on the tabs should be short, yet clearly identify the content in the tab. Avoid using a tabbed interface when readers won't benefit, such as for a long sequence of text, or where horizontal space is limited because of indentation, for example, in nested lists. Don't use a tabbed interface for hierarchical information. Aim for the right number of tabs. Too many tabs will look crowded and may be hard to use on a mobile device. If you can't answer the question "How does a tabbed interface help readers?" then you may need to use sections or separate topics instead.

Insert tabbed interfaces in task steps As part of a step in a task, you can present code examples for multiple programming languages on named tabs. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

In the task topic, place the cursor after the closing <cmd> element where you want the tabbed content, press Enter, then select choices.

Right-click the <choices> element, then select Edit Attributes.

In Name, select outputclass.

In Value, enter tabbed-interface.

Select the <choices> element, press Enter, then select choice.

Right-click the <choice> element, then select Edit Attributes.

In Name, select outputclass.

In Value, enter tab-pane.

Right-click the <choice> element, then select Edit Attributes.

10. In Name, select otherprops. 11. In Value, enter tab-title(<programming_language>); for example, "tab-title (UNIX)." 12. Place the cursor inside of the choice element, press Enter, then select p to enter

introductory text.

July 31, 2025 Page 26 of 38

Chapter 6

Tabbed interfaces 13. Place the cursor before the closing choice element, press Enter, then select codeblock to

enter the code snippet. Here's a code snippet of a single tab labeled "UNIX" with a paragraph and two code examples: <choices outputclass="tabbed-interface"> <choice outputclass="tab-pane" otherprops="tab-title(UNIX)"> <p>On UNIX operating systems, you can use one of the following installers:</p> <codeblock>/home/Oracle/jdk/jdk1.8.0_211/bin/java -jar fmw_14.1.1.0.0_wls_lite_generic.jar</codeblock> <codeblock>/home/Oracle/jdk/jdk1.8.0_211/bin/java -jar fmw_14.1.1.0.0_wls_lite_quick_slim_generic.jar</ codeblock> </choice> </choices> 14. Repeat Steps 5 through 13 for each additional tab.

Here's a code snippet that adds a second tab labeled "Windows" with a paragraph and two code examples: <choices outputclass="tabbed-interface"> <choice outputclass="tab-pane" otherprops="tab-title(UNIX)"> <p>On UNIX operating systems, use one of these installers:</p> <codeblock>/home/Oracle/jdk/jdk1.8.0_211/bin/java -jar fmw_14.1.1.0.0_wls_lite_generic.jar</codeblock> <codeblock>/home/Oracle/jdk/jdk1.8.0_211/bin/java -jar fmw_14.1.1.0.0_wls_lite_quick_slim_generic.jar</ codeblock> </choice> <choice outputclass="tab-pane" otherprops="tab-title(Windows)"> <p>On Windows operating systems, use one of these installers:</p> <codeblock>C:\Program Files\Java\jdk1.8.0_211\bin\java -jar fmw_14.1.1.0.0_wls_lite_generic.jar</ codeblock> <codeblock>C:\Program Files\Java\jdk1.8.0_211\bin\java -jar fmw_14.1.1.0.0_wls_lite_quick_slim_generic.jar</codeblock> </choice> </choices> 15. In Oxygen from the OAK Foundation menu, select Check In.

Insert tabbed interfaces in concepts or reference topics You can present code examples for multiple programming languages on named tabs in concepts, reference topics, or generic topics. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor in the <conbody>, <refbody>, or <body> element, press Enter, then select a valid "parent" element based on where you want the tabbed interface to be inserted:

July 31, 2025 Page 27 of 38

Chapter 6

Tabbed interfaces Option

Description

conbodydiv In concept topics, use to place a tabbed interface anywhere in the body. refbodydiv

In reference topics, use to place tabbed interface outside of a section.

bodydiv

In generic topics, use to place a tabbed interface anywhere in the body.

section

In concepts, reference topics, or generic topics, use to place a tabbed interface inside a new section.

sectiondiv

In concepts, reference topics, or generic topics, use to place a tabbed interface inside of an existing section.

Right-click the "parent" element, then select Edit Attributes.

In Name, select outputclass.

In Value, enter tabbed-interface. <conbodydiv outputclass="tabbed-interface"> </conbodydiv>

Place the cursor inside the "parent" element, press Enter, then select a "child" element: Option Description section

Valid inside <conbodydiv>, <refbodydiv>, and <bodydiv>

sectiondiv

Valid inside <section>

example

Valid inside <conbodydiv>, <refbodydiv>, <bodydiv>, and <section>

Right-click the "child" element, then select Edit Attributes.

In Name, select outputclass.

In Value, enter tab-pane.

Right-click the "child" element, then select Edit Attributes.

10. In Name, select otherprops. 11. In Value, enter tab-title(<programming_language>); for example, "tab-title (UNIX)."

<conbodydiv outputclass="tabbed-interface"> <section outputclass="tab-pane" otherprops="tab-title(Java)"></section> </conbodydiv> 12. Place the cursor inside the "child" element, press Enter, then select p to enter introductory

text. 13. Place the cursor inside the <p> element, press Enter, then select ol or ul to insert a

numbered or bulleted list. 14. Place the cursor inside the <ol> or <ul> element, press Enter, then select li to provide list

items as needed. 15. Place the cursor before the closing "child" element, press Enter, then select codeblock to

enter the code snippet. Here's a code snippet of a single tab labeled "Java" with a paragraph and a code example: <conbodydiv outputclass="tabbed-interface"> <section outputclass="tab-pane" otherprops="tab-title(Java)"> <p>Use this Java code to create a "Hello World" program:</p> Authoring with OAK Foundation and Oxygen F60978-17 Copyright © 2023, 2025, Oracle and/or its affiliates.

July 31, 2025 Page 28 of 38

Chapter 6

Tables <codeblock>class HelloWorld { public static void main(String[] args) { System.out.println("Hello World!"); } } </codeblock> </conbodydiv> 16. Repeat Steps 6 through 15 for each additional tab.

Here's a code snippet that adds a second tab labeled "C++" with a paragraph and code example: <conbodydiv outputclass="tabbed-interface"> <section outputclass="tab-pane" otherprops="tab-title(Java)"> <p>Use this Java code to create a "Hello World" program:</p> <codeblock>class HelloWorld { public static void main(String[] args) { System.out.println("Hello World!"); } } </codeblock> <section outputclass="tab-pane" otherprops="tab-title(C++)"> <p>Use this C++ code to create a "Hello World" program:</p> <codeblock>#include <iostream> int main() { std::cout << "Hello World!" << std::endl; return 0; } </codeblock> </conbodydiv> 17. In Oxygen from the OAK Foundation menu, select Check In.

Tables Use tables to organize complex relationships of tabular information.

Insert tables with titles (table) You can create formal tables with captions when you want to reference the tables in other topics, in the index, or in the front matter as a list of tables, for large tables that are longer than a printed page, or when needed for clarity. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps

July 31, 2025 Page 29 of 38

Chapter 6

Tables 1.

Place the cursor where you want to insert the table, press Enter, then select table (wizard).

Select Formal.

In Title, enter a descriptive title for the table.

In Description, enter a brief description of table content, starting with a verb, such as "Describes..."

Enter the number of rows and columns.

Click Insert.

Enter content in all table cells.

In Oxygen from the OAK Foundation menu, select Check In.

Insert tables (table) You can create informal tables without captions. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the table, press Enter, then select table (wizard).

Select Informal.

In Description, enter a brief description of table content, starting with a verb, such as "Describes..."

Enter the number of rows and columns.

Click Insert.

Enter content in all the table cells.

In Oxygen from the OAK Foundation menu, select Check In.

Insert tabular content (simpletable) You can create a simple table for tabular content that doesn't require a title, description, or heading row. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

July 31, 2025 Page 30 of 38

Chapter 6

Tables 5.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor where you want to insert the table, press Enter, then select table (wizard).

Select Simple.

Enter the number of rows and columns.

Click Insert.

Enter content in all table cells.

In Oxygen from the OAK Foundation menu, select Check In.

Insert tables of options and descriptions in tasks (choicetable) You can create a two-column, choice table in tasks for tabular content that doesn't require a title, description, or heading row; for example, available options and their descriptions. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

In a task topic, place the cursor where you want to insert the table, press Enter, then select choicetable (wizard).

Enter the number of rows.

Click Insert.

Enter content in all table cells.

In Oxygen from the OAK Foundation menu, select Check In.

Add columns or rows to tables You can add or delete columns and rows to tables. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

July 31, 2025 Page 31 of 38

Chapter 6

Tables Steps 1.

To add a column: a.

Place the cursor in the column next to where you want to insert a new column.

From the DITA menu, select Table.

Select Insert Column Above or Insert Column Below.

To add multiple columns: a.

Place the cursor in the column next to where you want to insert a new column.

From the DITA menu, select Table.

Select Insert Columns.

Enter the number of rows to add.

Select whether to add the row above or below the current row.

To delete a column: a.

Place the cursor in the column you want to delete.

From the DITA menu, select Table.

Select Delete Columns.

To add a row: a.

Place the cursor in the row next to where you want to insert a new row.

From the DITA menu, select Table.

Select Insert Row Above or Insert Row Below.

To add multiple rows: a.

Place the cursor in the row next to where you want to insert a new row.

From the DITA menu, select Table.

Select Insert Rows.

Enter the number of rows to add.

Select whether to add the row above or below the current row.

To delete a row: a.

Place the cursor in the row you want to delete.

From the DITA menu, select Table.

Select Delete Rows.

In Oxygen from the OAK Foundation menu, select Check In.

Change the width of columns in tables (table) By default, table columns are set to equal widths. You can change the column widths when needed for readability. If there is content in table cells that includes non-breaking characters like underscores (_), keeping those strings on the same line overrides the column width. Before you begin 1.

Open the publication.

July 31, 2025 Page 32 of 38

Chapter 6

Tables 2.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Under the <table> element, expand colspecs.

In width for each column, enter a value as a percentage or in inches. Avoid resizing columns by dragging the column dividers; enter specific values in the column specifications instead.

•

Enter a percentage for each column totaling 100%. For example, enter "25%" in columns 1 and 2 and "50%" in column 3 for a total of 100%.

•

Enter a value in inches for each column totaling 5.33 inches or 6.4 inches for a wide table. For example, enter "1.33in" in columns 1 and 2 and "2.67in" in column 3 for a total of 5.33 inches.

In Oxygen from the OAK Foundation menu, select Check In.

Change the width of columns in tables (simpletable, choicetable) By default, table columns are set to equal widths. You can change the column widths when needed for readability. If there is content in table cells that includes non-breaking characters like underscores (_), keeping those strings on the same line overrides the column width. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Right-click the <simpletable> or <choicetable> element, then select Edit Attributes.

In Name, enter "relcolwidth".

In Value, enter a value as a percentage or in inches for each column separated by spaces. Avoid resizing columns by dragging the column dividers; enter specific values in the column specifications instead.

•

Enter a percentage for each column totaling 100%. For example, enter "25% 25% 50%" for a total of 100%. These values set columns 1 and 2 to 25% and column 3 to 50%.

•

Enter a value in inches for each column totaling 5.33 inches or 6.4 inches for a wide table. For example, enter "1.33in 1.33in 2.67in" for a total of 5.33 inches. These values set columns 1 and 2 to 1.33in and column 3 to 2.67in.

In Oxygen from the OAK Foundation menu, select Check In.

July 31, 2025 Page 33 of 38

Chapter 6

Tables

Align tables to the page margin in PDF output You can set tables to start at the page margin instead of being indented under the body text in the PDF output. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Right-click the table element, then select Edit Attributes.

In Name, enter pgwide.

In Value, enter 1.

Click OK. Here's a table set to the page margin: <table frame="topbot" rowsep="1" colsep="0" pgwide="1">

In Oxygen from the OAK Foundation menu, select Check In.

Add a heading row to tables If the table header in a table is missing (for example, after you copy and paste a table from an HTML page), then change the first row to a table header. For accessibility, a table header is required for informal and formal tables. Don't add a header row to a simple table or a choice table. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Place the cursor in the row you want to make the heading row.

From the DITA menu, select Table, Table Properties.

On the Row tab, click Header under Row type.

In Oxygen from the OAK Foundation menu, select Check In.

July 31, 2025 Page 34 of 38

Chapter 6

Task steps

Task steps Typically tasks are made up of multiple steps that must be completed in sequence. For tasks with a single step or steps that can be completed in any order different step elements are available. You can also use paragraphs to describe task steps as needed.

Insert numbered steps in a task (steps) For tasks made up of multiple steps that must be completed in sequence, use the <steps> element. For sequential substeps, use a <substeps> element. To show different actions depending on the outcome of a step, use a <choices> element. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Insert the <steps> element before the closing <taskbody> element.

Under the <steps> element, insert a <step> element for each step in the task. Here's a code snippet of multiple, numbered task steps: <taskbody> <steps> <step> <cmd>Order and number the steps.</cmd> </step> <step> <cmd>Make each step short.</cmd> </step> <step> <cmd>Write each step as a complete sentence in the imperative mood.</cmd> </step> <step> <cmd>Write meaningful steps.</cmd> </step> <step> <cmd>Use branching of steps appropriately.</cmd> </step> </steps> </taskbody>

Insert the <substeps> element as needed before the closing <step> element.

Under the <substeps> element, insert a <substep> element for each substep.

July 31, 2025 Page 35 of 38

Chapter 6

Task steps Here's a code snippet of sequential substeps under a task step: <step> <cmd>Order and number the steps.</cmd> <substeps> <substep> <cmd>Present information in a logical order.</cmd> </substep> <substep> <cmd>Use letters for sequential substeps.</cmd> </substep> <substep> </substeps> 5.

Insert the <choices> element as needed before the closing <step> element.

Under the <choices> element, insert a <choice> element for each option. Here's a code snippet of a series of options under a task step: <step> <cmd>Use branching of steps appropriately.</cmd> <choices> <choice>Use branching if the procedure is the same for many cases and differs only at one or two steps. </choice> <choice>Indicate the branching condition in the main step text, not by using the word <i>or</i>. </choice> <choice>If the branching condition applies to most or all of the procedure, then use two different procedures. </choice> <choice>If a particular condition requires a substitution in most of the steps in the procedure, then provide that information in a note. </choice> <choice>If a step is optional, then do not use branching. </choice> <choice>If a user must know certain information to determine which branch to follow, then include the process by which the user can find out that information. </choice> </choices>

In Oxygen from the OAK Foundation menu, select Check In.

Insert task steps as a bulleted list (steps-unordered) You can use a bulleted list with one or more list items to describe single-step tasks or tasks with unordered steps. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

July 31, 2025 Page 36 of 38

Chapter 6

Task steps 6.

Open and check out the topic in the Editor.

•

Steps

•

Delete the <steps> element, then insert the <steps-unordered> element. Here's a code snippet of a task with a single step: <taskbody> <steps-unordered> <step> <cmd>Delete the <steps> element, then insert the <steps-unordered> element. </cmd> </step> </steps-unordered> </taskbody> Here's a code snippet of a task with unordered steps: <taskbody> <steps-unordered> <step> <cmd>In <ph conkeyref="GUID-9B95EC97-F9D9-4424-8D91-F4383F756B84/OXYGEN"/>, check out a task topic or create one using a Document Engineering template. </cmd> </step> <step> <cmd>Delete the <steps> element, then insert the <steps-unordered> element.</cmd> </step> <step> </steps-unordered> </taskbody>

•

In Oxygen from the OAK Foundation menu, select Check In.

Insert task steps as a paragraph (steps-informal) You can use a single paragraph to describe one or more task steps. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Delete the <steps> element, then insert the <steps-informal> element. In Oxygen, select Check In from the OAK Foundation menu. Here's a code snippet of a multiple steps in a paragraph: <taskbody> <steps-informal> <p>In <ph conkeyref="GUID-9B95EC97-F9D9-4424-8D91-F4383F756B84/OXYGEN"/>, create or open a task topic using a Document Engineering template. Delete the <steps> element, then insert the <steps-informal> element.</p>

July 31, 2025 Page 37 of 38

Chapter 6

Task steps </steps-informal> </taskbody>

July 31, 2025 Page 38 of 38

7 Reusing content Use content references, variables, and conditions to reuse content for different use cases. You can also reuse a topic in the same publication.

Insert content references for content reuse Define shared content in a conref library topic using an element ID, add the conref library as a resource, then insert the content reference in the topic.

Create conref library topics Create a separate conref library topic for different types of content, then set descriptive IDs on the elements you want to reuse. When creating content, you must use a Document Engineering template, which assigns a GUID needed to add files to OAK Foundation. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Select the conref library template that best matches your content under Topics/Library Topics.

Enter a descriptive name in Title (such as, "Library for Task Steps in Database Products" or "Library of Notes for use in Database Installation Guides"), then click Next.

Go to the folder where you want to save the library topic.

Select Check out and open, then click Create. The topic opens in Oxygen.

Enter the shared content in the appropriate elements and assign literal IDs to them. Here's an example code snippet for a library with task steps: <step id="step-1-logon"><cmd>Log in to the database console.</cmd></step> Here's an example code snippet for a library with notes: <note id="warning-logon" type="warning">You must have administrator privileges to log in to the console.</note>

In Oxygen from the OAK Foundation menu, select Check In. Enter a meaningful comment. The selected content is checked in.

Add a conref library topic as a resource Before you can reference content in a conref library topic, the library must be added to the root map of your publication as a resource file. Before you begin 1.

Open the publication.

July 31, 2025 Page 1 of 11

Chapter 7

Insert content references for content reuse 2.

Check out the root map and open it in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager under backmatter at the bottom of the root map, right-click Resources, then under Append Child, select Topic Reference.

Click

Browse, select a library topic, then click Insert.

The library topic is added to the Resources group. Here's a code snippet of a conref library inserted as a resource in a root map: <topicgroup processing-role="resource-only"> <topicmeta> <navtitle>Resources</navtitle> </topicmeta> <topicref keyref="GUID" format="dita"> <topicmeta> <navtitle>Library for Task Steps in Database Products</navtitle> </topicmeta> </topicref> </topicgroup> 3.

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the Check In.

root map, then under

OAK Foundation, select

Insert a content reference Use content references to insert content from a conref library into a topic. Content references are inserted using the GUID of the conref library and the element ID defined in the library. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

In Oxygen, right-click where you want to insert the content reference, then under the DITA menu, select Reuse Content .

Select Key, then click the Key icon.

Select the conref library.

Select the target ID corresponding to the content reference text to be inserted.

In Reference type, select conkeyref.

Click Insert and close.

July 31, 2025 Page 2 of 11

Chapter 7

Insert variables for content reuse The content is inserted as a content key reference using the GUID of the conref library topic and the element ID. Here's a code snippet of a content reference: <step conkeyref="GUID/step-1-logon"> <cmd/> </step> 7.

In Oxygen from the OAK Foundation menu, select Check In.

Insert variables for content reuse Create a set of variable libraries using the same library key and element ID, add the desired variable library as a resource using its key definition, then insert variables in topics. To use different variable text in a publication, swap the variable library being referenced as a resource in the root map.

Create a set of variable library topics Create variable libraries in sets with a separate library for each version of the variable text using the same library key and element ID for each variable. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Select Library of Variables under Topics/Library Topics/Variable Libraries.

In Title, enter a consistent and descriptive name for each variable library topic in a set (for example, "Library of Operating System Variables for Windows" and "Library of Operating System Variables for Linux"), then click Next.

Go to the folder where you want to save the library topic.

Select Check out and open, then click Create. The topic opens in Oxygen.

Replace the content="var_LIBRARY_KEY_NAME" attribute value with the key name for the variable library set; for example, content="var_os". Always begin key names with "var_".

Enter the shared content in <ph> elements and assign literal IDs to them. Here's an example code snippet for a library with operating system variables: <ph id="os">Windows</ph>

In Oxygen from the OAK Foundation menu, select Check In. Enter a meaningful comment. The selected content is checked in.

Repeat for every library in the set.

Add a variable library topic as a resource Before you can reference content in a variable library topic, the library must be added to the root map of your publication as a resource file, then the library must be assigned the key name defined in the variable library topic. Before you begin 1.

Open the publication.

Check out the root map and open it in DITA Maps Manager

July 31, 2025 Page 3 of 11

Chapter 7

Insert variables for content reuse 3.

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager under backmatter at the bottom of the root map, right-click Resources, then under Append Child, select Topic Reference.

Browse to a library topic or enter its GUID in Keyref, then click Insert. The library topic is added to the Resources group.

Set the key name for the variable library topic: a.

In DITA Maps Manager, right-click the variable library you just inserted, then under Define keys. Insert, select

Enter the library key name; for example, var_os in Key, then click Save.

The key name appears at the end of the variable library in the Resources group; for example, "{var_os}" Here's a code snippet of a variable library inserted as a resource in a root map: <topicgroup processing-role="resource-only"> <topicmeta> <navtitle>Resources</navtitle> </topicmeta> <topicref keyref="GUID" format="dita" keys="var_os"> <topicmeta> <navtitle>Library of Operating System Variables for Windows</navtitle> </topicmeta> </topicref> </topicgroup> 4.

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the root map, then under the menu, select Check In.

OAK Foundation

Insert a variable Use variables to insert content from a variable library into a topic. Insert a variable into a topic using the library key and element ID defined in the variable library. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

In Oxygen, place the cursor where you want to insert the variable, then under the DITA menu, select Reuse Content.

Select Key, then click the Key icon.

July 31, 2025 Page 4 of 11

Chapter 7

Control which conditions to include in a publication 3.

Type "var_" to filter keys to variable libraries that are resources in the root map, then select the desired library key name.

Select the target ID corresponding to the variable text to be inserted.

In Reference type, select conkeyref.

Click Insert and close. The variable is inserted as a content key reference using the library key name and element ID. <ph conkeyref="var_os/os_name"/>

In Oxygen from the OAK Foundation menu, select Check In.

Control which conditions to include in a publication Create a DITAVAL file to define which conditions to include in a publication, associate a DITAVAL file with a publication, or remove a DITAVAL file from a publication as needed.

Define conditions for publications Create a DITAVAL file using the Conditions template to define the conditions you want to include in the publication. If your publication doesn't include conditional text, you don't need to create a DITAVAL file. 1.

In Oxygen from the OAK Foundation menu, select Create New.

Select the Conditions template.

Enter a descriptive name in Title, then click Next.

Go to the folder where you want to save the DITAVAL file.

Select Check out and open, then select Create. The topic opens in Oxygen in Text mode.

For the condition name and value that you want to show or hide, set the action attribute to include or exclude, respectively.

In Oxygen from the OAK Foundation menu, select Check In.

Apply conditional settings to a publication Apply conditional settings to a publication by associating a DITAVAL file to the publication. You can use the same DITAVAL file for multiple publications. 1.

In the Workspace, right-click the publication that you to apply conditional settings to, then select Properties.

On the Conditions tab, click Browse, then select the DITAVAL file that contains the needed conditional settings.

In DITAVAL Version, select a different version of the DITAVAL file as needed.

Click Save.

July 31, 2025 Page 5 of 11

Chapter 7

Conditionalize content

Remove conditional settings from a publication Remove conditional settings from a publication by removing the associated DITAVAL file. 1.

In the Workspace, right-click the publication that you want to remove conditional settings from, then select Properties.

On the Conditions tab, click Clear.

Click Save.

Conditionalize content By setting conditional attributes on content, you can select the conditionalized topics, maps, or elements to include in different publications.

Conditionalize an entire topic or submap Conditionalize a topic or submap by setting conditions on a topic or map reference. Before you begin 1.

Open the publication.

Check out the root map as needed and open it in DITA Maps Manager.

Set the map context to <Current map>.

If used, check out the submap as needed and open it in DITA Maps Manager.

Set the map context to the named root map.

Steps 1.

Open the map with the topic or submap that you want to conditionalize.

Right-click the topic or submap reference that you want to conditionalize, then select Edit Attributes.

In Name, select the condition-<name> attribute such as condition-platform. The condition attribute is not valid.

In Value, select the condition value, such as linux. To apply multiple values, type the values separated by spaces, such as linux windows. The XML code for a condition is inserted. Here's a code snippet showing a condition on a topic reference: <topicref keyref="GUID" format="dita" condition-platform="linux windows"> <topicmeta> <navtitle>Server hardware requirements</navtitle> </topicmeta> </topicref>

Press Ctrl+S to save your changes.

In Oxygen from the OAK Foundation menu, select Check In.

July 31, 2025 Page 6 of 11

Chapter 7

Conditionalize content

Conditionalize content within a topic Apply a condition to an XML element in a topic by selecting a condition attribute and value. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Right-click the element that you want to conditionalize, then select Edit Attributes.

In Name, select the condition-<name> attribute such as condition-platform. The condition attribute is not valid.

In Value, select the condition value, such as linux. To apply multiple values, type the values separated by spaces, such as linux windows. Here's a code snippet showing compound, multiple, and simple conditions: <ol> <li condition-install_type="grid" condition-platform="linux">Runlevel - 3 or 5</li> <li condition-platform="linux windows">RAM – 256MB</li> <li condition-platform="windows">RAM - 2GB</li> <li>Server display card -- 1024x768</li> </ol>

In Oxygen from the OAK Foundation menu, select Check In.

Conditionalize a row in a table You may need to conditionalize a table row when using shared topics if the row contains information that doesn't apply to all the publications that share the topic. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open and check out the topic in the Editor.

Steps 1.

Right-click in the table row that you want to conditionalize, then select Edit Attributes.

In Name, select the condition-<name> attribute such as condition-platform. The condition attribute is not valid.

July 31, 2025 Page 7 of 11

Chapter 7

Control how conditions look when viewed in the Editor 3.

In Value, select the condition value, such as linux. To apply multiple values, type the values separated by spaces, such as linux windows. Here's a code snippet showing a condition on a table row: <tbody> <row condition-audience="administrator"> <entry>Array</entry> <entry>In</entry> <entry>Retrieves elements using specified indices, such as 0, 1, or index range such as 2:4, or a combination of both.</entry> </row>

In Oxygen from the OAK Foundation menu, select Check In.

Control how conditions look when viewed in the Editor You can control the appearance of conditional text in Oxygen.

Apply styles to conditional text when viewed in the Editor Condition colors and styles are an optional visual aid when you're authoring; they don't affect the output. 1.

In the Workspace, open any DITAVAL file.

In Oxygen, select Preferences from the Options menu.

Enter "profiling", then select Attributes and Condition Sets under Profiling/Conditional Text.

Click Import from DITAVAL, then select the DITAVAL file you opened from Local Storage (for example, C:\Users\Your Name\AppData\Local\OAKF\oakf_local_storage_prod.

Click Merge.

Select Colors and Styles under Profiling/Conditional Text.

Select the condition attribute that you want to style, click Edit, then select the styles.

July 31, 2025 Page 8 of 11

Chapter 7

Control how conditions look when viewed in the Editor

To apply a style to conditions without one, click Automatic styling.

Content with the associated conditions use the styles you defined.

July 31, 2025 Page 9 of 11

Chapter 7

Reuse topics in a publication

Show conditional text styles or attributes in the Editor You can choose to show or hide conditional text styles or condition attributes in the Editor. 1.

In Oxygen, select Profiling/Conditional Text from the DITA Maps menu.

To show conditional text styles, select Show Profiling Colors and Styles.

To show condition attributes, select Show Profiling Attributes.

Reuse topics in a publication You can reuse entire topics by referencing them in maps. Before you begin 1.

Open the publication.

Check out the root map as needed and open it in DITA Maps Manager.

Set the map context to <Current map>.

July 31, 2025 Page 10 of 11

Chapter 7

Reuse topics in a publication 4.

If used, check out the submap as needed and open it in DITA Maps Manager.

Set the map context to the named root map.

Steps 1.

In DITA Maps Manager, right-click where you want to insert the topic, then under Append Child, Insert Before, or Insert After, select Topic Reference.

Browse to the a topic or enter its GUID in Keyref, then click Insert. The XML code for a topic reference is inserted. Here's a code snippet of a topic reference to a topic being reused in a different publication: <topicref keyref="GUID" format="dita"> <topicmeta> <navtitle>Reuse topics in publications</navtitle> </topicmeta> </topicref>

If the topic being reused in the same publication, set the copy-to attribute: a.

On the Attributes tab, copy the GUID from the keyref attribute.

Paste the GUID in the copy-to attribute, append a descriptor to it, then add the .DITA extension; for example, reuse-GUID-D955D8EA-BCC3-4DD4-B131-F41F12A0B19D.dita. The XML code for a topic reference is inserted. Here's a code snippet of a topic reference to a topic being reused in the same publication: <topicref keyref="GUID-D955D8EA-BCC3-4DD4-B131-F41F12A0B19D" copy-to="reuse-GUIDD955D8EA-BCC3-4DD4-B131-F41F12A0B19D.dita" format="dita"> <topicmeta> <navtitle>Reuse topics in publications</navtitle> </topicmeta> </topicref>

Press Ctrl+S to save your changes.

In DITA Maps Manager, right-click the root map or submap, then under the Foundation menu, select Check In.

OAK

July 31, 2025 Page 11 of 11

8 Versioning content & managing the publication baseline Create new version or branches of objects as needed then identify which versions or branches should be used in a publication via the publication baseline. Change the workflow status of any version of any object to track its release readiness.

Change the workflow status of content Use workflow statuses to track the readiness of content for release. Typically, you will want to update the status of the baseline version, but you can update the status of the latest or any previous version. When you change the status of multiple content objects, only those with the same starting status are updated.

Change the workflow status of maps, topics, images, and other content You can change the workflow status of any number of root maps, submaps, topics, library topics, DITAVAL files, images, and image description topics with the same starting status at the same time. 1.

To change the baseline version: a.

In Oxygen from the OAK Foundation menu, select Open Workspace.

In the Workspace, right-click the publication, then select Manage Baseline.

Go to Step 4.

To change the latest version: a.

In Oxygen from the OAK Foundation menu, select Open Workspace.

Go to Step 4.

To change a previous version: a.

From Manage Baseline or the Workspace, right-click the content object, then select Manage Versions.

Go to Step 4.

Right-click the desired content objects, then select Change Status.

If the objects you selected are in multiple states, select the starting status you want to change in the Selected Status.

Select the status you want to update the content with in New Status.

Change the workflow status of a publication You can change the workflow status of a publication. 1.

To change the latest version:

July 31, 2025 Page 1 of 5

Chapter 8

Create a version or branch of content

In Oxygen from the OAK Foundation menu, select Open Workspace.

Go to Step 3.

To change a previous version: a.

In Oxygen from the OAK Foundation menu, select Open Workspace.

Right-click the publication, then select Manage Versions.

Go to Step 3.

Right-click the publication, then select Change Status.

Select the status you want to update the publications with in New Status.

Create a version or branch of content Versions and branches not only allow you to track changes made to content over time, but they also enable you to manage the current and previous states of content independently. You can version publications, root maps, submaps, topics, library topics, DITAVAL files, images, and image description topics regardless of their workflow state. You can check out content (excluding publications) when you create the new version.

Create a version of a publication You can a create a version or branch of a publication. 1.

In the Workspace, right-click the publication, then... a.

To start from the latest version, select Create Version.

To start from a previous version, select Manage Versions, right-click the desired version, then select Create Version.

Select New latest version or New branch.

Click Create.

Create a version of a root map Create a version or branch of a root map. To associate the new version with a publication, you need to select that version in the properties of the publication. 1.

In the Workspace, right-click the root map, then... a.

To start from the latest version, select Create Version.

To start from a previous version, select Manage Versions, right-click the desired version, then select Create Version.

Select New latest version or New branch.

To immediately check out the new version, select Check out and open.

Click Create.

Create a version of a submap, topic, image, or other content You can create a version or branch of a submap, topic, library topic, image, or image description topic. Depending on where you create the version, you can apply it immediately to the publication baseline or apply it to the baseline separately.

July 31, 2025 Page 2 of 5

Chapter 8

Change the root map associated with a publication 1.

Select the version you want to start from: a.

To start from the baseline version, go to the Workspace, right-click the publication, then select Manage Baseline.

To start from the latest version, go to the Workspace.

To start from a previous version, go to the Workspace or Manage Baseline, right-click the content object, then select Manage Versions.

Right-click the desired object, then select Create Version.

Select New latest version or New branch.

To immediately check out the new version, select Check out and open.

Click Create.

If you created a version from Manage Baseline, click Save to apply the new version to the publication baseline.

Create a version of a DITAVAL file Create a version or branch of a DITAVAL file. To associate the new version with a publication, you need to select that version in the properties of the publication. 1.

In the Workspace, right-click the DITAVAL file, then select Create Version.

Select New latest version or New branch.

To immediately check out the new version, select Check out and open.

Click Create.

In the Workspace, right-click the publication, then select Properties.

On the Root Map tab, select the root map:

•

To select a different version of the root map, select the appropriate version number .

•

To select a different root map, click version is selected.

Browse to select it. By default, the latest

Click Save.

Change the version of content associated with a publication You can view and change which version of individual submaps, topics, library topics, images, and image description topics are used in a publication. The Latest column indicates which objects have newer versions available for selection. Sorting objects by this column helps you identify which object versions might need updating. 1.

In the Workspace, right-click a publication, then select Manage Baseline.

In the Version column, click the version number and select a version.

Click Save, then close Manage Baseline.

July 31, 2025 Page 3 of 5

Chapter 8

Change the DITAVAL file associated with a publication The newly selected object version is copied locally and available in the root map.

Change the DITAVAL file associated with a publication When you version the DITAVAL file associated with a publication, you need to select that version in the properties of the publication; you cannot change the DITAVAL version in the publication baseline. You can associate a different DITAVAL file for a publication in the same way. 1.

In the Workspace, right-click the publication, then select Properties.

Click the Conditions tab.

To select a different version of the DITAVAL file, select the appropriate version number.

To select a different DITAVAL file, click Browse to select it. By default, the latest version is selected.

Click Save.

In the Workspace, right-click the publication, then select Manage Baseline.

Click the

Sync with Map icon.

The baseline is updated with all objects being referenced in the root map. Related Topics •

How and when the publication baseline is updated

Automatically complete the publication baseline You can automatically complete the publication baseline by applying a version type (latest available or latest released) to each submap, topic, image, or library topic individually or to all objects in the baseline. 1.

In the Workspace, right-click a publication, then select Manage Baseline.

Click the Autocomplete Baseline icon. .

Select which type of version to apply to the baseline.

•

Latest available versions – Selects the highest available version or branch of all objects in the baseline regardless of their workflow status.

•

Latest released versions – Selects the highest available version or branch of all objects that are in a Released status in the baseline.

To replace an individual object, click Replace. To replace all objects, select Apply to all remaining objects, then click Replace.

July 31, 2025 Page 4 of 5

Chapter 8

Compare different versions or revisions of a content object 5.

Click Save, then close Manage Baseline.

The replaced versions are copied locally and available in the root map.

Compare different versions or revisions of a content object You can compare any version or revision of the same object against another version or revision of that object or compare different objects against each other. 1.

To compare two versions of an object, open each version: a.

In the Workspace, right-click the content that you want to compare, then select Manage Versions.

Right-click each version you want to compare, then select Open.

To compare two revisions of the same version of an object, open each revision: a.

In the Workspace, right-click the content that you want to compare, then select Manage Versions.

Select the version you want to compare, then select View Revisions.

Right-click each revision you want to compare, then select Open.

In Oxygen from the Tools menu, select Comparison Tools, then select Compare Files.

Open the source version or revision in the left-side and the target version of revision in the right-side.

From the Compare menu, select Perform Files Differencing.

View and restore revisions OAK Foundation creates a revision each time you check in a content object or update properties for a publication. When you work with a version of any object, you are always working with the latest revision by default, but you can view or restore earlier revisions. 1.

In the Workspace, right-click the desired content object, then select View Revisions.

Right-click the revision that you want to restore, then select Restore Revision, then click OK. A new revision number is created with a check in comment that indicates the revision that was restored.

July 31, 2025 Page 5 of 5

9 Searching for content in OAK Foundation Search for any object in the OAK Foundation database using the Search tab in the OAK Foundation Workspace. Apart from search, you can also find objects via the Manage Baseline and Where Used features.

Find the DITAVAL file associated with a publication View the DITAVAL file associated with a publication by viewing the publication properties dialog box. 1.

In the Workspace, right-click the publication that you want to view the DITAVAL file for then select Properties. The DITAVAL file and file version is shown in the Pub Details tab.

To locate the DITAVAL file in repository, you can copy the GUID of the DITAVAL file then search for it in the Workspace.

Find the root map associated with a publication You can quickly locate the root map associated with a publication. You can view the properties of the root map or perform relevant actions it, such as opening, checking out, creating a new version, or changing workflow status. 1.

In the Workspace, right-click the publication, then select Locate Root Map. The version of the root map associated with the publication is highlighted in Manage Versions.

To view the location or GUID of the root map, right-click any version, then select Properties.

To take an action on the root map, right-click the desired version, then select the appropriate command from the context menu.

Find where objects are located in OAK Foundation You can locate the folder where content is stored when you are working with maps or topics, or in the baseline.

Find the repository location of maps open in DITA Maps Manager You can quickly find where content objects referenced in a root map or submap are stored in OAK Foundation. 1.

In DITA Maps Manager, right-click the content object, then under menu, select Locate Object.

OAK Foundation

July 31, 2025 Page 1 of 4

Chapter 9

Find which publications use specific maps, topics, and images The latest version of the object is highlighted in the Workspace. 2.

To view a different version, right-click the object, then select Manage Versions.

Find the repository location of content open in Oxygen You can quickly find where content objects open in the Editor are stored in OAK Foundation. 1.

In Oxygen under

OAK Foundation menu, select Locate Object.

The latest version of the object is highlighted in the Workspace. 2.

To view a different version, right-click the object, then select Manage Versions.

Find the repository location of content in the publication baseline You can quickly find where content objects referenced in Manage Baseline are stored in OAK Foundation. 1.

In the Workspace, right-click the publication, then select Manage Baseline.

Right-click the content object, then under Location.

OAK Foundation menu, select Go to

The latest version of the object is highlighted in the Workspace. 3.

To view a different version, right-click the object, then select Manage Versions.

Find which publications use specific maps, topics, and images You can view which versions of root maps, submaps, topics, library topics, images, and image description topics are referenced by specific versions of publications. The Where Used tab uses publication baselines to determine where objects are being used. 1.

In the Workspace, right-click the object that you want to view publication dependencies for, then select Properties.

Click the Where Used tab. A list of all publications that use the object is shown.

To find a publication, right-click it and select Go to Location. The latest version of the publication is highlighted in the Workspace.

Search for content by metadata Use predefined or custom metadata to find content in OAK Foundation. You can take a variety of actions on the objects returned by search. 1.

In the Workspace, click the Search tab.

To see all available versions in the search results, clear Show latest versions only.

To enable case-sensitive search, select Case sensitive.

Select the criteria you want to search against: Option

Description

Object Title

Enter a full or partial title.

July 31, 2025 Page 2 of 4

Chapter 9

Search for content by metadata Option

Description

GUID

Enter a full or partial GUID or PGUID string; for example, "GUID-4399C95E-4C7D-490E-9165-F40997A00AC9" or "4399C95E".

Description

Enter a full or partial object description.

HTML File Name

Enter a full or partial file name.

DITA Type

Select a DITA or other object type: •

Bookmap – Has a <Bookmap> map element.

•

Concept – Has a <concept> topic element.

•

Filter – DITAVAL Conditions files.

•

Glossentry – Has a <glossentry> topic element.

•

Map – Has a <DITA Map> map element

•

Publication – Publication content object

•

Reference – Has a <reference> topic element.

•

Subject Scheme – Subject scheme maps.

•

Task – Has a <task> topic element.

•

Topic – Has a <topic> topic element.

Note Files that have been refactored to other map or topic types are still tagged with the original DITA type.

Template

Select the name of a DocEng template.

File Type

Enter a supported file extension.

Release Label

Enter a full or partial string of your custom metadata.

Changes

Enter a full or partial string of your custom metadata.

Status

Enter a workflow status.

Last Modified On

Enter the date that the content was most recently updated in YYYYMM-DD format; for example, "2025-01-09".

Last Modified By

Enter the email address of the person who most recently updated the content; for example, "DEE.BECK@ORACLE.COM".

Locked By

Enter the email address of the person who has the content checked out; for example, "DEE.BECK@ORACLE.COM".

Keywords

Enter a full or partial string of your custom metadata.

Feature Number Enter a full or partial string of your custom metadata. Bug Number 5.

Enter your custom metadata.

Click Search.

July 31, 2025 Page 3 of 4

Chapter 9

Search for objects checked out by you

Search for objects checked out by you Search the OAK Foundation database using the Locked By metadata search field and your email address to find all objects that are currently checked out by you. 1.

In the Workspace, click the Search tab.

Enter your partial or full email address in upper case and select Locked By from the Metadata Type list.

Clear Show latest versions only to view all object versions checked out by you.

Click Search.

View all available versions of a content object The Workspace shows the latest available version of content objects, but you can also view a list of all available versions using Manage Versions. 1.

In the Workspace, right-click an object and select Manage Versions.

Right-click the version you want, then select the desired action.

View all content in a publication Find all content in a publication by viewing its baseline. The baseline lists the version of each submap, topic, image, and library topic referenced by the root map of a publication. Use the baseline to ensure that the correct set and version of content are used in the publication.

•

In the Workspace, right-click a publication and select Manage Baseline. The Manage Baseline window opens to show all objects in the publication. The root map is indicated by a yellow icon to set it apart from other objects.

View the audit history of content You can view a sequential record of the changes and actions made to any version of content. 1.

To view a previous version of content, right-click the object from the Workspace or Manage Baseline, then select Manage Versions.

Right-click the version, then select View Revisions to see who changed the content and when.

July 31, 2025 Page 4 of 4

A Default preferences in Oxygen By default, the recommended preferences are set in Oxygen when you install the OAK Foundation add-ons. Commands

Option

Description

Add-ons

Enable automatic updates checking

Notifies you of updates to the OAK Foundation or other addons the next time you open Oxygen.

Editor / Edit Modes / Author Show XML comments

Displays XML comments in Author mode.

Tags display mode

Displays full tag names with attributes for block and inline elements in Author mode.

Display referenced content

Displays references like content references or variables in the content they reference.

Editor / Edit Modes / Author / Schema-Aware

Convert external content on Preserves certain styles and structure information when paste copying-and-pasting content from external sources in an attempt to keep the resulting document valid.

Editor / Edit Modes / Author / Serialization

Compatibility with other tools

Avoids breaking lines after starting or ending elements and doesn't indent elements. If you work with topics that were created in another editor or see extra spaces in a topic, the Do not break lines, do not indent option improves compatibility with content created in different editors.

Editor / Save

Automatically save the document every

Automatically saves your changes every 10 minutes.

Clear undo buffer on save

Allows changes made prior to saving the document to be undone, when deselected. We don't recommend selecting this option unless you frequently encounter out of memory errors when editing large documents.

Editor / Content Completion / Annotations

Show annotations in tooltip Hides tooltips that appear when you hover over elements and attributes in the Editor.

Editor / Document Validation

Enable automatic validation Automatically validates as you type and highlights errors or warning in the Editor.

Editor / Spell Check

Automatic spell check

Checks spelling as you type and highlights misspelled words in the Editor.

XML spell checking in

Checks spelling in Comments and Text only.

Options

Ignore acronyms, words with digits, and URLs during spell checking. Depending on your content and preferences, you might find ignoring or allowing other options helpful.

When opening a map

Always opens maps in DITA Maps Manager.

DITA / Maps

July 31, 2025 Appendix A-1 of A-1

B Frequently asked questions Frequently asked questions (FAQs) about OAK Foundation.

General OAK Foundation FAQs Frequently asked questions about OAK Foundation. What is OAK Foundation? Oracle Authoring Kit Foundation, or OAK Foundation, is our Next-Gen authoring and content management solution that integrated with other InfoDev applications. It's developed in-house using Oracle technologies, including Oracle XML database, for storing and managing content being published to Oracle Help Center. OAK Foundation is designed primarily for DITA XML files with Oxygen XML as the authoring tool, but it also supports other documentation source formats such as Markdown. It's designed for any UA team creating technical documentation, not just those using SDL today. Is OAK Foundation a 1-to-1 replacement for SDL? No, OAK Foundation is a new approach to managing information development—our intent is not to duplicate SDL functionality 1:1. It supports the same type of functions provided by modern content management systems, such as SDL, but with the flexibility to adapt to changing business and stakeholder needs without added third-party limitations and costs. What are the advantages of OAK Foundation over SDL? The initial driver for building OAK Foundation was to move away from dependency on an expensive external application that also imposed limits on when we could update and adopt new technology. Because OAK Foundation is developed in-house, we have much more control over how it evolves over time to meet stakeholder needs. Other advantages include: •

OAK Foundation development and deployment is not constrained by third-party vendor upgrades and release schedules

•

OAK Foundation enhancements and upgrades are fully controlled by DocEng

•

OAK Foundation integration with DocEng applications and components will be easier and more flexible

•

OAK Foundation is built using our own Oracle technologies and products such as Oracle Autonomous Database with XML, Java, JDBC, and Oracle Cloud services

•

Licensing, support, and maintenance feeds do not have to be paid to a third-party

What will happen to SDL? The SDL CCMS system will be decommissioned once all UA teams that use SDL are migrated to OAK Foundation. Currently this is expected to happen in early 2026. For on the latest OAK Foundation milestones and dates, see OAK Foundation Status. What is the benefit of OAK Foundation to UA teams? Being in control of OAK Foundation allows us to have more offerings for our user base:

July 31, 2025 Appendix B-1 of B-5

Appendix B

Migration FAQs •

Ability to move to DITA 1.3 whenever we're ready, which will allow UA teams to take advantage of features in current versions of DITA and the DITA Open Toolkit when creating and reusing content.

•

Ability to store Markdown in the same repository as DITA XML, making it easier to see connections and work towards one day combining those sources.

•

Ability to more easily support new publication types and metadata as content needs change.

How can I propose features that are not already in the OAK Foundation roadmap? If your team has special requirements, or you have special use cases that you would like the OAK Foundation team to consider, contact Mark Paterson so that we can understand your need and evaluate how they can be address. What version of DITA will be supported by OAK Foundation? OAK Foundation is designed to support any DITA version, however, because content coming from SDL is in DITA 1.2, that is the version that will be initially supported by OAK Foundation. DITA 1.3 support is on the OAK Foundation roadmap, and will be available in future releases of OAK Foundation. Updating to DITA 1.3 means also updating the DITA Open Toolkit used to build publications from DITA XML to HTML and PDF. What are the key features of OAK Foundation? For an overview of repository features, see OAK Foundation. For a list of roadmap features, see OAK Foundation Status. Can I try OAK Foundation before migrating to it? Teams can try out OAK Foundation by participating in our Try It program. By participating, you will have access to the latest OAK Foundation release as well as your own copy of a training publication that you can use for trying out the system. As part of the program, you will be required to complete OAK Foundation training. Once completed, you will have the opportunity to try out OAK Foundation using a copy of your actual content. For more information on participating, contact Mark Paterson. How do I submit a defect or enhancement request for OAK Foundation? Before submitting a defect, check that the issue isn't already listed on the OAK Foundation Known Issues page. If it's not listed, clone DPS-108795 - [TEMPLATE] OAKF defect ticket, then post a link to your ticket in the #infodev-oakf-helpdesk Slack channel. Before submitting a feature enhancement request, check that the feature isn't already listed as a roadmap feature on the OAK Foundation Status page. If it's not listed, clone DPS-123023 [TEMPLATE] OAK Foundation: <Describe Enhancement Request> then post a link to your ticket in the #infodev-oakf-helpdesk Slack channel. Will I need a software license for OAK Foundation? No, you do not need a software license to use OAK Foundation. However, you will need a license for the version of Oxygen that is currently supported by OAK Foundation. OAK Foundation is fully integrated with Oxygen, therefore, it is installed as an Oxygen add-on.

Migration FAQs Frequently asked questions related to migrating SDL content into OAK Foundation. Which teams will be migrated to OAK Foundation? During initial onboarding, the focus will be migrating DITA XML content from SDL to OAK Foundation. Teams using SDL will work with DocEng Support to decide which publications to migrate, with highest priority given to active and latest publications. To determine when your team should migrate to OAK Foundation, see Participate in Controlled Availability.

July 31, 2025 Appendix B-2 of B-5

Appendix B

Migration FAQs Teams with content not in SDL can also be migrated to OAK Foundation. However, the request to migrate this content will be reviewed by the InfoDev team on a case-by-case basis. Each request is evaluated based on complexity of the content to be migrated as well as the urgency of the business need. For more information on migrating non-SDL content to OAK Foundation, contact Mark Paterson. Which publications can be migrated to OAK Foundation? For information on the types of publications that are eligible to be migrated, see Migrate SDL Content to OAK Foundation. What does the SDL migration process look like? At a high level: •

Migration will happen in groups, not as a single event.

•

Teams will identify active and/or latest publications to migrate.

•

Teams will perform pre-migration cleanup to ensure that publications are ready for migration.

•

Publications will be exported, processed, and imported into OAK Foundation by DocEng. As part of the migration process, XML conversion scripts is run on each publication to remove SDL-specific markup and replace them with standard DITA 1.2.

•

Teams will perform post-migration checks to ensure that publications have been successfully migrated. Depending on content complexity, additional post-migration cleanup may be required.

•

Teams will use OAK Foundation for all migrated publications going forward.

For more information, see Migrate SDL Content to OAK Foundation. How long does it take to prepare an SDL publication for migration? Before publications can be migrated from SDL into OAK Foundation, teams must perform a series of pre-migration tasks to ensure that their SDL publication is free of errors. The length of time it takes to prepare a publication for migration depends on the size and complexity of your publication. In general, as long as publications don't contain invalid DITA, condition, content reference, or variable issues, and has a baseline that is cleaned up, the premigration tasks involve just a cursory check of each tab in Publication Manager. Publications with errors or conflicts will require more effort to clean them up for migration, however, premigration tasks can be completed at any point in time (even if you're not migrating to OAK Foundation yet). For more information on what's involved in completing pre-migration tasks for OAK Foundation, see OAK Foundation - Pre-Migration Checklist. How do I validate that my SDL content has been properly migrated to OAK Foundation? After a publication has been migrated to OAK Foundation, teams must perform a series of post-migration tasks to ensure that no content errors were introduced during the migration process. For more information, see OAK Foundation - Post-Migration Validation Checklist. Will I be able to continue working in SDL after migration? Yes, you can still work in SDL after migrating to OAK Foundation. However, once a publication is migrated, all authoring and publishing of that publication must be done from OAK Foundation. For publications that haven't been migrated, you can continue to work on them in SDL up until they're migrated. When working in SDL, use Oxygen 17.1. When working in OAK Foundation, use Oxygen 27.0 Will SDL GUIDs be preserved during migration? References containing SDL GUIDs are refactored during the migration process, but actual GUID values will remain unchanged. This means that olinks will continue to work.

July 31, 2025 Appendix B-3 of B-5

Appendix B

Authoring and object management FAQs GUIDs for publications also remain unchanged but will be prepended with a "P" so that you can quickly find and identify publications in OAK Foundation by PGUID. Will conditions in my SDL publications be preserved during migration? Yes, conditions in SDL publications will be preserved but refactored from using the "ishcondition" attribute to using a DITA profiling attribute with conditional logic managed via DITAVAL files to confirm to DITA 1.2. Allowed condition names and values will continue to be centrally managed by InfoDev. How will conrefs and variables be handled during migration? DITA keys will be used to replace SDL variables. All variable references (Varrefs) are converted to conkeyrefs via a named key in OAK Foundation. Oxygen provides good support for variables management and keys that can be leveraged for OAK Foundation. Will comments in my content be preserved during migration? Yes, draft and XML comments are part of the DITA XML content itself, and will be preserved during migration. Are there any changes to how metadata is captured and/or used? In OAK Foundation, we've simplified the metadata that is captured and also relaxed constraints of the type of metadata that can be captured in some fields. Much of the metadata in SDL was not universally or consistently used, so in OAK Foundation, we've shifted to a more generic "keywords" model where teams can enter any metadata in a format of their choosing for searching purposes. Can I still make updates to legacy content in SDL after SDL has been decommissioned? Yes, DocEng Support will work with you and your team to ensure that your legacy content is updated as needed. This may involve migrating your publication so that you can work on it in OAK Foundation, editing your output files, or other method depending on size and complexity of changes. Who should I contact if I have more questions about migrating content to OAK Foundation? For questions on migrating SDL content to OAK Foundation, contact Danny Yip. For questions on migrating content not in SDL, contact Mark Paterson.

Authoring and object management FAQs Frequently asked questions related to authoring content and managing objects using OAK Foundation. Do I need to be connected to VPN to use OAK Foundation? Yes, OAK Foundation uses network resources and requires a VPN connection. You can check out content, work on it offline, then check in your changes when you are connected again. How are objects organized in OAK Foundation? Repository objects are organized by folders and displayed as a hierarchical structure. During migration from SDL, objects will be migrated to the same folder paths in OAK Foundation. Does OAK Foundation support the notion of publications? Yes, OAK Foundation supports the notion of publications. In OAK Foundation, publications are a special object type with which you associate a root map to define the contents of the publication. Metadata required for OHC publishing, such publication title, part number, DOCID, and publication base path, is also preserved in a publication object. When you open a

July 31, 2025 Appendix B-4 of B-5

Appendix B

Authoring and object management FAQs publication in OAK Foundation, you open its associated root map in Oxygen. To edit the metadata of a publication, you edit its properties. Will I be able to search for publications in OAK Foundation? In OAK Foundation, publication GUIDs begin with "PGUID", so the fastest way to find all publications is to search for objects with a GUID of "PGUID". You can also search for specific publications by searching by title, workflow status, release label, and/or other metadata. Will I be able to work with multiple publications at the same time? In OAK Foundation, you can open and work on different publications at the time. This includes entirely different publications and different versions or branches of the same publication. When multiple publications are open, each publication is displayed in a separate tab in DITA Maps Manager. Switch between the tabs as needed. Simultaneously working on publications that share the exact same root map isn't supported yet. For this use case, you'll have to work in each publication separately. Can multiple writers work on the same publication at the same time? Yes, multiple writers can work on the same publication at a time. Each writer will need to open the publication then check out the objects they need to edit. Objects can only be edited by one writer at a time. If someone else has the object checked out, you will need to wait until the object is checked in before you can check it out for editing. What's new with branching? In OAK Foundation, you can version or branch any object. This includes creating a new version from a branch and creating a new branch from an existing branch. Version numbers in OAK Foundation are whole numbers whereas branch numbers are restricted to a single decimal place (such as, 2.1). During migration from SDL, SDL branch numbers will be ported over as-is, but once they are in OAK Foundation, new branches will confirm to the OAK Foundation numbering convention. Are workflow statuses supported in OAK Foundation? Yes, you can use workflow status in OAK Foundation to manage your objects throughout the development lifecycle. When promoting to Production, objects need only be in the Completed state. Once a publication is released to production, all objects in the publication are automatically set to Released as part of the publishing pipeline. Apart from In Progress, Completed, and Released, OAK Foundation also supports the Inactive and Inactive-Released states so that you can indicate objects that should no longer be used. Can we directly query the OAK Foundation database? For example, to find the parent/ child relationship between objects? We don't allow direct queries of the database. However, we will have a Where Used type feature to identify object dependencies as described above. Over time we can add additional reporting as needs develop.

July 31, 2025 Appendix B-5 of B-5

C Schematron rules in Oxygen Schematron flags content that break specific business rules for different content types. Errors must be resolved before you can check in content. Rule No. Displayed

Business Rule and Reference

Rules Applies To

UA005(a1, a2, b)

In the Get Started topichead in a solution ditamap, all "Learn About..." submaps must be positioned first. More than one "Learn About" submap is allowed.

Solutions ditamaps

In solutions ditamaps, "Learn About..." submaps can only be placed in the Get Started topichead. UA007

In solutions, the titleelement for submaps and topics must use headline-style casing.

Solutions submaps and topics

Exception: Titles of long image descriptions that are of the general format "Description of the illustration <file-name>" UA009 (a, b)

The title elements in a ditamap must begin with imperative verb phrases, not gerunds. The title must begin with an approved imperative phrase.

Solutions ditamaps

UA011 (a, b, c, d)

A topic with title beginning with "About Required..." Solutions submaps must be in "Learn About…" submap, it must be of type concept only, the title may include any combination of the words "Roles", "Products", and "Services", and it cannot precede topics entitled "Architecture" or "Considerations for..." "About Required" topics cannot include unapproved words such as "Optional" instead of "Required,", or "Software" instead of "Services."

UA015 (a1, a2, a3, b)

In a solutions ditamap, if a submap contains an Solutions ditamaps "Explore More Solutions" topic, then that submap must be placed last in the ditamap unless a solution also contains a Download Code topichead, where "Explore More Solutions" is next to last, and "Download Code" is placed last.

UA016

An submap should not contain more than seven topics.

Solutions submaps

UA018 (a)

A topic cannot contain inline links or crossreferences, except within those topics entitled "Explore More", "Before You Begin", "About Required Services and Roles" (including variations), and "Download Code" topichead.

Solutions topics

A topic cannot can contain bare URLs. Exceptions include URLs within codeph and codeblock elements.

July 31, 2025 Appendix C-1 of C-2

Appendix C

Rule No. Displayed

Business Rule and Reference

Rules Applies To

UA027 (a, b)

In topics, the image element must not be included within a fig element.

Solutions topics

Exception: A wide image must be placed within a fig element, which must not have a title. UA028 (a)

Topics cannot contain formal tables.

UA037

A short desc element must not exceed 50 words in All topics length.

UA042 (a, b, c)

Table cells must contain readable text. Table cells must not be empty or contain the equivalent of blank space only.

All topics

UA043

Table cells in a column header must contain text. Column headers cannot be empty or contain the equivalent of blank space only.

All topics

UA044 (a)

Images must have either alt or longdescref but not both.

All topics

UA045 (a, b, c)

Tables must have header rows. Simple and choice tables must not have header rows.

All topics

UA047 (a, b, c)

A table must have a desc element, which must be between 6 and 180 characters in length, and cannot contain only spaces or punctuation.

All topics

UA048

Do not use the menu cascade element. The output All topics is not accessible.

UA076

Except in What's New publications, a topic cannot contain section elements.

UA085 (a, b)

A topic must not contain a link to an internal Oracle All topics domain inside an xref element or inside the text.

UA091(a, b)

An example must be informal, it cannot have a title, Solutions topics and cannot contain pre elements.

UA094

A solutions submap must not contain more than two levels of topics.

UA155

Use the table wizard to create an informal or All reference topics simple table. Don't use the properties element. The output isn't accessible.

Solutions topics

Solutions submaps

July 31, 2025 Appendix C-2 of C-2

D Troubleshooting You can resolve common issues during installation, authoring, or publishing.

Cannot download Oxygen If you have issues downloading the software, there some steps to follow to resolve the issue. If you have issues downloading the software, try the following: •

Clear the browser cache.

•

Use an incognito (Chrome) or private (Firefox) browser window.

•

Enable cookies or resolve browser issues. For detailed steps, see Uno Tips for Solving Common Errors.

Cannot find or run the Setup program If you have issues running or finding the Setup program, go to Troubleshooting in Uno and DSSM, click Troubleshooting, then follow the instructions in Software install completed but I can't find it on my machine. If the issue persists, contact software-compliance_ww@oracle.com

Could not connect to a license server If you see a "Could not connect to a license server on URL: http://den03fil.us.oracle.com:8092/ oXygenLicenseServlet/license-servlet User: user" message during the installation, you need an additional OIM entitlement 1.

Request the VPN SSO with Lab Access entitlement. For detailed steps, see How to request account/entitlement/role via OIM.

After the entitlement is approved, wait 30 minutes before trying again.

If you still see the message, disconnect and reconnect VPN, then try again.

Request access to OAK Foundation If you see a "Request Access to OAK Foundation" message when trying to open the OAK Foundation Workspace, you need to request the DOCENG_OAKF_USER entitlement from OIM. The DOCENG_OAKF_ADMIN entitlement is for internal support staff only. For detailed steps, see How to request account/entitlement/role via OIM.

July 31, 2025 Appendix D-1 of D-6

Appendix D

Validate and correct DITA files

Validate and correct DITA files Use Oxygen's validation features to ensure that topics and maps are well-formed and don't contain XML validation errors.

Open the publication.

Open the root map in DITA Maps Manager

Set the map context to <Current map>.

Steps 1.

In DITA Maps Manager, select the tab for the root map.

Press F5 to reload the map.

In Oxygen from the DITA Maps menu, select Validate and Check for Completeness.

Select Batch validate referenced DITA resources.

Select these checks:

•

Report multiple references to the same topic – If selected, finds where a topic is referenced multiple times in the root map without a unique copy-to attribute.

•

Check for duplicate topic IDs within the DITA map context – Finds any topics that have the same ID within the root map.

•

Report table layout problems – Finds issues within table elements; for example, if a row has fewer cells than columns.

•

Identify possible conflicts in profile attribute values – Finds conditions used in topics that are not defined in the DITAVAL file.

Click Check. Issues are returned in the Results pane.

Validate a topic or submap When you have a topic or submap open the Editor in Oxygen, Oxygen automatically validates it to ensure that DITA XML content is valid, well-formed, and conforms to Schematron rules. Before you begin 1.

Open the publication.

Open the root map in DITA Maps Manager.

Set the map context to <Current map>.

July 31, 2025 Appendix D-2 of D-6

Appendix D

Validate and correct DITA files 4.

If used, open the submap in DITA Maps Manager.

Set the map context to the named root map.

Open the submap or topic in the Editor as needed.

Steps 1.

From the DITA Maps menu, select Validate. A list of all validation errors and warnings appear in the Results pane.

Correct each issue, then validate the topic or map again.

Correct duplicate ID errors If you created duplicate IDs when you copied and pasted elements, correct them by finding the problematic elements and regenerating new IDs for them. 1.

Click the error message to highlight the location of the element with the duplicate ID. If the location of the element isn't highlighted when you click the error message, then click the Text tab at the bottom of the page, and try again.

Right-click the element, select Regenerate ID, then confirm the action. A new ID is generated for the element, resolving the error.

Correct XML validation errors If you create an invalid structure (typically by pasting an element where it doesn't belong), then the Xerces XML parser displays a validation error. 1.

Click the error message to highlight the location of the error in the topic. If the location of the error isn't highlighted when you click the error message, then click the Text tab at the bottom of the page, and try again.

Use the "must match" information in the error message to insert the correct XML element.

Correct missing key definition warnings Oxygen relies on DITA Maps Manager to resolve key references, and reports a missing key definition error if the correct root map isn't available. Before you begin 1.

Open the publication.

Check out the root map as needed and open it in DITA Maps Manager.

Set the map context to <Current map>.

If used, check out the submap as needed and open it in DITA Maps Manager.

Set the map context to the named root map.

Use the "must match" information in the error message to insert the correct XML element.

July 31, 2025 Appendix D-3 of D-6

Appendix D

Tools & Software not appearing in Uno

Correct Schematron warnings Schematron adds validation rules that are based on accessibility requirements, security requirements, and writing standards. A quick fix guides you through the steps to fix an error. 1.

If you see a Quick Fix icon then click .

for a Schematron error (on the line where the error occurs),

Note If you don't see 2.

, then click the Text tab at the bottom of the page.

Click a quick fix option, and follow any steps in the Quick Fix dialog box.

Tools & Software not appearing in Uno If you don't see Tools & Software in Uno, there are steps you can take to resolve it. If you don't see Tools & Software in Uno, follow these steps: 1.

Click Manage workspaces and widgets.

Double-click Request Computing Resources.

Click the Tools & Software icon.

Troubleshoot build issues using the DITA-OT log Although the DITA Open Toolkit (DITA-OT) log is not especially user-friendly, by looking for a few key elements, you can use the log to find and fix issues in your build.

Locating errors in the DOT log Typically when a job fails, you want to start looking in the DITA-OT log for most severe errors first , then go to lower severity messages. 1.

Download the buildlog.zip file from the build and extract the build.log file to your desktop.

Open the build.log file with a text editor like Notepad or Wordpad.

Search for the term “fatal” to find any fatal messages. When you find one, select the entire message string and copy it to a blank text document.

Continue searching until you don't find any more fatal messages.

If you don't find any more fatal messages, then search on the term “[error]”. (Include the brackets.) When you find one, select the entire message string and copy it to the text document.

Note The log may repeat the same message on the same topic in different parts of the log because different processes encounter it. You can usually ignore multiple occurrences of the same message on the same topic, as long as you fix it once.

July 31, 2025 Appendix D-4 of D-6

Appendix D

Tracking down missing cross-references 6.

Try to determine what the message is saying. A good guide is available at: http://www.ditaot.org/1.8/readme/DITA-messages.html

To find the file affected by the error:

In the Workspace, click the Search tab.

Press Ctrl+V to paste the second GUID listed in the log message into the GUID field.

Click Search.

Check out the topic and find the broken link target (the first GUID listed in the log message).

Fix and check in, then run the build again.

If your search doesn't turn up any fatal or error messages, but there is no output, then post DITA-OT processing may be the culprit. a.

Look at the end of the log to find a BUILD FAILED heading. There will be text under that – usually some type of Java errors – indicating what went wrong. These can be very hard to decipher.

One possible reason for failure is the search-and-replace file used for OHJ contains blank lines at its end. Delete all blank lines from that file.

Tracking down missing cross-references Cross-reference errors can be a bit confusing because the messages are even more cryptic. 1.

Locate DOTX031E errors in the DOT log; see Locating errors in the DOT log.

In this message, the first GUID (GUID-CBC9FB78-1744-4D07-96FD-F0AFB8BCBBCE) is the file that the build can't find. The second GUID (GUID-27D69BE2-1A5E-4E90B3AB-0731911303C3) is the file that contains the missing or broken link. [DOTX031E][ERROR]: The file file:/tmp/scratch/buildArea/build_gEfYqDP2q777hkyf/tmp/ GUID-CBC9FB78-1744-4D07-96FD-F0AFB8BCBBCE is not available to resolve link information. The location of this problem was at(File = /tmp/scratch/buildArea/build_gEfYqDP2q777hkyf/sources/ GUID-27D69BE2-1A5E-4E90-B3AB-0731911303C3.xml,

To find the file affected by the error: a.

In the Workspace, click the Search tab.

Press Ctrl+V to paste the second GUID listed in the log message into the GUID field.

Click Search.

Check out the topic and find the broken link target (the first GUID listed in the log message).

Fix and check in, then run the build again.

View the OAK Foundation version You can view which version of OAK Foundation you have installed.

•

In Oxygen, select About from the OAK Foundation menu to view the build number.

July 31, 2025 Appendix D-5 of D-6

Appendix D

Get help

Get help For assistance with OAK Foundation, contact the #infodev-oakf-helpdesk Slack channel. For more information on Oxygen, see the Oxygen XML Author 27.0 User Guide.

July 31, 2025 Appendix D-6 of D-6

E XML refactoring You can use Oxygen to separate sections in DITA topics into standalone topics, convert DITA topics into different topic types, convert DITA maps into different map types, and convert elements and attributes for various reasons.

Note If you have not yet migrated to OAK Foundation, you can perform refactoring in Oxygen 20.1 or later.

Separate sections into standalone topics You can convert the sections inside of a topic into separate topics. You can convert the resulting topics into another topic type as needed. You need to replace the OASIS doctype declaration that is inserted by default with the InfoDev declaration for the associated topic type as part of this manual conversion. 1.

In the OAK Foundation Workspace, right-click the topics you want to convert, and then select Check Out and Open.

Convert sections to standalone topics: a.

In Oxygen, select XML Refactoring from the Tools menu.

Under DITA, select Convert sections to new topics, and then click Next.

Under Scope, select Current File or All opened files, and then click Finish.

The original topic remains open in Oxygen. Files are created for each section and saved in Local Storage. 3.

Add each new topic to OAK Foundation: a.

In the Workspace, right-click the folder where you want the topics, then select Add File.

Browse to Local Storage (C:\Users\<Your Name>\AppData\Local\OAKF\oakf_local_storage_prod). The section title is appended to the end of the new files using the same file name as the original using this format: <Original_Topic_Title>=<GUID>=<Version>_<Section_Title>.xml; for example, Separate_sections_into_standalone_topics=GUID-2D67A92AB1C1-4164-8D65-0A746FD5A40E=1_section_title.xml.

Rename each file with title you want to use, removing the original topic title, GUID, and version; for example, Section_Title.xml

Select the renamed file, then and click Open.

In the Workspace, right-click the newly added topics, and select Check Out and Open.

Convert the topics to a different topic type as needed: a.

In Oxygen, select XML Refactoring from the Tools menu.

July 31, 2025 Appendix E-1 of E-3

Appendix E

Separate sections into standalone topics

Under DITA, select the corresponding conversion command; for example, Convert to task, and then click Next.

Under Scope, select Current File or All opened files, and then click Finish.

Replace the OASIS doctype declaration with the InfoDev declaration for the associated topic type. a.

In Oxygen, select Find/Replace in Files under the Find menu.

Select Ignore extra whitespaces, so that all instances of a text string are found.

Select Enable XML search options, then select Doctype.

In Text to find, enter the OASIS declaration and in Replace with enter the InfoDev declaration as defined below. F Text to find... or th is to pi c ty p e. ..

Replace with...

To <!DOCTYPE topic PUBLIC "-//OASIS//DTD pi DITA Topic//EN" "topic.dtd"> c

<!DOCTYPE topic PUBLIC "-//Oracle//DTD InfoDev DITA Topic//EN" "infodevTopic.dtd[]">

Ta <!DOCTYPE task PUBLIC "-//OASIS//DTD sk DITA Task//EN" "task.dtd">

<!DOCTYPE task PUBLIC "-//Oracle//DTD InfoDev DITA Task//EN" "infodevTask.dtd[]">

C <!DOCTYPE concept PUBLIC "-// on OASIS//DTD DITA Concept//EN" ce "concept.dtd"> pt

<!DOCTYPE concept PUBLIC "-// Oracle//DTD InfoDev DITA Concept//EN" "infodevConcept.dtd[]">

R <!DOCTYPE reference PUBLIC "-// ef OASIS//DTD DITA Reference//EN" er "reference.dtd"> en ce

<!DOCTYPE reference PUBLIC "-// Oracle//DTD InfoDev DITA Reference//EN" "infodevReference.dtd[]">

Under Scope, select All opened files.

Click Find All.

In the Results pane, review each occurrence of the text by double-clicking rows with the highlighted word or string. The corresponding topic opens with the text string highlighted in yellow.

In Oxygen, select Find/Replace in Files under the Find menu.

Click Replace All.

In Oxygen, select Check In from the OAK Foundation menu.

July 31, 2025 Appendix E-2 of E-3

Appendix E

Replace an element with another

Replace an element with another You can replace one element with another element to quickly change the XML markup. For example, you can replace "body text headings" coded as <p><b> into sections with titles <section><title>. 1.

In the OAK Foundation Workspace, right-click the topics you want to convert, and then select Check Out and Open.

Change one element to another:

In Oxygen, right-click the specific instance of the element you want to replace, then select Refactoring, Rename Element. For example, to replace <p><b> with <section><b>, select the <p> element.

Enter the new element name without the opening and closing brackets (for example, section), select Rename current element, and then click OK.

If you are changing nested elements, repeat these steps on the next element. For example, to replace <b> with <title>, select the <b> element and change it to <title>.

You might need to adjust other elements to create valid XML. For example, elements that belong to the section need to be moved inside <section>.

In Oxygen, select Check In from the OAK Foundation menu.

July 31, 2025 Appendix E-3 of E-3