The Open Group Standard Template

In this chapter we give a brief overview of how to instantiate a project using The Open Group Standard template. This is primarily for advanced users, usually the maintainer of the project. We describe the steps below in their most generic form.

Getting Started

When developing a new document we create the project by importing a copy of the template.

Step 1: Create the New Project

Go to top level of the GitLab site, and select New Project. See Figure 1.

1	Select the "Import Project" tab
2	Click on "git Repo by URL"
3	Enter https://gitlab.com/theopengroup/standard-template.git into the Git repository URL field
4	Leave Username and Password blank
5	Enter the project name, also you can enter the project description, select where the project is created (the project URL) and the visibility level

Figure 1. Create the New Project

You can then scroll down and click on Create Project. The progress of the import of the project template is then shown, see Figure 2.

Figure 2. Importing the Project Template

Confirmation of the successful import is then shown, see Figure 3.

Figure 3. Successfully Imported the Project Template

Step 2: Configure the Document

See Configuring the Document.

Step 3: Commit the Changes

The final step is to commit the configured document back to the project repository.

We recommend using the Brackets editor to do this. See Working with a Project to commit the project.

The File Tree

In general, files beginning with underscore (_) are configuration files. They may need to be tailored for the document, usually done by the project maintainer and/or the editorial team..

Files with suffix .sh are shell scripts.

Files with suffix .rb are Ruby scripts.

Files with suffix .adoc are AsciiDoc files.

Files with prefix _ or the suffix .yml are configuration files.

The file tree should look as follows (directories are shown with a trailing slash (/)):

LICENSE
README.md
_book-html.adoc
_book-pdf.adoc
_files.adoc
_strings.adoc
_vars.sh
bin/
ci/
images/
modules/
output/
references.bib
resources/

The source for the document is developed in the modules directory.

The built documents are placed in the output directory.

Configuring the Document

Project Strings

The key file to set up a document is _strings.adoc. This sets various strings for the project.

// String Variables file
//
// Common strings should appear here for the Project
// To define a string variable:
//     :varname: value
//
// Use // to start a comment
//
// Used in many places including the copyright
//
:tog-producer: The Open Group
//
// Copyright type - default or short
:tog-copyright: default
//
// Copyright year - 2023, or 2005-2023
:tog-copyright-year: 2024
//
// The document type - Standard, Snapshot, or Guide
//:tog-doctype: Snapshot
//:tog-doctype: Guide
//:tog-doctype: TOGAF Series Guide
:tog-doctype: Standard
//
// for documents produced by the OSDU Forum set to true
// Sets the logos for the cover for pdf output
//:tog-osdu: true
:tog-osdu: false
//
// Is this a draft, if so DRAFT, if not leave blank
:tog-draft: DRAFT
//
// The Document Title
// use {nbsp} if you do not want it to break across lines
:tog-doctitle: The Book Title{nbsp}Here(TM)
// Inside Title - above without trademarks, can be an abbreviation
:tog-doctitle2: The Book Title{nbsp}Here
//
// Select a date format for page footers
// date format differs between published Standard (year) and Snapshot (date/time)
// {docyear} is year only
//:tog-date: {docyear}
// {localdatetime} is the date and time of the build
//:tog-date: {tog-draft} {localdatetime}
:tog-date: {tog-draft} {localdatetime}
//final Build
//:tog-date: {localdate}
//
// Keywords for the Document
//
:tog-keywords: Standard, Template, The Open Group, www.opengroup.org
//
//
// Document Number; e.g., C231, G236
// Document numbers are assigned by the editorial team.
:tog-document-Number: C23x
//
// ISBN number  (assigned by the editorial team)
// if set, edit frontmatter/copyright.adoc and uncomment a line
//:tog-isbn-number: 1-947754-xx-x
//
// Where to send feedback email to
:tog-feedback-email: ogspecs@opengroup.org
:tog-snapshot-feedback-email: ogspecs-snapshot-feedback@opengroup.org
//
//
// Whether to make template guidance visible in the document output;
// true is on, false is off
:tog-guidance: true
//:tog-guidance: false

Setting the Output Filename

The default name for the output files is Template, which is set in the TOG_DOCNAME/DOCNAME variable. If you are not sure of the naming then check with The Open Group editorial team.

There are two files to edit to change the name:

_vars.sh
.gitlab-ci.yml (see Configuring the Automated Build)

_vars.sh

The document name should be set in _vars.sh.

# Variables for the build scripts in shell script format
# Conventions are to use a prefix such as g_ for guide, ts_ technical standard, s_ for Snapshot
# The name here should also be the same in the .gitlab-ci.yml file
TOG_DOCNAME=g_Handbook-for-GitLab-Development
export TOG_DOCNAME

Configuring the Automated Build

The automated build is driven off the .gitlab-ci.yml file.

This will build a tree of output in the project repository. By default the output is to build the PDF and HTML output.

You should set the value of DOCNAME in this file.

image: opengroup/digital-portfolio-build-tools:latest

variables:
  # use the same value for DOCNAME as in _vars.sh
  DOCNAME: Template
  ZIPFILE: "${CI_PROJECT_NAME}-${CI_COMMIT_SHORT_SHA}.zip"

include:
  - local: '/ci/build-and-deploy.yml'

stages:
#  - images
  - build
  - deploy

Adding Chapters and Files to the Document

The file _files.adoc contains the list of files to build the document.

// The files used to build the document
// Switch auto-numbering off for sections such as the frontmatter and part pages
:sectnums!:
//frontmatter
include::modules/00-front-matter/title-page.adoc[]
include::modules/00-front-matter/copyright.adoc[]
include::modules/00-front-matter/preface.adoc[]
include::modules/00-front-matter/trademarks.adoc[]
include::modules/00-front-matter/acknowledgements.adoc[]
include::modules/00-front-matter/references.adoc[]

// The introduction starts at Chapter 1 in The Open Group Standard template, and must be numbered
// For The Open Group Standards the first two chapters must be Introduction and Definitions
:sectnums:
include::modules/01-doc/pages/chap01.adoc[]
include::modules/01-doc/pages/chap02.adoc[]

// Your original content can start here
include::modules/01-doc/chap03.adoc[]
// A chapter could be built from one or more files;
//e.g., to add a file
//include::modules/01-doc/pages/chap03-part2.adoc[]

// This is an example part page
:sectnums!:
include::modules/01-doc/pages/part1.adoc[]
:sectnums:
include::modules/01-doc/pages/chap04.adoc[]

// The appendices follow
:sectnums!:
include::modules/99-appendices/pages/section-intro.adoc[]

:sectnums:
include::modules/99-appendices/pages/appendix.adoc[]
include::modules/99-appendices/pages/rationale.adoc[]
// Index is not generated for html
ifdef::backend-pdf[]
// The index is auto-generated
include::modules/99-appendices/pages/index.adoc[]
endif::[]