From: Alexander Kriegisch <Alexander@Kriegisch.name>
Date: Wed, 3 Jan 2024 07:05:32 +0000 (+0700)
Subject: Adjust design overview docs to other multi-page docs
X-Git-Tag: V1_9_21_1~71
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=ac71008e59b83d24ec5985e9e557c5cc6bd84c00;p=aspectj.git

Adjust design overview docs to other multi-page docs

- Link to other pages in index.adoc
- Include other pages in design-overview.adoc

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
---

diff --git a/docs/developer/design-overview.adoc b/docs/developer/design-overview.adoc
new file mode 100644
index 000000000..ee3bd755e
--- /dev/null
+++ b/docs/developer/design-overview.adoc
@@ -0,0 +1,30 @@
+= AspectJ Design Overview
+:doctype: book
+
+Here are some sobering words:
+
+"Although it is essential to upgrade software to prevent aging, changing software can cause a different form of
+aging. The designer of a piece of software usually had a simple concept in mind when writing the program. If the
+program is large, understanding the concept allows one to find those sections of the program that must be altered
+when an update or correction is needed. Understanding that concept also implies understanding the interfaces used
+within the system and between the system and its environment.  Changes made by people who do not understand the
+original design concept almost always cause the structure of the program to degrade. Under those circumstances,
+changes will be inconsistent with the original concept; in fact, they will invalidate the original concept. Sometimes
+the damage is small, but often it is quite severe. After those changes, one must know both the original design rules
+and the newly introduced exceptions to the rules, to understand the product. After many such changes, the original
+designers no longer understand the product. Those who made the changes, never did. In other words, *nobody*
+understands the modified product." +
+ +
+Software that has been repeatedly modified (maintained) in this way becomes very expensive to update. Changes take
+longer and are more likely to introduce new 'bugs'."
+-- David Parnas on "Ignorant Surgery" in his paper on Software Aging
+
+////
+ATTENTION: Please do not remove blank lines in between 'include::' statements. Otherwise, section numbers in the
+table of contents (TOC) can be wrong and the first section of each document missing completely.
+////
+include::compiler-weaver/index.adoc[Guide for Developers of the AspectJ Compiler and Weaver]
+
+include::modules.adoc[Module Structure]
+
+include::language.adoc[Language Design]
diff --git a/docs/developer/index.adoc b/docs/developer/index.adoc
index aa347182e..a358948b3 100644
--- a/docs/developer/index.adoc
+++ b/docs/developer/index.adoc
@@ -19,6 +19,8 @@ Software that has been repeatedly modified (maintained) in this way becomes very
 longer and are more likely to introduce new 'bugs'."
 -- David Parnas on "Ignorant Surgery" in his paper on Software Aging
 
-include::compiler-weaver/index.adoc[Guide for Developers of the AspectJ Compiler and Weaver]
-include::modules.adoc[Module Structure]
-include::language.adoc[Language Design]
+**Table of Contents**
+
+* xref:compiler-weaver/index.adoc[Guide for Developers of the AspectJ Compiler and Weaver]
+* xref:modules.adoc[Module Structure]
+* xref:language.adoc[Language Design]