AsciiDoc: updates in main index and FAQ (WIP)

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

2 files changed, 12 insertions, 13 deletions

diff --git a/docs/dist/doc/README-11.adoc b/docs/dist/doc/README-11.adoc
index cd744c343..d846cff81 100644
--- a/docs/dist/doc/README-11.adoc
+++ b/docs/dist/doc/README-11.adoc
@@ -255,8 +255,7 @@ the batch-build mode of the new compiler.
 The AspectJ tools sources are available under the
 https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt[Eclipse Public
 License v 2.0] in the Git repository at https://eclipse.org/aspectj. For
-more information, see the FAQ entry on
-faq.html#q:buildingsource[building sources].
+more information, see the FAQ entry on building sources.
 
 '''''
 
diff --git a/docs/dist/doc/index.adoc b/docs/dist/doc/index.adoc
index 35ac9dfb9..3e838031f 100644
--- a/docs/dist/doc/index.adoc
+++ b/docs/dist/doc/index.adoc
@@ -3,8 +3,8 @@
 
 AspectJ^TM^ is a seamless aspect-oriented extension to
 Java^TM^. The compiler and development tools are available
-under an open-source license, require Java 1.3 to run, and produce code
-that runs in JDK 1.1 and later VM's. For the latest materials, see
+under an open-source license, require Java 8 to run, and produce code
+that runs in JDK 1.3 and later VM's. For the latest materials, see
 https://eclipse.org/aspectj. Not all of these materials have been updated
 for AspectJ 5.
 
@@ -12,7 +12,7 @@ for AspectJ 5.
 |===
 |+++Section+++ |+++Contents+++
 
-|xref:#documentation[docs] |xref:../../faq/faq.adoc#faq[FAQ], link:quick5.pdf[Quick
+|xref:#documentation[Documentation] |xref:../../faq/faq.adoc#faq[FAQ], link:quick5.pdf[Quick
 Reference (AspectJ 5)], link:quick.pdf[Quick Reference (1.2.1)],
 xref:../../adk15ProgGuideDB/adk15notebook.adoc[AspectJ 5 Developer's Notebook],
 link:progguide/index.html[programming],
@@ -20,17 +20,17 @@ link:devguide/index.html[development] and
 link:pdguide/index.html[problem diagnosis] guides,
 link:runtime-api/index.html[API] and link:examples/[example code].
 
-|xref:#distributions[distributions]
+|xref:#distributions[Distributions]
 |https://eclipse.org/aspectj[AspectJ]; development environment support
 for https://eclipse.org/ajdt[Eclipse].
 
-|xref:#resources[resources] |http://aosd.net[aosd.net];
+|xref:#resources[Other resources] |http://aosd.net[aosd.net];
 https://eclipse.org/aspectj[AspectJ project] the bug
 https://bugs.eclipse.org/bugs[db], and mailing lists for
 mailto:aspectj-users@eclipse.org[users] and
 mailto:aspectj-dev@eclipse.org[developers].
 
-|xref:#paths[paths] |for those new to AspectJ
+|xref:#paths[Learning paths] |for those new to AspectJ
 |===
 
 [[documentation]]
@@ -45,14 +45,14 @@ reference for the AspectJ 5 language.
 |link:quick.pdf[AspectJ Quick Reference] |This is a two-page quick
 reference for the AspectJ language.
 
-|xref:../../adk15ProgGuideDB/adk15notebook.adoc[AspectJ 5 Developer's Notebook]
+|xref:../../adk15ProgGuideDB/adk15notebook.adoc[AspectJ 5 Developer's Notebook] +
 (printable link:adk15notebook/printable.html[html]) |This describes the
 changes to the AspectJ language and tools introduced in the AspectJ 5
 Development Kit. These changes are additive, and are not yet reflected
 in the programming guide or quick reference.
 
-|link:progguide/index.html[Programming Guide] (printable
-link:progguide/printable.html[html]) |This introduces AOP and the
+|link:progguide/index.html[Programming Guide] +
+(printable link:progguide/printable.html[html]) |This introduces AOP and the
 AspectJ language. link:progguide/starting.html[Getting Started]
 describes basic semantics, and shows development- and production-time
 applications. link:progguide/language.html[The AspectJ Language]
@@ -136,7 +136,7 @@ as the documentation and examples.
 AspectJ is available under the open-source
 https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt[Eclipse Public
 License v 2.0] license from the Git repositories for the AspectJ
-project. See the faq.html#q:buildingsource[FAQ entry].
+project. See the xref:../../faq/faq.adoc#buildingsource[FAQ entry].
 
 |https://eclipse.org/ajdt[AspectJ for Eclipse] |AspectJ Development
 Environment support for Eclipse is available under Eclipse Public
@@ -183,7 +183,7 @@ for general AOSD discussions.
 |===
 
 [[paths]]
-=== Suggested paths for those new to AspectJ
+=== Suggested learning paths for those new to AspectJ
 
 To learn the AspectJ language, read the
 link:progguide/index.html[Programming Guide], keeping the