generated from isaqb-org/advanced-template
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
51b1c59
commit 0630ad4
Showing
6 changed files
with
23 additions
and
151 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 |
|---|---|---|
| @@ -1,4 +1,4 @@ | ||
| = Template for https://isaqb.org[iSAQB] Advanced Level Curricula | ||
| = https://isaqb.org[iSAQB] Advanced Level Curriculum Formal Methods FM | ||
|
|
||
| :toc: | ||
| :toc-placement!: | ||
|
|
@@ -12,172 +12,44 @@ 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-fm/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-fm/main.svg["Last commit"] | ||
| image:https://img.shields.io/github/contributors/isaqb-org/curriculum-fm.svg["Contributors",link="https://github.com/isaqb-org/curriculum-fm/graphs/contributors"] | ||
| image:https://img.shields.io/github/issues/isaqb-org/curriculum-fm.svg["Issues",link="https://github.com/isaqb-org/curriculum-fm/issues"] | ||
| image:https://img.shields.io/github/issues-closed/isaqb-org/curriculum-fm.svg["Issues closed",link="https://github.com/isaqb-org/curriculum-fm/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aclosed+"] | ||
|
|
||
|
|
||
| This is <<copyrighted,copyrighted work>>. | ||
|
|
||
| == Content | ||
| This repository contains a template for iSAQB Advanced Level *curricula* in AsciiDoc. | ||
| This repository contains the curriculum Formal Methods | ||
|
|
||
| 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: | ||
| 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-fm.git --recursive | ||
| Via HTTPS: | ||
| git clone https://github.com/isaqb-org/advanced-template.git --recursive | ||
| git clone https://github.com/isaqb-org/curriculum-fm.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`) | ||
| . 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: | ||
| . Once the "BUILD SUCCESSFUL" is show, you can review the build result under `./build/` | ||
|
|
||
| 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. | ||
|
|
||
| In case you want to change that, adjust the following part of `build.gradle`: | ||
|
|
||
| [source,groovy] | ||
| ---- | ||
| task buildDocs { | ||
| group 'Documentation' | ||
| description 'Grouping task for generating all languages in several formats' | ||
| dependsOn "renderDE", "renderEN" | ||
| } | ||
| ---- | ||
|
|
||
| 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. | ||
| It was forked from https://github.com/isaqb-org/curriculum-template, | ||
| This repository is currently maintained by Mike Sperber and his team. | ||
| It was forked from https://github.com/isaqb-org/advanced-template, | ||
| so the contributors of that project basically contributed to this one, too. | ||
|
|
||
|
|
||
|
|
||
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