README.adoc - aendggner - Gitiles

 = ÄndGgner -- Programmbibliothek zur Konsolidierung von Änderungsgesetzen des Bundes und der Länder
 Matthias Andreas Benkard
 // Meta
 :experimental:
 :data-uri:
 :sectnums:
 :toc:
 :stem:
 :toclevels: 2
 :description: ÄndGgner Manual
 :keywords: mulk
 // Settings
 :icons: font
 :source-highlighter: pygments


 == Resources

 |===
 |Resource |Links

 |Public Artifact
 |https://bintray.com/mulk/maven/aendggner[Bintray]

 |Bug Tracker
 |MantisBT
 |===


 [[building]]
 == Building a JAR

 To build an executable JAR at `target/aendggner-${REVISION}.jar`:

 [source,shell script]
 ----
 ./mvnw package
 ----

 `${REVISION}` defaults to `0.1.0-SNAPSHOT` unless you override it by
 passing the `-Drevision` flag to `mvnw`.


 == Running the Command Line Application

 To run the command line application after <<building,building>> it:

 [source,shell script]
 ----
 ./mvnw exec:java
 ----


 [[usage]]
 == Usage

 ÄndGgner erzeugt aus einem Stammgesetz und einem Änderungsgesetz eine
 zweispaltige HTML-Synopse (alte Fassung links, neue rechts, Änderungen
 wortweise hervorgehoben).

 Eingaben:

 * Stammgesetz (Bundesrecht): XML im gii-norm-Format von
   https://www.gesetze-im-internet.de/[gesetze-im-internet.de]
 * Stammgesetz (Landesrecht Bayern): konsolidierte Fassung von
   https://www.gesetze-bayern.de/[gesetze-bayern.de] als PDF oder als
   kanonischer Klartext im Format der `--extract-only`-Ausgabe; amtliche
   Satznummern und Fußnotenmarker stehen als Unicode-Superskripte im
   Text („¹Die freilebende Tierwelt …“, „Enteignung⁶)“)
 * Änderungsgesetz: BGBl-, GVBl- oder Drucksachen-PDF (Bundestag,
   Bundesrat, Bayerischer Landtag) oder Klartext

 [source,shell script]
 ----
 java -jar target/aendggner-0.1.0-SNAPSHOT.jar \
   stammgesetz.xml aenderungsgesetz.pdf -o synopse.html
 ----

 Wichtige Optionen:

 `-o, --output <file>`::
   Ausgabedatei (Default `synopse.html`; `-` = Standardausgabe).
 `--vollstaendig`::
   Auch unveränderte Normen in die Synopse aufnehmen.
 `--artikel <n>`::
   Nur diesen Artikel des Änderungsgesetzes anwenden (Default: alle
   Artikel, deren Einleitung das Stammgesetz nennt).
 `--extract-only`::
   Nur den bereinigten Lineartext des Änderungsgesetzes ausgeben. Nützlich,
   wenn die PDF-Extraktion fehlerhaft ist: Text prüfen, von Hand
   korrigieren und als Klartextdatei wieder einspeisen.

 Erkannt werden die gebräuchlichsten Änderungsbefehle des Handbuchs der
 Rechtsförmlichkeit (Ersetzen, Neufassung, Einfügen, Anfügen, Aufheben,
 Streichen, Umnummerierung) einschließlich zahlreicher Sonderformen:
 Bereichs- und Koordinationsziele („Die Absätze 8 und 9 werden durch die
 folgenden Absätze 8 bis 10 ersetzt“), strukturelle Streichungen ganzer
 Einheiten („§ 9 wird gestrichen“), §- und Gliederungs-Umnummerierungen
 („§ 9a wird zu § 9“, „Der bisherige Abschnitt 2 wird zu Abschnitt 3“),
 das Einfügen/Ersetzen ganzer §-Blöcke, Chapeau-Lokatoren („Im
 Satzteil vor Nummer 1 …“), Änderungen an Anhängen und Anlagen („Der
 Anhang wird wie folgt geändert: … Nach Nummer 2 wird die folgende
 Nummer 2a eingefügt“), Angabe-Befehle auf die Inhaltsübersicht (gefasst,
 ersetzt, eingefügt, gestrichen — sie werden auf die
 Inhaltsübersichts-Norm angewandt), das Einfügen und Ersetzen von
 Gliederungs-Überschriften („Nach § 33 werden die folgenden Überschriften
 zu Teil 3 … eingefügt“), Voranstellungen, Mehrfach-Ersetzungs- und
 -Einfügepaare, Verbünde aus Umnummerierung und Folgeänderung („§ 50 wird
 zu § 38 und wird wie folgt geändert“) sowie die Neufassung der
 Gesetzesüberschrift. Die PDF-Aufbereitung toleriert dabei
 Drucksachen-Artefakte (Seitenköpfe und -füße, Vorabfassungs-Wasserzeichen,
 vertauschte oder gerade Anführungszeichen, verklebte Wortgrenzen) und
 bestimmt die Brotschrift seitenweise, sodass auch Ministeriumsentwürfe
 mit gemischten Layouts vollständig extrahiert werden. Auf den
 Beispieldaten werden damit alle Befehle der BGBl-Fassungen und der
 aktuellen Entwürfe angewandt (UWG/AGG/ProdHaftG: 0 manuell); was
 unsicher bleibt — etwa Befehle gegen eine ältere Gesetzesfassung, deren
 Zieltext nicht mehr existiert — landet mit Begründung im Abschnitt
 *Manuell prüfen* der Synopse und wird niemals stillschweigend verworfen.

 Für das bayerische Landesrecht versteht ÄndGgner die dortigen
 Konventionen: Stammgesetze gliedern sich in Artikel („Art. 6 Abs. 2
 Satz 1 Nr. 2“, durchgängig abgekürzt zitiert), Änderungsgesetze dagegen
 in Paragraphen — auch mehrere Gesetze in einem GVBl-Heft, aus denen die
 auf das Stammgesetz zielenden §§ (einschließlich „Weitere Änderung“)
 anhand des Einleitungssatzes ausgewählt werden. Amtliche Satznummern
 bleiben als Superskripte erhalten und dienen als exakte Satzgrenzen;
 zusätzlich erkannt werden die bayerischen Befehlsformen („Fußnote 1
 wird aufgehoben“, „In Satz 1 wird die Satznummerierung „1“ gestrichen“,
 „Dem Wortlaut werden die folgenden Abs. 1 bis 4 vorangestellt“, „Der
 bisherige Wortlaut wird Abs. 5“, Halbsatz-Ziele, Klauselketten mit
 gemeinsamem Schlussverb) sowie das Fortführungszeichen des GVBl (jedes
 neugefasste Aufzählungsglied öffnet erneut mit „). Meta-Änderungen an
 Drucksachen (Änderungsanträge des Landtags) sind bewusst noch nicht
 abgedeckt.


 == Running the Tests

 To build and run the tests:

 [source,shell script]
 ----
 ./mvnw verify
 ----
	= ÄndGgner -- Programmbibliothek zur Konsolidierung von Änderungsgesetzen des Bundes und der Länder
	Matthias Andreas Benkard
	// Meta
	:experimental:
	:data-uri:
	:sectnums:
	:toc:
	:stem:
	:toclevels: 2
	:description: ÄndGgner Manual
	:keywords: mulk
	// Settings
	:icons: font
	:source-highlighter: pygments


	== Resources

	\|===
	\|Resource \|Links

	\|Public Artifact
	\|https://bintray.com/mulk/maven/aendggner[Bintray]

	\|Bug Tracker
	\|MantisBT
	\|===


	[[building]]
	== Building a JAR

	To build an executable JAR at `target/aendggner-${REVISION}.jar`:

	[source,shell script]
	----
	./mvnw package
	----

	`${REVISION}` defaults to `0.1.0-SNAPSHOT` unless you override it by
	passing the `-Drevision` flag to `mvnw`.


	== Running the Command Line Application

	To run the command line application after <<building,building>> it:

	[source,shell script]
	----
	./mvnw exec:java
	----


	[[usage]]
	== Usage

	ÄndGgner erzeugt aus einem Stammgesetz und einem Änderungsgesetz eine
	zweispaltige HTML-Synopse (alte Fassung links, neue rechts, Änderungen
	wortweise hervorgehoben).

	Eingaben:

	* Stammgesetz (Bundesrecht): XML im gii-norm-Format von
	https://www.gesetze-im-internet.de/[gesetze-im-internet.de]
	* Stammgesetz (Landesrecht Bayern): konsolidierte Fassung von
	https://www.gesetze-bayern.de/[gesetze-bayern.de] als PDF oder als
	kanonischer Klartext im Format der `--extract-only`-Ausgabe; amtliche
	Satznummern und Fußnotenmarker stehen als Unicode-Superskripte im
	Text („¹Die freilebende Tierwelt …“, „Enteignung⁶)“)
	* Änderungsgesetz: BGBl-, GVBl- oder Drucksachen-PDF (Bundestag,
	Bundesrat, Bayerischer Landtag) oder Klartext

	[source,shell script]
	----
	java -jar target/aendggner-0.1.0-SNAPSHOT.jar \
	stammgesetz.xml aenderungsgesetz.pdf -o synopse.html
	----

	Wichtige Optionen:

	`-o, --output <file>`::
	Ausgabedatei (Default `synopse.html`; `-` = Standardausgabe).
	`--vollstaendig`::
	Auch unveränderte Normen in die Synopse aufnehmen.
	`--artikel <n>`::
	Nur diesen Artikel des Änderungsgesetzes anwenden (Default: alle
	Artikel, deren Einleitung das Stammgesetz nennt).
	`--extract-only`::
	Nur den bereinigten Lineartext des Änderungsgesetzes ausgeben. Nützlich,
	wenn die PDF-Extraktion fehlerhaft ist: Text prüfen, von Hand
	korrigieren und als Klartextdatei wieder einspeisen.

	Erkannt werden die gebräuchlichsten Änderungsbefehle des Handbuchs der
	Rechtsförmlichkeit (Ersetzen, Neufassung, Einfügen, Anfügen, Aufheben,
	Streichen, Umnummerierung) einschließlich zahlreicher Sonderformen:
	Bereichs- und Koordinationsziele („Die Absätze 8 und 9 werden durch die
	folgenden Absätze 8 bis 10 ersetzt“), strukturelle Streichungen ganzer
	Einheiten („§ 9 wird gestrichen“), §- und Gliederungs-Umnummerierungen
	(„§ 9a wird zu § 9“, „Der bisherige Abschnitt 2 wird zu Abschnitt 3“),
	das Einfügen/Ersetzen ganzer §-Blöcke, Chapeau-Lokatoren („Im
	Satzteil vor Nummer 1 …“), Änderungen an Anhängen und Anlagen („Der
	Anhang wird wie folgt geändert: … Nach Nummer 2 wird die folgende
	Nummer 2a eingefügt“), Angabe-Befehle auf die Inhaltsübersicht (gefasst,
	ersetzt, eingefügt, gestrichen — sie werden auf die
	Inhaltsübersichts-Norm angewandt), das Einfügen und Ersetzen von
	Gliederungs-Überschriften („Nach § 33 werden die folgenden Überschriften
	zu Teil 3 … eingefügt“), Voranstellungen, Mehrfach-Ersetzungs- und
	-Einfügepaare, Verbünde aus Umnummerierung und Folgeänderung („§ 50 wird
	zu § 38 und wird wie folgt geändert“) sowie die Neufassung der
	Gesetzesüberschrift. Die PDF-Aufbereitung toleriert dabei
	Drucksachen-Artefakte (Seitenköpfe und -füße, Vorabfassungs-Wasserzeichen,
	vertauschte oder gerade Anführungszeichen, verklebte Wortgrenzen) und
	bestimmt die Brotschrift seitenweise, sodass auch Ministeriumsentwürfe
	mit gemischten Layouts vollständig extrahiert werden. Auf den
	Beispieldaten werden damit alle Befehle der BGBl-Fassungen und der
	aktuellen Entwürfe angewandt (UWG/AGG/ProdHaftG: 0 manuell); was
	unsicher bleibt — etwa Befehle gegen eine ältere Gesetzesfassung, deren
	Zieltext nicht mehr existiert — landet mit Begründung im Abschnitt
	Manuell prüfen der Synopse und wird niemals stillschweigend verworfen.

	Für das bayerische Landesrecht versteht ÄndGgner die dortigen
	Konventionen: Stammgesetze gliedern sich in Artikel („Art. 6 Abs. 2
	Satz 1 Nr. 2“, durchgängig abgekürzt zitiert), Änderungsgesetze dagegen
	in Paragraphen — auch mehrere Gesetze in einem GVBl-Heft, aus denen die
	auf das Stammgesetz zielenden §§ (einschließlich „Weitere Änderung“)
	anhand des Einleitungssatzes ausgewählt werden. Amtliche Satznummern
	bleiben als Superskripte erhalten und dienen als exakte Satzgrenzen;
	zusätzlich erkannt werden die bayerischen Befehlsformen („Fußnote 1
	wird aufgehoben“, „In Satz 1 wird die Satznummerierung „1“ gestrichen“,
	„Dem Wortlaut werden die folgenden Abs. 1 bis 4 vorangestellt“, „Der
	bisherige Wortlaut wird Abs. 5“, Halbsatz-Ziele, Klauselketten mit
	gemeinsamem Schlussverb) sowie das Fortführungszeichen des GVBl (jedes
	neugefasste Aufzählungsglied öffnet erneut mit „). Meta-Änderungen an
	Drucksachen (Änderungsanträge des Landtags) sind bewusst noch nicht
	abgedeckt.


	== Running the Tests

	To build and run the tests:

	[source,shell script]
	----
	./mvnw verify
	----