10. 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.

10.1. Getting Started

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

10.1.1. Step 1: Create the New Project

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

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
Browse Files
Figure 64. Create the New Project

See Figure 65.

1 In Project Name, change from "Standard Template" to your project name, in the example shown "My Project"
2 Optionally adjust the Project URL and Project slug
3 Enter Project Description, and also Visibility Level
4 Finally select Create Project
Browse Files
Figure 65. Create the New Project

10.1.2. Step 2: Configure the Document

10.1.3. 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 Section 7.4 to commit the project.

10.2. The File Tree

In general, files beginning with underscore (_) are configuration files. They may need to be tailored for the document.

Files with suffix .sh are shell scripts.

Files with suffix .rb are Ruby scripts.

Files with suffix .adoc are AsciiDoc 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.

10.3. Configuring the Document

10.3.1. 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

10.4. 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:

  1. _vars.sh

  2. .gitlab-ci.yml (see Section 10.4.2)

10.4.1. _vars.sh

The document name should be set in _vars.sh.

# Variables for the build scripts in shell script format
TOG_DOCNAME=g_Handbook-for-GitLab-Development
export TOG_DOCNAME

10.4.2. 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/og-asciidoc-build-tools

variables:
  DOCNAME: g_Handbook-for-GitLab-Development

include:
#  - local: '/ci/compliance-checker.yml'
#  - local: '/ci/compliance-notify.yml'
  - local: '/ci/build-and-deploy.yml'

stages:
#  - compliance-check
#  - compliance-notify
  - build
  - deploy

10.4.3. 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::[]