transformed

visualization/doc/about.md

@@ -0,0 +1,25 @@
+# About
+
+Die zur Umsetzung des beschriebenen Konzepts benötigten Komponenten beinhalten 
+verschiedene Bestandteile.
+
+Elektronische Rechnungen, die visualisiert werden sollen, sind XRechnungskonforme XML-Instanzen in den vorgegebenen Syntaxen UBL und CII. Diese können mittels von der KoSIT 
+bereitgestellten Transformationsskripten in das syntaxneutrale Format überführt werden. 
+
+Eine beispielhafte Visualisierung des Kompetenzzentrums für das Kassen- und 
+Rechnungswesen des Bundes (KKR) ist mittels eines weiteren Transformationsskriptes in 
+(X)HTML-Format möglich und kann anhand von CSS-Datei(en) zur Umsetzung von Layout 
+und Labeln gestaltet werden. Diese Visualisierung dient der Veranschaulichung und kann 
+anwendungsspezifisch angepasst werden.
+
+Die Komponenten zur Visualisierung bestehen aus den folgenden Teilen:
+
+| # | Komponente - Beschreibung | Verantwortung |
+| :--- | :---: | :---: |
+| 1. | Transformationsskripte (XSLTs) zur Überführung von Rechnungen im UBL-Format und CII-Format (konform zu XRechnung) in das syntaxneutrale Format | KoSIT |
+| 2. | XML Schema-Definition (XSD) zur Validierung der erzeugten Rechnungen im syntaxneutralen Format | KoSIT |
+| 3. | Transformationsskript (XSLT) zur Überführung von syntaxneutralen Rechnungen in das (X)HTML-Format | KKR |
+| 4. | CSS-Datei(en) zur Umsetzung von Layout und Labeln | KKR |
+<caption style="align:center;"><em>Abbildung 2: Bestandteile und Verantwortlichkeiten</em></caption>
+
+Als Betreiberin des Standards XRechnung stellt die KoSIT die *Bestandteile 1 und 2* bereit, das KKR liefert die *Bestandteile 3 und 4* zur beispielhaften Visualisierung.

visualization/doc/architecture.md

@@ -0,0 +1,41 @@
+# Architecture
+
+Der Standard XRechnung basiert auf der Europäischen Norm EN16931. Diese Norm besteht 
+aus einem semantischen Datenmodell und sogenannten Syntax-Bindings zu den 
+vorgegebenen Syntaxen.
+
+Das semantische Datenmodell spezifiziert in nicht-technischer Form mögliche Bestandteile
+(Rechnungsnummer, Rechnungsdatum, Rechnungsbetrag, Käufer etc.) elektronischer
+Rechnungen in Form von Business Terms (BT), Business Groups (BG) und Business Rules 
+(BR). Mit den Syntax-Bindings wird spezifiziert, wie diese Bestandteile in technischer Form 
+abgebildet werden müssen. Grundlage dieser Spezifikation sind die beiden durch die Norm 
+vorgegebenen Syntaxen UBL und CII und die diesen Syntaxen zugrundeliegenden XML 
+Schema-Dateien.
+
+Im Rahmen der Umsetzung der elektronischen Rechnungsbe- und -verarbeitung wurde in 
+unterschiedlichen Zusammenhängen die Anforderung formuliert, die durch die Norm 
+spezifizierte technische Abbildung einer konkreten Rechnung (= XML-Instanz) in 
+strukturierter Form für menschliche Leser\*innen optimiert lesbar anzuzeigen. Bestandteile
+dieser Anzeige (Visualisierung) sind zum einen die konkreten Inhalte der elektronischen 
+Rechnung und deren Bezug zu den BTs und BGs der Norm. Zum anderen muss das 
+Konzept der Visualisierung anwendungsspezifische Anforderungen hinsichtlich Position, 
+Reihenfolge und Bezeichnung der Bestandteile einer Rechnung unterstützen.
+
+*Abbildung 1* zeigt einen konzeptionellen Ansatz zur Erzeugung der Visualisierung von 
+XRechnungen unter Berücksichtigung der genannten Anforderungen.
+
+![Grundkonzept der Visualisierung von XRechnung](../img/visualization-concept.png)
+<figcaption align="center" style="width:80%;"><em>Abbildung 1: Grundkonzept der Visualisierung von XRechnung</em></figcaption>
+
+*Schritt 1* beinhaltet die Rechnungen im Format der durch die Norm geforderten technischen 
+Syntaxen (XML-Instanzen in UBL bzw. CII).
+
+*Schritt 2* zeigt die mittels einer bereitgestellten Transformation (XSL-Datei aus den 
+gegebenen XML-Instanzen) in eine „syntaxneutrale“ Abbildung der Rechnung, die um die 
+Information zu den in der Rechnung genutzten BTs und BGs angereichert ist.
+
+Diese Abbildung ist die Basis für eine zweite Transformation der Rechnung in eine domänen- bzw. anwendungsspezifische Visualisierung im HTML-Format (*Schritt 3*). Die letztendliche 
+Visualisierung dieser HTML-Instanzen erfolgt mittels CSS-Dateien, in denen individuelle 
+Bezeichner, Positionen und Reihenfolgen der BTs/BGs und der zugehörigen 
+Rechnungsinhalte spezifiziert sind. Transformation (XSL-Datei) und zugehörige CSS-Dateien 
+werden durch die jeweiligen Anwendungsbereiche bereitgestellt.

visualization/doc/development.md

@@ -0,0 +1,112 @@
+# Development of XRechnung Visualization
+
+
+## Project Structure
+
+* `src` contains the source files.
+* `src/test` contains example instances of invoice files.
+* `src/xsd` contains the schema of the intermediate xml.
+* `src/xsl` contains the transformation files.
+
+## Dependencies Overview
+
+### Compile Time
+
+That is for creating visualizations.
+
+* Apache FOP
+* Saxon HE
+* XRechnung-Testsuite
+
+### Testing
+
+* validator-configuration-xrechnung
+* VNU HTML Validator
+
+## The build environment
+
+This repository contains an ANT `build.xml` for development and test.
+
+We recommend `Apache Ant` version 1.10.x or newer (but should work with > 1.8.x).
+
+The main `ant` targets for development are:
+
+* `clean` deletes all generated folders i.e. foremost the `build` directory.
+* `transform-to-visualization` generates all visualizations from xrechnung-testsuite and test instances in `src/test`
+* `test` validates source UBL or CII XML against XRechnung, transforms to XR Sem Model and schema validates results and transforms and test HTML and PDF visualization
+* and `dist` (creating the distribution artefact)
+
+However, because of the complex dependencies, you may only expect `transform-to-visualization` target to work without any customizations.
+
+## Test dependencies on the fly
+
+If you build own local custom versions of dependencies such as XRechnung Testsuite or Validator Configuration XRechnung, you can customize the ant build at runtime.
+
+### Test with local Validator Configuration XRechnung
+
+If you want to test with a local validator configuration xrechnung installation set the ant property `validator.repository.dir` to the directory (full path) like e.g. `validator.repository.dir=/mnt/c/data/git-repos/validator-configuration-xrechnung/build` (Linux). 
+To execute the `test` target, for example, call
+
+```shell
+ant -Dvalidator.repository.dir=/home/renzo/projects/validator-configuration-xrechnung/build test
+```
+
+For Windows users:
+
+```shell
+ant "-Dvalidator.repository.dir=/c:/dev/git/validator-configuration-xrechnung/build" test
+```
+
+### Development properties file
+
+In order to configure more complex adoption to the local development needs, you have to load a set of different properties from a file.
+
+We provide the `development.build.properties.example` file for the most common properties to be set different than default. It contains some documentation.
+
+You have to copy the file to e.g. `development.build.properties` and you have to explicitly provide the property file location at CLI for your development (otherwise tests will always fail or not be executed at all).
+
+
+## Distribution
+
+The `ant` target `dist` creates the distribution zip Archive for releases.
+
+## Release
+
+### Checklist
+
+* Are all issues scheduled for the release solved?
+* Is everything merged to master branch?
+* Make sure that CHANGELOG.md is up to date
+* Make sure all external contributors are mentioned
+
+
+### Prepare
+
+* Make sure you committed and pushed everything 
+* Create the distribution 
+ 
+   * Use the `clean` target to build and test all from scratch
+
+```
+ant clean dist
+```
+
+* Tag the last commit according to the following naming rule: `v${xr-visu.version.full}` e.g.
+  `git tag v2024-06-20 && git push origin v2024-06-20`
+
+### Publish
+
+* Draft a new release at https://github.com/itplr-kosit/xrechnung-visualization/releases/new
+  * Choose the git tag you just created
+* Add release title of the following scheme: `XRechnung Visualization ${xr-visu.version.full} compatible with XRechnung ${xrechnung.version}`
+* Copy & paste the high quality changelog entries for this release from CHANGELOG.md.
+* Upload distribution zip and tick mark this release as a `pre-release`.
+* If **all** released components are checked to be okay, then uncheck pre-release.
+
+### Post-Release
+
+* Change the version of this component in `build.xml` to the next release and commit
+* bump version
+* update CHANGELOG.md
+
+You are done :smile:

visualization/doc/guide-for-visual-testing.md

@@ -0,0 +1,39 @@
+# Guide for Visual Testing
+
+## Embedded Documents
+For testing embedded documents' features, use
+* embedded-documents-bt-125_ubl.xml
+* embedded-documents-with-newline-and-whitespace_ubl.xml
+* 01.15
+
+Expectation:
+* HTML: should work across all browsers
+* PDF: default configuration should work:
+  * with Adobe Professional 2017
+  * with PDF-XChange Viewer 2.5
+  * but not in browsers at all 
+
+## Scheme Identifier for various BTs
+* maxRechnung_ubl.xml
+* maxRechnung_creditnote.xml
+
+## "Project reference" (BT-11) in UBL Creditnote
+* maxRechnung_creditnote.xml
+
+## Direct Debit (BG-19)
+
+* direct-debit-bt-90-seller_ubl.xml (BT-29 and BT-60 with @schemeID)
+* direct-debit-bt-90-payee_ubl.xml (BT-29 and BT-60 without @schemeID)
+* direct-debit-bt-90-seller_creditnote.xml (BT-29 and BT-60 with @schemeID)
+* direct-debit-bt-90-payee_creditnote.xml (BT-29 and BT-60 without @schemeID)
+
+## Item Attributes (BG-32)
+* itemAttributes_ubl.xml
+
+## Dates
+* wrong-date-with-text-uncefact.xml
+* wrong-date-with-zeros-uncefact.xml
+
+expectation: 
+* fields should contain "no date defined" or similar
+* all others should show YYYY-MM-DD without timezone

visualization/doc/usage.md

@@ -0,0 +1,72 @@
+# Usage
+
+There are various configuration options for the XSLT transformations.
+
+## PDF Transformation
+
+### Choice of PDF Profile
+
+There are various profiles for PDF generation. The default uses none with enabled accessibility. 
+In order to use profile PDF/UA-1 and PDF/A-1, you can use another FOP configuration during build time, e.g. 
+```bash
+ant -Dfop.config=conf/fop-with-ua1-a1.xconf transform-xr-to-pdf
+```
+
+Note: PDF/A-1 does not allow embedded files. Use the default profile for display of embedded documents.
+
+### Choice of FO engine 
+
+The FO engine used can be specified. Engine specific extensions will then be enabled. 
+
+```xml
+<xsl:param name="foengine"/>
+```
+
+Supported values are: 
+* axf - Antenna House XSL Formatter
+* fop - Apache FOP
+
+### Layout options
+
+**Configuration of the general invoice layout **
+
+```xml
+<xsl:param name="invoiceline-layout">normal</xsl:param>
+```
+Supported values are: 
+* normal - Similar to HTML layout incl. box layout of invoice lines 
+* tabular - Tabular layout of invoice lines
+
+**Configuration of table column width**
+
+```xml
+<xsl:param name="tabular-layout-widths">2 7 2 2 2 2 1.3 2</xsl:param>
+```
+
+Change column proportions according to your tabular layout.
+
+**Configuration of the invoice line numbering scheme**
+
+```xml
+<xsl:param name="invoiceline-numbering">normal</xsl:param>
+```
+
+Supported values are: 
+* normal - use numbers as in original invoice 
+* 1.1    - use multilevel arabic numbering
+* 1.i    - use mixture of arabic and roman numbering
+* 00001  - use aligned arabic numbering 
+* *other* - any picture string supported by [xsl:number](https://developer.mozilla.org/en-US/docs/Web/XSLT/Element/number) instruction can be used
+
+### Choice of Language for HTML and PDF
+
+Default language is German (de), an English (en) translation is also provided.
+
+```xml
+<xsl:param name="lang" select="'de'"/>
+```
+
+Translation files are located in the [l10n subdirectory](../src/xsl/l10n/) and can be customized according to specific local needs.
+
+Translation files are formatted according to Java Properties in XML (see https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Properties.html for details).
+Additional languages can be included by adding XML Properties files to the [l10n directory](../src/xsl/l10n/). By default, files have to be named according to ISO 639-1 two letter language codes (e.g. `fr.xml` for French).