📝 Update docs

docs/mkdocs.yml

@@ -141,10 +141,10 @@ markdown_extensions:
 nav:
   - Welcome: index.md
   - Getting started:
-      - getting-started/index.md
-      - Installation: getting-started/installation.md
+      - Introduction: getting-started/introduction.md
+      - Install: getting-started/install.md
       - Basic usages: getting-started/basic-usages.md
-      - Creating your logger: getting-started/creating-your-logger.md
+      - Creating your logger: getting-started/creating-custom-logger.md
   - Under the hood:
     - under-the-hood/index.md
     - Log severity levels: under-the-hood/log-severity-levels.md

docs/overrides/welcome.html

@@ -79,7 +79,7 @@
     }
 
     .custom-hero {
-        margin-top:10%;
+        margin-top:3%;
         margin-left:6%;
         margin-right:6%;
     }
@@ -116,7 +116,7 @@
             <div class="custom-hero-content">
                 <h1>Log smarter, debug faster in VBA</h1>
                 <p>{{ config.site_description }} Set up in two minutes.</p>
-                <a href="{{ 'getting-started/' | url }}" title="Set up in two minutes!" class="md-button md-button--primary">
+                <a href="{{ 'getting-started/introduction.html' | url }}" title="Set up in two minutes!" class="md-button md-button--primary">
                     Get started
                 </a>
                 <a href="{{ 'under-the-hood/' | url }}" title="To understand and learn what's happening with each compontents of this library" class="md-button">

docs/src/getting-started/basic-usages.md

@@ -1,44 +1,11 @@
-## Severity levels
 
-The severity levels indicate the severity of each event, from the most trivial to the most catastrophic, and allow administrators or developers to filter messages based on their importance.
 
-**VBA Monologger** manages 8 standard severity levels to classify the importance of log messages, following the [PSR-3](https://www.php-fig.org/psr/psr-3/) standard, which is itself based on RFC 5424, the standard defined by the IETF (*Internet Engineering Task Force*) to specify the format of messages for the Syslog protocol, which is used for transmitting logs over IP networks.
-
-| Log level   | Description                                                                                                                                                                                                                               |
-|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `EMERGENCY` | Indicates a very critical situation that requires immediate attention. (System crash, data corruption)                                                                                                                                    |
-| `ALERT`     | Signals an alert condition. (Critical disk space running out)                                                                                                                                                                             |
-| `CRITICAL`  | Indicates a serious error. (Database connection failure, server downtime)                                                                                                                                                                 |
-| `ERROR`     | Represents an error in the system. (Failed to save user data, unexpected exception)                                                                                                                                                       |
-| `WARNING`   | A warning about a potential problem. (Use a deprecated function used, low memory warning)                                                                                                                                                 |
-| `NOTICE`    | Important notifications that are not urgent. (User login successful, configuration change detected)                                                                                                                                       |
-| `INFO`      | General information about the normal operation. (System startup, data processed successfully)                                                                                                                                             |
-| `DEBUG`     | Detailed information for debugging. (Variable values during loop iteration, query execution details). Notes, that the '**debug**' method exposes presents in PSR-3 is rename into '**trace**' in order to be compatible in VBA ecosystem. |
-
-Each logger must implement hte interface `LoggerInterface`. ' This interface is (*supposed to be*) designed according to the PSR-3 standard (see: https://www.php-fig.org/psr/psr-3/), and exposed this methods:
-
-```vbscript
-' Logs message for each severity levels
-Logger.trace "Authentication function call for user 'Bob Morane'." 
-Logger.info "User 'UltraVomit' has logged in successfully."
-Logger.notice "Process completed successfully with minor issues."
-Logger.warning "'Beetlejuice' should not be called more than 3 times."
-Logger.error "An error occurred with the user 'DRZCFOS2'."
-Logger.critical "System is in an unstable state."
-Logger.alert "Action required: unable to generate the dashboard."
-Logger.emergency "A critical failure occurred in the application."
-```
-
-
-
-## Create default logger with factory
+## Create default loggers with factory
 
 ### Log output to VBA Console
 
 To create a logger that output logs into the VBA console, we use the factory `VBAMonologger.Factory`, as shown below. 
 
-This logger is configured by default with the handler `VBAMonologger.Handler.HandlerConsoleVBA`, which uses the default line formatter: `VBAMonologger.Formatter.FormatterLine`. By default, this logger also loads the pre-processors placeholders: `VBAMonologger.Processor.ProcessorPlaceholders`, allowing the use of placeholders in log messages that will be replaced with values provided in the log record context.
-
 ```vbscript
 Public Sub howto_use_loggerConsoleVBA()
     ' Create a logger instance for output log into VBA console
@@ -61,14 +28,14 @@ You can see result in the **VBA console** (a.k.a. **Excel's Immediate Windows**)
 
 ![VBAMonologger-output-VBAConsole.png](VBAMonologger-output-VBAConsole.png)
 
-> Note: If the console is not visible in Excel Visual basidc IDE, go to the menu and select *View > Immediate Window*. Alternatively, you can press <kbd>Ctrl</kbd> + <kbd>G</kbd> to quickly open it.
+> Note: If the console is not visible in Excel Visual basic IDE, go to the menu and select *View > Immediate Window*. Alternatively, you can press <kbd>Ctrl</kbd> + <kbd>G</kbd> to quickly open it.
 
+This logger is configured by default with the handler `VBAMonologger.Handler.HandlerConsoleVBA`, which uses the default line formatter: `VBAMonologger.Formatter.FormatterLine`. This logger also loads the pre-processors placeholders: `VBAMonologger.Processor.ProcessorPlaceholders`, allowing the use of placeholders in log messages that will be replaced with values provided in the log record context.
 
-### Log output to Windows Console
 
-The factory also provides a logger for Windows console (*cmd.exe*). 
+### Log output to Windows Console
 
-This logger handles log messages by streaming them to the Windows console using an HTTP-based client/server architecture. The client sends log entries as HTTP requests to the server, and the server processes these requests, displaying the log messages directly in the console output. By default, this logger features a formatter that supports ANSI colors (`VBAMonologger.Formatter.FormatterANSIcoloredLine`). It also includes the *placeholders* pre-processors.
+The factory also provides a logger for Windows console (*cmd.exe*). It handles log messages by streaming them to the Windows console using an HTTP-based client/server architecture. The client sends log records as HTTP requests to the server, and the server processes these requests, displaying the log messages directly in the console output. This logger features a formatter that supports ANSI colors (`VBAMonologger.Formatter.FormatterANSIcoloredLine`), and like the VBA console logger, it also includes the *placeholders* pre-processors.
 
 ```vbscript
 Public Sub howto_use_loggerConsole()
@@ -80,7 +47,7 @@ Public Sub howto_use_loggerConsole()
 End Sub    
 ```
 
-When you execute this code, it launches a `cmd.exe`, and you can view the results in it.
+When you execute this code, it launches a `cmd.exe`, and you can view the results in it. The formatter's configuration allows you to customize the color scheme.
 
 ![VBAMonologger-output-WindowsConsole.png](VBAMonologger-output-WindowsConsole.png)
 

docs/src/getting-started/creating-custom-logger.md

@@ -0,0 +1,82 @@
+
+
+### Create a custom logger from scratch
+
+In this example, we create an empty logger, and we push into multiples handlers with differnts formatters.
+    - a handler for ouptut log into console VBA
+    - a handler for ouptut log into console
+    - a handler for ouptut log into file only for error log records (level >= error)
+
+```vbscript
+Public Sub howto_create_a_custom_Logger_from_scratch()
+    Dim customLogger As VBAMonologger.Logger
+    Set customLogger = VBAMonologger.Factory.createLogger
+
+    ' Create a custom line formatter
+    Dim customFormatterLine As VBAMonologger.FormatterLine
+    Set customFormatterLine = VBAMonologger.Factory.createFormatterLine
+    customFormatterLine.showContext = True
+    customFormatterLine.showExtra = True
+    customFormatterLine.withAllowingInlineLineBreaks = False
+    customFormatterLine.templateLine = ":: {{ channel }}{{ level_name }} - {{ message }}"
+
+    ' Add a custom console VBA handler (use custom formatter)
+    Dim customHandlerConsoleVBA As VBAMonologger.HandlerConsoleVBA
+    Set customHandlerConsoleVBA = VBAMonologger.Factory.createHandlerConsoleVBA
+    Set customHandlerConsoleVBA.formatter = customFormatterLine
+    customLogger.pushHandler customHandlerConsoleVBA
+
+    ' Add a custom console handler (use default formatter with ANSI support)
+    Dim customHandlerConsole As VBAMonologger.HandlerConsole
+    Set customHandlerConsole = VBAMonologger.Factory.createHandlerConsole
+    customHandlerConsole.portServer = 20101
+    customHandlerConsole.hostnameServer = "127.0.0.1"
+    customHandlerConsole.withANSIColorSupport = True
+    customHandlerConsole.withDebug = False
+    customHandlerConsole.withNewlineForContextAndExtra = True
+    customHandlerConsole.startServerLogsViewer
+    customLogger.pushHandler customHandlerConsole
+
+    ' Add a custom file handler (use a custom formatter and capture only error log records, i.e. with level >= LEVEL_ERROR)
+    Dim customHandlerFile As VBAMonologger.handlerFile
+    Set customHandlerFile = VBAMonologger.Factory.createHandlerFile
+    customHandlerFile.logFileName = "error_" & Format(Now, "yyyy-mm-dd") & ".log"
+    customHandlerFile.logFileFolder = ThisWorkbook.Path & "\logs"
+    customHandlerFile.Level = LEVEL_ERROR
+    Dim formatter As VBAMonologger.FormatterLine
+    Set formatter = customHandlerFile.formatter
+    formatter.setTemplateLineWithNewlineForContextAndExtra
+    formatter.withWhitespace = True
+    formatter.withAllowingInlineLineBreaks = True
+    customLogger.pushHandler customHandlerFile
+
+    ' Add pre-processors
+    VBAMonologger.Factory.pushProcessorPlaceholders customLogger
+    VBAMonologger.Factory.pushProcessorUID customLogger, 8
+    VBAMonologger.Factory.pushProcessorUsageCPU customLogger
+    VBAMonologger.Factory.pushProcessorUsageMemory customLogger
+    Dim tags As Object
+    Set tags = CreateObject("Scripting.Dictionary")
+    tags.Add "environment", "production"
+    VBAMonologger.Factory.pushProcessorTags customLogger, tags, TAGS_DESTINATION.LOG_EXTRA
+
+    ' Use the custom logger
+    customLogger.trace "Authentication function call for user 'Bob Morane'." ' The 'debug' method exposes presents in PSR-3 is rename into 'trace' in order to be compatible in VBA ecosystem
+    customLogger.info "User 'Ultra Vomit' has logged in successfully."
+    customLogger.notice "Process completed successfully with minor issues."
+    customLogger.warning "The user 'Beetlejuice' should not be called more than 3 times."
+    customLogger.Error "An error occurred when the user 'DeadRobotZombieCopFromOuterspace' tried to read the dashboard file."
+    customLogger.critical "System is in an unstable state. Unable to authenticate the user 'Skjalg Skagen'."
+    customLogger.alert "Action required: unable to generate the dashboard."
+    customLogger.emergency "A critical failure occurred in the application for moving files."
+
+    Dim context As Object: Set context = CreateObject("Scripting.Dictionary")
+    context.Add "UserName", "Bob Morane"
+    context.Add "UserID", 342527
+    customLogger.trace "Authentication function call for user '{UserName}' with id '{UserID}'.", context
+    customLogger.Error "User id '{UserID}' does not exist. Unable to create dashboard file.", context
+End Sub
+```
+
+![VBAMonologger-multiples-handlers.png](VBAMonologger-multiples-handlers.png)
+

docs/src/getting-started/index.md

@@ -4,11 +4,3 @@ hide:
 ---
 
 # Getting started
-
-## Preamble
-
-VBA provides developers with the ability to automate tasks, interact with the features of
-Microsoft Office applications, and even create applications with a graphical user interface (`Userform`). However, compared to other development ecosystems, VBA only offers a rudimentary logging solution, limited to the `Debug.Print` function, which writes to the Excel console (a.k.a. the Excel immediate window).
-
-The *VBA Monologger* library project was born out of the need for a more advanced and flexible logging solution in the VBA ecosystem. It is (heavily) inspired by the PSR-3 standard in the PHP ecosystem and its most recognized implementation, the Monolog library. The goal of this library is to provide similar features and capabilities, particularly by offering a modular architecture that can easily adapt to different use cases. The main idea is for each developer to easily configure and customize their own logging system according to their needs.
-

docs/src/getting-started/installation.md → docs/src/getting-started/install.md

@@ -1,4 +1,4 @@
-## Installation
+## Manual installation
 
 1. Download the VBA Monologger Excel Add-in (.xlam file) to your computer.
 
@@ -18,4 +18,15 @@
     <br/>
     ![excel_reference_vbamonologger.png](excel_reference_vbamonologger.png)
 
-That's it. Time to code with it!
+That's it.
+
+
+
+## Setup wizard installation (*as soon as possible*)
+
+In the future, we plan to introduce a setup wizard to simplify the deployment of VBA add-ins using [InnoSetup](https://jrsoftware.org/isinfo.php). 
+
+This setup will place the VBA Monologger `.xlam` file into the standard folder for Excel add-ins: `C:\Users\[name]\AppData\Roaming\Microsoft\AddIns\`. And after, it will automatically activate in Excel by updating the Windows Registry.
+
+> See : https://github.com/6i-software/deploy-microsoft-office-extensions  
+