Merge pull request #27 from hagbard/work

Better callouts.

docs/_config.yml

@@ -38,6 +38,30 @@ aux_links:
   Flogger Repository: https://github.com/google/flogger
   Example Code: https://github.com/hagbard/the-flogger-manual/tree/main/src/main/java/net/goui/flogger/examples
 
+# Copied from https://github.com/just-the-docs/just-the-docs/blob/main/_config.yml
+callouts_level: quiet # or loud (for dark theme)
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+  pros:
+    title: Pros
+    color: green
+  cons:
+    title: Cons
+    color: red
+
 # Exclude from processing.
 # The following items will not be processed, by default.
 # Any item listed under the `exclude:` key here will be automatically added to

docs/advanced.md

@@ -138,7 +138,7 @@ targeted debugging within a single execution of a task. Combined with the abilit
 per-invocation identifier via metadata, this lets you easily control logging to suit your
 debugging needs.
 
-> **Note**
+{: .important }
 > When a log statement if forced, it bypasses all rate limiting and sampling thresholds,
 > ensuring that every log statement encountered is emitted. This even applies to log
 > statements which would have been emitted normally anyway.

docs/background.md

@@ -42,7 +42,7 @@ The challenges for debug logging are no longer limited to locally run applicatio
 single machine. If debug logging is to remain a useful tool for developers, it needs to evolve to
 address this new world.
 
-> **Note**
+{: .note }
 > SLF4J introduced a "Flogger like" fluent API in version 2.0. This was directly inspired by
 > Flogger's API (and while this is un-acknowledged by the developers, it is
 > [obvious from the discussion and similarities in naming](https://github.com/qos-ch/slf4j/discussions/280)).
@@ -131,6 +131,7 @@ logger implementation, which either prevents easy code refactoring or discourage
 logging at all, but if loggers are created only in the class they are used in, it means they must
 have a low memory footprint per instance.
 
+{: .highlight }
 > Loggers should be thought of as "part of the environment" rather than "part of a system's API".
 
 Flogger also had to be performant in terms of speed and low memory allocations, since you could
@@ -151,6 +152,7 @@ allowed to cause more problems, and you cannot assume the user is able to recomp
 
 **However, one of the most compelling design requirements for any logging API is simplicity.**
 
+{: .highlight }
 > Almost nobody ever comes to their code in order to write great log statements.
 
 Log statements are not part of the business logic of the code they are in, they are mostly disabled
@@ -162,6 +164,7 @@ However, when logging is needed (e.g. during debugging) log output and the log s
 produced them must be reliable and easy to reason about. A user must be able to understand, at a
 glance, what a log statement will do and under what conditions they expect to see output.
 
+{: .highlight }
 > A user in the middle of debugging a serious issue should never also have to reason about some
 > subtle behaviour from their logging API.
 
@@ -190,7 +193,7 @@ loggers between classes is discouraged
 There's also no way to get a "name" for a logger as a user, it's just not a concept you should care
 about in code which is doing logging.
 
-> **Note**
+{: .highlight }
 > While the "name" of a logger is often the name of the class using it, that's not required for
 > Flogger, and a Flogger backend could even supply exactly the same logger for every call to
 > `forEnclosingClass()`, if configured to do so. The only thing you know is that the logger you've
@@ -208,7 +211,7 @@ For Flogger's fluent API, the basic construction is of the form:
 The `level-selector` (e.g. `atInfo()`) always comes first because that's where the logger can return
 a "no-op" instance of the API when logging is disabled by level.
 
-> **Note**
+{: .highlight }
 > Flogger's level selector methods are all prefixed with "at", rather than just
 > being `info()`, `warning()` etc. This serves two purposes; it makes the variable level selector
 > method `at(Level)` more discoverable, and it groups the levels together at the start of any API

docs/basic.md

@@ -33,8 +33,9 @@ logger.atInfo().log("Hello %s World", variable);
 ```
 <!-- @formatter:on -->
 
-> **Note**
-> The format syntax for `FluentLogger` is 100% compatible with Java's "printf" syntax.
+{: .note }
+> The format syntax for `FluentLogger` is 100% compatible with Java's "printf" syntax, but other
+> placeholder syntax is possible in custom loggers.
 
 Additionally, if you have a printf format message and argument array, you can call the
 `logVarargs()` method to format this directly. These API decisions are discussed in depth in
@@ -83,9 +84,10 @@ The difference between these methods can be summarized as follows:
 In all cases the number of log statements "skipped" since the previously emitted log message is
 tracked and added as metadata to each log statement.
 
-> **Warning**
+{: .important }
 > It is possible to combine multiple types of rate-limiting into a single log statement, and while
-> the behaviour is well-defined, it's not very intuitive. As such it's not recommended.
+> the behaviour is well-defined, it's not very intuitive and rarely useful. As such it's not 
+> recommended.
 
 ### When To Use Rate Limiting
 
@@ -134,8 +136,8 @@ its rate limit period. There are several reasons for this:
    will do. See [API Design Choices](background.md#api-design-choices) for more on Flogger's
    design principles.
 
-> **Note**
-> It's not impossible that a `Duration` based method could be added in the future, and this would
+{: .note }
+> It's quite possible that a `Duration` based method could be added in the future, and this would
 > help in the rare cases where a variable rate limit period is needed. However, even if such a
 > method existed, for most normal usage where the rate limit period is constant, the existing API
 > would still be strongly recommended.
@@ -213,18 +215,16 @@ logger.atFine().log("Expensive data: %s", lazy(() -> doExpensiveCalculation()));
 This wraps a `Runnable` or lambda into an instance of `LazyArg`, which can then be evaluated only
 when logging will definitely occur.
 
-**Pros:**
+{: .pros }
+> 1. It's concise and keeps everything in a single log statement.
+> 2. It avoids mismatched log levels in guarded blocks.
+> 3. **It works correctly for rate limited log statements** (because it is part of the log statement).
 
-1. It's concise and keeps everything in a single log statement.
-2. It avoids mismatched log levels in guarded blocks.
-3. **It works correctly for rate limited log statements** (because it is part of the log statement).
-
-**Cons:**
-
-1. It may (depending on the contents of the lambda) cause a small, short-lived allocation to be
-   made (e.g. if local variables need to be captured).
-2. If two or more pieces of logged data depend on each other, it may be impractical to evaluate them
-   independently using `lazy()`.
+{: .cons }
+> 1. It may (depending on the contents of the lambda) cause a small, short-lived allocation to be
+>    made (e.g. if local variables need to be captured).
+> 2. If two or more pieces of logged data depend on each other, it may be impractical to evaluate them
+>    independently using `lazy()`.
 
 While `lazy()` can cause small allocations to be made, it is better integrated with features like
 rate limiting, and will generally produce simpler and more maintainable code. In all but the

docs/index.md

@@ -1,7 +1,4 @@
 ---
-# Feel free to add content and custom Front Matter to this file.
-# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults
-
 layout: home
 ---
 

docs/install.md

@@ -44,7 +44,7 @@ This dependency will provide the logging API for use in libraries, application a
 ```
 <!-- @formatter:on -->
 
-> **Note**
+{: .note }
 > At the time of writing, the latest Flogger version is `0.7.4`.
 
 Adding these dependencies will install the core library and system backend, allowing you to write