Skip to content

Commit

Permalink
Update variables for the GREEN curriculum
Browse files Browse the repository at this point in the history
  • Loading branch information
programming-wolf committed Sep 29, 2023
1 parent 10a456a commit 7469eda
Show file tree
Hide file tree
Showing 6 changed files with 18 additions and 129 deletions.
135 changes: 14 additions & 121 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ ifdef::env-github[]
endif::[]

== Status
image:https://github.com/isaqb-org/advanced-template/workflows/CI%20-%20Releases%20and%20Main/badge.svg?branch=main["CI – Releases and Main"]
image:https://img.shields.io/github/last-commit/isaqb-org/advanced-template/main.svg["Last commit"]
image:https://img.shields.io/github/contributors/isaqb-org/advanced-template.svg["Contributors",link="https://github.com/isaqb-org/advanced-template/graphs/contributors"]
image:https://img.shields.io/github/issues/isaqb-org/advanced-template.svg["Issues",link="https://github.com/isaqb-org/advanced-template/issues"]
image:https://img.shields.io/github/issues-closed/isaqb-org/advanced-template.svg["Issues closed",link="https://github.com/isaqb-org/advanced-template/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aclosed+"]
image:https://github.com/isaqb-org/curriculum-green/workflows/CI%20-%20Releases%20and%20Main/badge.svg?branch=main["CI – Releases and Main"]
image:https://img.shields.io/github/last-commit/isaqb-org/curriculum-green/main.svg["Last commit"]
image:https://img.shields.io/github/contributors/isaqb-org/curriculum-green.svg["Contributors",link="https://github.com/isaqb-org/curriculum-green/graphs/contributors"]
image:https://img.shields.io/github/issues/isaqb-org/curriculum-green.svg["Issues",link="https://github.com/isaqb-org/curriculum-green/issues"]
image:https://img.shields.io/github/issues-closed/isaqb-org/curriculum-green.svg["Issues closed",link="https://github.com/isaqb-org/curriculum-green/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aclosed+"]


This is <<copyrighted,copyrighted work>>.
Expand All @@ -27,136 +27,32 @@ This repository contains a template for iSAQB Advanced Level *curricula* in Asci
toc::[]

== How to contribute or participate
Create an issue, a merge- or pull-request

== How to use this template

. Either click on "Use this template" in the Github UI or Clone the repository - including the submodule:
Create an issue, a merge- or pull-request. Clone the repository, including the submodule:
+
--
[source,shell]
----
Via SSH:
git clone [email protected]:isaqb-org/advanced-template.git --recursive
git clone [email protected]:isaqb-org/curriculum-green.git --recursive
Via HTTPS:
git clone https://github.com/isaqb-org/advanced-template.git --recursive
git clone https://github.com/isaqb-org/curriculum-green.git --recursive
----
--
. Rename the repository to the name of your curriculum e.g. `curriculum-flex`
. Rename the file `/docs/advanced-template.adoc` to the name of your curriculum e.g. `curriculum-flex.adoc` (this is later on referred to as `curriculumFileName`)

== TODO

. Open the file `./config/setup.adoc` to adjust configuration specific to your curriculum:
.. `:curriculum-short: MODULKUERZEL`: this is the abbreviation of your module. Replace MODULKUERZEL with your module name e.g. FLEX
.. `:curriculum-name: MODULNAME IN VOLLER LAENGE`: the full German title of your CPSA-A module. replace "MODULNAME IN VOLLER LAENGE" with your module name e.g. "Flexible Architecture Models - Microservices und Self-Contained Systems"
.. `:curriculum-name: MODULNAME IN VOLLER LAENGE`: the full English title of your CPSA-A module. replace "MODULNAME IN VOLLER LAENGE" with your module name e.g. "Flexible Architecture Models - Microservices and Self-Contained Systems"
. Open the file `build.gradle` to adjust attributes specific to your curriculum:
[loweralpha]
.. `curriculumFileName`: the name of the asciidoc root file of your curriculum e.g. `curriculum-flex` (see above! The `.adoc` suffix is added automatically, omit it here!)
. Open README.adoc and replace the string `curriculum-template` with the name of your Github repository e.g. `curriculum-flex`
. Build the project with http://www.gradle.com[gradle] (you need a locally installed JDK 17 or higher) via `./gradlew`.
. Once the "BUILD SUCCESSFUL" is show, you can review the build result under `./build/index.html`

== How to write iSAQB Advanced Level Curricula with AsciiDoc

=== Requirements and (our) solutions

[cols="1,2a",options="header"]
|===
|Requirement
|Solution

|Visually appealing pdf output
|We created an iSAQB pdf theme, located under the `/style` directory. The original is maintained in the `adoc2pdf` repository.

|Multiple people contribute content, review and comment
|highly modularized content: Small chunks, like learning-goals or subsections, are contained in their own asciidoc-files.

|Multiple languages, at least EN and DE (i18n)
|Every piece of text is enclosed in _tags_ like `tag::EN[]`. The build process collects all parts for the desired language.

|Simple conversion from asciidoc to pdf (and html)
|There is currently one option available:

* Gradle based build, requiring a local Java runtime.
|===

- - -

**TODO:** Add explanation for keywords and general procedure when creating a new Advanced Level Curriculum.

- - -

=== How to organize files?

==== Prerequisite: AsciiDoc include
You should know some details about the AsciiDoc include statement.

If the Asciidoctor processor encounters a statement like the one below:

[source,asciidoc]
----
include::directory/file.adoc[]
----

It will replace this include statement with the contents of `file.adoc`. That's easy and straightforward.

=== Content and Structure files
As we are writing i18n we need to strictly distiguish between two
kind of files:

* *content* files, they contain text, tables or diagrams that shall be included in the output.
* *structure* files, containing only include-statements, configuration information. Structure files include both content-files and other structure files.

For content files, specific parts will be included via the tag-syntax described above.
For that purpose we define a variable named `include_configuration` in the file `config/setup.adoc`.

==== Structure File Example

In theory, you can just use the `docs/curriculum-template.adoc` as is and just
edit the section documents in the subdirectories. If you want to create your own file,
we recommend to stick with the following:

From `docs/curriculum-template.adoc` (excerpts):

[source,asciidoc]
----
= Template Curriculum: CPSA Certified Professional for Software Architecture^(R)^
:doctype: book
include::config/setup.adoc[] // // <1>
:document-version: 2020.2 // //<2>
:sectnums!: // // <3>
include::00-preamble/copyright.adoc[{include_configuration}] // // <4>
<<< // // <5>
:toc:
<<<
:sectnums!:
include::00-preamble/00-introduction.adoc[] // //<6>
----

1. We propose to put the asciidoc configuration in this special file (`docs/config/setup.adoc`).
2. You can set a version, but it may be overridden in the build process.
3. You can turn section numbering on and off (here: off).
4. This includes parts of the `docs/00-preamble/copyright.adoc` file.
5. The `<<<` will create a pagebreak in pdf files.
6. Include the whole file 00-introduction.adoc.


=== Suggestions

TBD.

== How to build the documents

Prerequisite: You need a Java Runtime(tm) installed.

You build the output documents with gradle.
That will produce both pdf and html output in German (DE) _and_ English (EN), unless you modify the configuration.
You build the output documents with gradle, use the wrapper that comes with the repository: `./gradlew buildDocs`

This will produce both pdf and html output in German (DE) _and_ English (EN), unless you modify the configuration.

In case you want to change that, adjust the following part of `build.gradle`:

Expand All @@ -171,9 +67,6 @@ task buildDocs {

In the task "renderDE", certain attributes (aka variables) are defined that configure the corresponding output.

== Additional translations/languages
include::docs-ext/EXTERNAL_DOCUMENTS_README.adoc[]

== Maintainers

This repository is currently maintained by Benjamin Wolf.
Expand Down
2 changes: 1 addition & 1 deletion build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ def group = "org.isaqb"
def releaseVersion = System.getenv("RELEASE_VERSION")
def localVersion = "LocalBuild"
project.version = releaseVersion == null ? localVersion : releaseVersion
def curriculumFileName = "curriculum-template"
def curriculumFileName = "curriculum-green"
def versionDate = new SimpleDateFormat("yyyyMMdd").format(new Date())
def languages = ["DE", "EN"]

Expand Down
Binary file removed docs-ext/curriculum-template-es.pdf
Binary file not shown.
4 changes: 2 additions & 2 deletions docs/config/setup.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
:icons: font
:sectnumlevels: 2
:imagesdir: images
:chapter-label:
:chapter-label:

// ":language:" denotes the language or the target document.
// currently only DE and EN are supported
Expand All @@ -12,7 +12,7 @@
// additional markers might be configured here!
:include_configuration: tags=**;{language};!*

:curriculum-short: MODULKUERZEL
:curriculum-short: GREEN

ifeval::["{language}" == "DE"]
:curriculum-name: MODULNAME IN VOLLER LAENGE
Expand Down
File renamed without changes.
6 changes: 1 addition & 5 deletions docs/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ The terminology used in the iSAQB curricula can be found as a (freely available)

== Development versions

The Advanced Level Template Curriculum is currently maintained and published in both English (EN) and German (DE).
The Curriculum {curriculum-name} is currently maintained and published in both English (EN) and German (DE).
Maintainers and volunteer reviewers collaborate on GitHub to improve the curriculum.

[cols="<,^,^"]
Expand All @@ -24,8 +24,4 @@ Maintainers and volunteer reviewers collaborate on GitHub to improve the curricu
| link:{curriculumFileName}-en.html[HTML]
| link:{curriculumFileName}-en.pdf[PDF]

| Español
|
| link:{curriculumFileName}-es.pdf[PDF]

|===

0 comments on commit 7469eda

Please sign in to comment.