Expand doc

cider-log.el

@@ -1417,7 +1417,7 @@ the CIDER Inspector and the CIDER stacktrace mode.
 ;;;###autoload
 (defun cider-log-show ()
   "Ensures the *cider-log* buffer is visible,
-setting up an appender and consumer if necessary.
+setting up a framework, appender and consumer if necessary.
 
 Honors the `cider-log-framework-name' customization variable.
 

doc/modules/ROOT/pages/debugging/logging.adoc

@@ -3,7 +3,7 @@
 
 CIDER Log Mode allows you to capture, debug, inspect and view log
 events emitted by Java logging frameworks. The captured log events can
-be searched, streamed to the client, pretty printed and are integrated
+be searched, streamed to the client, pretty-printed, and are integrated
 with the CIDER link:inspector.html[Inspector] and
 link:../usage/dealing_with_errors.html[Stacktrace Mode]. Here is a
 screenshot of CIDER Log Mode in action.
@@ -20,34 +20,76 @@ logging related actions.
 
 == Features
 
-- Browse Javadocs and website of log framework.
+- Browse Javadocs and website of the given log framework.
 - Search log events and show them in buffers.
-- link:../usage/pretty_printing.html[Pretty Print] log events.
-- Show log events in the CIDER link:inspector.html[Inspector]
-- Show log event exceptions in the CIDER link:../usage/dealing_with_errors.html[Stacktrace Mode]
-- Integration with https://github.com/doublep/logview[logview]
+- link:../usage/pretty_printing.html[Pretty-print] log events.
+- Show log events in the CIDER link:inspector.html[Inspector].
+- Show log event exceptions in the CIDER link:../usage/dealing_with_errors.html[Stacktrace Mode].
+- Integration with https://github.com/doublep/logview[logview].
 
 == Dependencies
 
 https://github.com/doublep/logview[Logview] is an optional dependency
 of CIDER Log Mode. We recommend using it, since it is responsible for
 coloring the log events and it provides other useful features, such as
 syntax highlighting, filtering and more. It is used automatically when
-available and its use can be customized via `cider-log-use-logview`.
+available, and its use can be customized via `cider-log-use-logview`.
 
 == Usage
 
-To use CIDER Log Mode, type kbd:[C-c M-l l] or kbd:[M-x cider-log] in
-any buffer that has a CIDER https://github.com/vspinu/sesman[Sesman]
-session attached to it. The first time you run the command, it will
+To use CIDER Log Mode, there are a few ways to get started:
+
+* Traditionally, `M-x cider-log` has been considered the main entrypoint, although it can be slightly low-level for casual usage.
+* `M-x cider-log-event` improves upon the default experience of `M-x cider-log`. It also uses transient-mode and will not immediately show the logs (you should use transient-mode to show the `*cider-log*` buffer)
+* `M-x cider-log-show` is a newer function that intends to be an "all-in-one" command, intended for a streamlined experience, which can be useful to get started, or for casual usage.
+  * It doesn't use transient-mode - it aims to do everything in one step
+  * It immediately shows the `*cider-log*` buffer
+  * You can refine its setup by running `M-x cider-log` afterwards.
+
+NOTE: any of the three commands will only succeed in
+a buffer that has a CIDER repl (https://github.com/vspinu/sesman[Sesman]
+session) attached to it.
+
+=== Via `cider-log-show`
+
+By using `M-x cider-log-show`, all setup and rendering will be performed for you in a single step that doesn't pop up a `transient-mode` menu:
+
+* A framework will be set up, automatically
+  * You may be prompted for a framework
+  * You can prevent the prompt by customizing `cider-log-framework-name` (best done in `dir-locals.el`)
+* A log appender and a log consumer will be setup, automatically
+* The `*cider-log*` buffer will be rendered.
+
+All these steps are idempotent, so it's safe to run `M-x cider-log-show` more than once.
+
+You can refine the setup afterwards (e.g. configuring filtering) by running `M-x cider-log`.
+
+=== Via `cider-log-event`
+
+The intended workflow for this function is as follows:
+
+* Run `M-x cider-log-event`
+* A framework will be set up, automatically
+  * You may be prompted for a framework
+  * You can prevent the prompt by customizing `cider-log-framework-name` (best done in `dir-locals.el`)
+* A log appender and a log consumer will be setup, automatically
+* The `*cider-log*` buffer will _not_ be rendered
+  * For it to be rendered, press `s` (`Search log events`) within the transient-mode menu.
+
+=== Via `cider-log`
+
+type kbd:[C-c M-l l] or kbd:[M-x cider-log]. The first time you run the command, it will
 prompt you to select a log framework to use, and then attach a log
 appender to the root logger of the selected framework. After the log
 appender has been attached, the `cider-log` command will show a
 https://www.gnu.org/software/emacs/manual/html_mono/transient.html[Transient]
 menu, from which you can take further actions, like managing the log
 framework, appenders, consumers and events.
 
-To view log events and stream them to your client, type kbd:[es]
+You should add a log appender, and a log consumer, at this point - else no log entries will be possibly shown
+(which is why `cider-log` is considered a lower-level workflow).
+
+After that, to view log events and stream them to your client, type kbd:[es]
 (Search log events) followed by kbd:[s]. This will open the
 `+*cider-log*+` buffer showing any log events captured thus far. It will
 also add a log consumer to this buffer, which receives newly-arriving
@@ -88,7 +130,7 @@ the selected framework.
 == Log framework
 
 CIDER Log Mode supports log frameworks that allow reconfiguration at
-run time. More specifically the framework should support attaching log
+runtime. More specifically the framework should support attaching log
 appenders to loggers, in order to capture events.
 
 At the moment the following log frameworks are supported:
@@ -103,6 +145,15 @@ https://stackoverflow.com/a/17842174/12711900[difficulties] with
 configuration changes made at runtime, which are wiped out by the
 Log4j2 reconfiguration mechanism.
 
+Timbre support is WIP as well.
+
+TIP: If your logging framework of choice is not currently supported by CIDER Log Mode,
+you can opt to use Clojure's official `tools.logging` façade in your project, such that you can locally,
+unobstrusively tell it to use a supported framework (like Logback) instead of your project's default one.
+Note that `tools.logging`'s choice of logging backend implementation can be controlled with the
+`-Dclojure.tools.logging.factory` Java system property, which can be cleanly customized locally via Lein profiles,
+or Clojure CLI aliases.
+
 === Keybindings
 
 |===