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 |
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 |
10.1.2. Step 2: Configure the Document
See Section 10.2.
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. Configuring the Document
10.2.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: 2023
//
// 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.3. Setting the Output Filename
The default name for the output files is Template, which is set in the TOG_DOCNAME/DOCNAME variable.
There are two files to edit to change the name:
-
_vars.sh
-
.gitlab-ci.yml (see Section 10.3.2)
10.3.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.3.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: Template 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.3.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::book/00-front-matter/title-page.adoc[] include::book/00-front-matter/copyright.adoc[] include::book/00-front-matter/preface.adoc[] include::book/00-front-matter/trademarks.adoc[] include::book/00-front-matter/acknowledgements.adoc[] include::book/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::book/01-doc/chap01/introduction.adoc[] include::book/01-doc/chap02/definitions.adoc[] // Your original content can start here include::book/01-doc/chap03/chap03-intro.adoc[] // A chapter could be built from one or more files; //e.g., to add a file //include::book/01-doc/chap03/chap03-text.adoc[] // This is an example part page :sectnums!: include::book/01-doc/part1/part1.adoc[] :sectnums: include::book/01-doc/chap04/chap04-intro.adoc[] // The appendices follow :sectnums!: include::book/99-appendices/section-intro.adoc[] :sectnums: include::book/99-appendices/appendix.adoc[] include::book/99-appendices/rationale.adoc[] // Index is not generated for html ifdef::backend-pdf[] // The index is auto-generated include::book/99-appendices/index.adoc[] endif::[]