General improvements. (#41)

* Add bare minimum docs for Flogger Next. * Snapshot to add Flogger Next stuff. * Convert to new namepsace for Flogger Next. * Update version and tidy. * Flatten structure and fix links. * Better install docs. * Fixing table of contents layout.
hagbard · May 3, 2024 · fa9327e · fa9327e
1 parent 16a8c43
commit fa9327e
Show file tree

Hide file tree

Showing 13 changed files with 184 additions and 126 deletions.
diff --git a/docs/advanced.md b/docs/advanced.md
@@ -4,16 +4,16 @@ title: Advanced Usage
 nav_order: 30
 ---
 
+<!-- @formatter:off -->
 # Advanced Usage
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
 
-<details open markdown="block">
-  <summary>
-    Table of contents
-  </summary>
-  {: .text-delta }
 - TOC
 {:toc}
-</details>
+<!-- @formatter:on -->
 
 For working code examples for advanced usage,
 see [AdvancedExamples.java]({{site.examples}}/AdvancedExamples.java).

diff --git a/docs/background.md b/docs/background.md
@@ -4,16 +4,16 @@ title: Background
 nav_order: 110
 ---
 
+<!-- @formatter:off -->
 # Background
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
 
-<details open markdown="block">
-  <summary>
-    Table of contents
-  </summary>
-  {: .text-delta }
 - TOC
 {:toc}
-</details>
+<!-- @formatter:on -->
 
 ## Motivation and History {#motivation-and-history}
 

diff --git a/docs/basic.md b/docs/basic.md
@@ -4,16 +4,16 @@ title: Basic Usage
 nav_order: 20
 ---
 
+<!-- @formatter:off -->
 # Basic Usage
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
 
-<details open markdown="block">
-  <summary>
-    Table of contents
-  </summary>
-  {: .text-delta }
 - TOC
 {:toc}
-</details>
+<!-- @formatter:on -->
 
 For working code examples for basic usage,
 see [BasicExamples.java]({{site.examples}}/BasicExamples.java).

diff --git a/docs/debugging.md b/docs/debugging.md
@@ -4,16 +4,16 @@ title: "Debugging With Flogger"
 nav_order: 45
 ---
 
+<!-- @formatter:off -->
 # Debugging With Flogger
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
 
-<details open markdown="block">
-  <summary>
-    Table of contents
-  </summary>
-  {: .text-delta }
 - TOC
 {:toc}
-</details>
+<!-- @formatter:on -->
 
 ## Logging Configuration And Debugging
 

diff --git a/docs/design.md b/docs/design.md
@@ -4,16 +4,16 @@ title: Flogger Design
 nav_order: 100
 ---
 
+<!-- @formatter:off -->
 # Flogger Design
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
 
-<details open markdown="block">
-  <summary>
-    Table of contents
-  </summary>
-  {: .text-delta }
 - TOC
 {:toc}
-</details>
+<!-- @formatter:on -->
 
 ## Log Statement Flow
 

diff --git a/docs/flogger_next.md b/docs/flogger_next.md
@@ -4,16 +4,16 @@ title: "Flogger Next"
 nav_order: 50
 ---
 
+<!-- @formatter:off -->
 # Flogger Next
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
 
-<details open markdown="block">
-  <summary>
-    Table of contents
-  </summary>
-  {: .text-delta }
 - TOC
 {:toc}
-</details>
+<!-- @formatter:on -->
 
 ## What is Flogger Next?
 
@@ -22,9 +22,10 @@ and provide improved integration with the underlying logging system. If provides
 replacement [`FluentLogger`]({{site.next.FluentLogger}}) implementation with additional features as
 well as new backend implementations and features.
 
-## Efficient log statements with String Template syntax
+## String Template Syntax Integration
 
-Utilize Java's new `StringTemplate` syntax to improve readability of your log statements.
+Utilize Java's new `StringTemplate` syntax to improve readability of your log statements (JDK 21
+and above).
 
 <!-- @formatter:off -->
 ```java
@@ -53,7 +54,7 @@ logger.atFine()."Statistics: \{ lazy(() -> this.collectStatsExpensive()) }".log(
 
 See [String Templates](templates) for more.
 
-## Improved log messages with custom formatter options
+## Custom Log Message Formatting
 
 Replace Flogger's original, fixed, message format with a flexible new formatter.
 
@@ -76,7 +77,7 @@ com.foo.bar.MyClass#myMethod (task@1234) My log message
 
 See [Custom Formating](formatter) for more.
 
-## Reduce class initialization costs by sharing logger backends
+## Reduce Class Initialization Costs
 
 Instead of allocating one logger backend for each Fluent logger instance, share backends between
 classes with the same logging requirements.
@@ -98,4 +99,3 @@ object allocations and class initialization cost.
 > APIs which make up for this.
 
 See [Backend Naming](backend) for more.
-
diff --git a/docs/index.md b/docs/index.md
@@ -2,7 +2,16 @@
 layout: home
 ---
 
+<!-- @formatter:off -->
 # The Flogger Manual
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+- TOC
+{:toc}
+<!-- @formatter:on -->
 
 [Flogger](https://github.com/google/flogger) is Google's open-source Java debug logging library.
 

diff --git a/docs/install.md b/docs/install.md
@@ -4,16 +4,16 @@ title: Installing Flogger
 nav_order: 10
 ---
 
+<!-- @formatter:off -->
 # Installing Flogger
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
 
-<details open markdown="block">
-  <summary>
-    Table of contents
-  </summary>
-  {: .text-delta }
 - TOC
 {:toc}
-</details>
+<!-- @formatter:on -->
 
 ## Maven Dependencies
 

diff --git a/docs/next_backend.md b/docs/next_backend.md
@@ -4,16 +4,16 @@ title: "Next: Backend Naming"
 nav_order: 54
 ---
 
+<!-- @formatter:off -->
 # Backend Naming
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
 
-<details open markdown="block">
-  <summary>
-    Table of contents
-  </summary>
-  {: .text-delta }
 - TOC
 {:toc}
-</details>
+<!-- @formatter:on -->
 
 ## Introduction
 
@@ -331,16 +331,20 @@ See [Debugging With Flogger](debugging) for more.
 
 ## Installation
 
+JDK logging backend (replaces the `com.google.flogger:flogger-system-backend` dependency):
+
 <!-- @formatter:off -->
 ```xml
 <dependency>
-    <groupId>net.goui.flogger.next</groupId>
-    <artifactId>backend-system</artifactId>
-    <version>${flogger-next.version}</version>
+  <groupId>net.goui.flogger.next</groupId>
+  <artifactId>backend-system</artifactId>
+  <version>${flogger-next.version}</version>
 </dependency>
 ```
 <!-- @formatter:on -->
 
+Log4J 2 backend (replaces the `com.google.flogger:flogger-log4j2-backend` dependency):
+
 <!-- @formatter:off -->
 ```xml
 <dependency>