Add FAQ to docs

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 3.0.2
 
-_Released 2024-xx-xx_
+_Released 2024-11-xx_
 
  * Fix formatting options of user-defined types sometimes being ignored
  * Fix build failures on Emscripten

docs/CMakeLists.txt

@@ -23,8 +23,10 @@ add_custom_command(
         OUTPUT "${CMAKE_CURRENT_LIST_DIR}/html"
         MAIN_DEPENDENCY "${CMAKE_CURRENT_LIST_DIR}/poxy.toml"
         DEPENDS
+            "${CMAKE_CURRENT_LIST_DIR}/pages/faq.md"
             "${CMAKE_CURRENT_LIST_DIR}/pages/guide.md"
             "${CMAKE_CURRENT_LIST_DIR}/pages/mainpage.md"
+            "${CMAKE_CURRENT_LIST_DIR}/script/monospace-headers.js"
             "${SCN_ABSOLUTE_PUBLIC_HEADERS}"
         COMMENT "Generating docs"
         VERBATIM)

docs/pages/faq.md

@@ -0,0 +1,30 @@
+\page faq FAQ
+\tableofcontents
+
+\section faq-1 Why doesn't `scn::scan(input, "{},{}")` work?
+
+The format string given to `scn::scan` is not a pattern, or a regular expression.
+Instead, not unlike `std::scanf`, the format string is evaluated left-to-right,
+and each replacement field (`{}`) is scanned based on the rules given
+by the type to be scanned, and the options inside the replacement field.
+
+For example, `scn::scan<std::string, std::string>(input, "{},{}")` means:
+ 1. scan a `string` with default options (empty replacement field `{}`),
+    which means to scan until whitespace
+ 2. scan a literal <code>','</code> character, and discard it
+ 3. scan another `string`, again with default options
+
+Compare this with a call to `scanf`, with the same behavior
+(discounting buffer overflow prevention):
+`std::sscanf(input, "%s,%s", output1, output2)`.
+
+To reiterate,
+the way values are scanned is only influenced by the type of the value to be scanned,
+and the options given in the replacement field (inside the `{}`).
+The context around the replacement field in the format string is not considered.
+
+To scan until a <code>','</code>, one can do:
+`scn::scan<std::string, std::string>("{:[^,]},{}")`.
+The `[^,]` in the formatting options for the first argument modifies the scanning behavior to
+accept all characters except <code>','</code>. Thus, it won't read until whitespace,
+but until a comma, after which the comma is consumed with the literal <code>','</code> in the format string.

docs/pages/mainpage.md

@@ -27,6 +27,7 @@ This documentation is for the version 3.0 of the library.
 For version 2.0.3, see https://scnlib.dev/v2.0.3/.
 
 An introductory guide to the library can be found at \ref guide "Guide".
+Answers to frequently asked questions are listed at \ref faq "FAQ".
 
 The API documentation is organized into modules, that can be found under Modules, behind the link at the top of the page.
 It can be searched directly using the search function in the navbar, or by pressing the TAB key.

docs/poxy.toml

@@ -8,6 +8,10 @@ theme = "dark"
 show_includes = false
 navbar = ['namespaces', 'classes', 'modules', 'pages', 'repo']
 changelog = true
+jquery = true
+scripts = [
+    'script/monospace-headers.js'
+]
 
 [warnings]
 enabled = true
@@ -32,8 +36,8 @@ strip_paths = ['../include', 'pages']
 'SCN_MOVE(x)' = 'std::move(x)'
 'SCN_FWD(x)' = 'std::forward<decltype(x)>(x)'
 'SCN_DECLVAL(x)' = 'std::declval<x>()'
-'SCN_BEGIN_NAMESPACE' = ''
-'SCN_END_NAMESPACE' = ''
+'SCN_BEGIN_NAMESPACE' = 'inline namespace v3 {'
+'SCN_END_NAMESPACE' = '}'
 'SCN_GCC_PUSH' = ''
 'SCN_GCC_IGNORE(...)' = ''
 'SCN_GCC_POP' = ''

docs/script/monospace-headers.js

@@ -0,0 +1,16 @@
+'use strict';
+
+$(document).ready(function() {
+    // Find all `<li>` elements inside `#poxy-toc`
+    $('#poxy-toc').find('ul').children('li')
+        // Additionally, find all headers
+        .add('h1, h2, h3, h4, h5')
+        // Replace:
+        //  - &lt;code&gt;...&lt;/code&gt; -> <code>...</code>
+        //  - likewise for <tt> (replace with <code>, too)
+        .each(function () {
+            $(this).html($(this).html()
+                .replace(/&lt;code&gt;(.*?)&lt;\/code&gt;/, '<code>$1</code>')
+                .replace(/&lt;tt&gt;(.*?)&lt;\/tt&gt;/, '<code>$1</code>'));
+        });
+});