generated from isaqb-org/advanced-template
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update variables for the GREEN curriculum
- Loading branch information
1 parent
10a456a
commit 7469eda
Showing
6 changed files
with
18 additions
and
129 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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>>. | ||
|
@@ -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`: | ||
|
||
|
@@ -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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters