diff --git a/README.adoc b/README.adoc index 8823dcc..4fc59ab 100644 --- a/README.adoc +++ b/README.adoc @@ -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 <>. == 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 git@github.com:isaqb-org/advanced-template.git --recursive +git clone git@github.com: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. diff --git a/build.gradle b/build.gradle index 9764091..832c49f 100644 --- a/build.gradle +++ b/build.gradle @@ -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-fm" def versionDate = new SimpleDateFormat("yyyyMMdd").format(new Date()) def languages = ["DE", "EN"] diff --git a/docs-ext/curriculum-template-es.pdf b/docs-ext/curriculum-template-es.pdf deleted file mode 100644 index a1c6b93..0000000 Binary files a/docs-ext/curriculum-template-es.pdf and /dev/null differ diff --git a/docs/config/setup.adoc b/docs/config/setup.adoc index 918422e..b21b0de 100644 --- a/docs/config/setup.adoc +++ b/docs/config/setup.adoc @@ -12,14 +12,14 @@ // additional markers might be configured here! :include_configuration: tags=**;{language};!* -:curriculum-short: MODULKUERZEL +:curriculum-short: FM ifeval::["{language}" == "DE"] -:curriculum-name: MODULNAME IN VOLLER LAENGE +:curriculum-name: Formale Methoden :curriculum-header-title: iSAQB-Curriculum für Advanced Level: {curriculum-short} endif::[] ifeval::["{language}" == "EN"] -:curriculum-name: FULL NAME OF MODULE +:curriculum-name: Formal Methods :curriculum-header-title: iSAQB curriculum for Advanced Level: {curriculum-short} endif::[] diff --git a/docs/curriculum-template.adoc b/docs/curriculum-fm.adoc similarity index 100% rename from docs/curriculum-template.adoc rename to docs/curriculum-fm.adoc diff --git a/docs/index_rc.adoc b/docs/index_rc.adoc index 3d56769..46bf272 100644 --- a/docs/index_rc.adoc +++ b/docs/index_rc.adoc @@ -9,11 +9,11 @@ The **Release Candidates** of the **{curriculum-name} [{curriculum-short}]** adv == Current Release Candidate v2023.1 -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://img.shields.io/github/commits-since/isaqb-org/advanced-template/latest.svg[] +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+"] +image:https://img.shields.io/github/commits-since/isaqb-org/curriculum-fm/latest.svg[] |=== | Version | HTML | PDF @@ -28,5 +28,5 @@ image:https://img.shields.io/github/commits-since/isaqb-org/advanced-template/la |=== == Changes compared to XXX -- link:https://github.com/isaqb-org/advanced-template/blob/main/CHANGELOG.md[CHANGELOG.md on GitHub] +- link:https://github.com/isaqb-org/curriculum-fm/blob/main/CHANGELOG.md[CHANGELOG.md on GitHub] // - link: [HTML diff to the latest curriculum] T.B.A.