synopsis fix and maintenance

doc/howto/subcommand_parser/subcommand_parse.out

@@ -1,4 +1,4 @@
 mygit
 =====
-    subcommand_parse_snippet -f|--flag
+    subcommand_parse_snippet [-f|--flag]
     Try -h or --help for more information.

doc/tutorial/parser/solution3.out

@@ -1,5 +1,5 @@
 Game-of-Parsing - Aggregate average Game of Thrones viewers by season.
 ======================================================================
-    solution3_snippet -H|--header-is-set [-y|--year uint32] [-a|--aggregate-by
-    string] [--] path
+    solution3_snippet [-H|--header-is-set] [-y|--year uint32]
+    [-a|--aggregate-by string] [--] path
     Try -h or --help for more information.

doc/tutorial/parser/solution4.out

@@ -1,5 +1,5 @@
 Game-of-Parsing - Aggregate average Game of Thrones viewers by season.
 ======================================================================
-    solution4_snippet -H|--header-is-set [-s|--season uint8]...
+    solution4_snippet [-H|--header-is-set] [-s|--season uint8]...
     [-a|--aggregate-by string] [--] path
     Try -h or --help for more information.

doc/tutorial/parser/solution5.out

@@ -1,5 +1,5 @@
 Game-of-Parsing - Aggregate average Game of Thrones viewers by season.
 ======================================================================
-    solution5_snippet -H|--header-is-set -s|--season uint8 [-s|--season
+    solution5_snippet [-H|--header-is-set] -s|--season uint8 [-s|--season
     uint8]... [-a|--aggregate-by string] [--] path
     Try -h or --help for more information.

doc/tutorial/parser/solution6.out

@@ -1,5 +1,5 @@
 Game-of-Parsing - Aggregate average Game of Thrones viewers by season.
 ======================================================================
-    solution6_snippet -H|--header-is-set -s|--season uint8 [-s|--season
+    solution6_snippet [-H|--header-is-set] -s|--season uint8 [-s|--season
     uint8]... [-a|--aggregate-by string] [--] path
     Try -h or --help for more information.

include/sharg/detail/format_base.hpp

@@ -734,17 +734,20 @@ class format_help_base : public format_base
         }
 #endif
 
-        auto positional_subrange =
-            std::ranges::partition(synopsis_elements, std::logical_not{}, &synopsis_element::is_positional);
+        std::ranges::stable_sort(synopsis_elements, std::ranges::less{}, &synopsis_element::type);
+        auto const pivot = std::ranges::lower_bound(synopsis_elements,
+                                                    synopsis_element::option_type::positional,
+                                                    std::ranges::less{},
+                                                    &synopsis_element::type);
 
-        for (auto it = synopsis_elements.begin(); it != positional_subrange.begin(); ++it)
+        for (auto it = synopsis_elements.begin(); it != pivot; ++it)
         {
             synopsis_line += " " + it->option_str;
         }
-        if (!std::ranges::empty(positional_subrange))
+        if (pivot != synopsis_elements.end())
         {
             synopsis_line += " [\\fB--\\fP]";
-            for (auto it = positional_subrange.begin(); it != positional_subrange.end(); ++it)
+            for (auto it = pivot; it != synopsis_elements.end(); ++it)
             {
                 synopsis_line += " " + it->option_str;
             }
@@ -766,8 +769,15 @@ class format_help_base : public format_base
     //!\brief Structure to store synopsis element information.
     struct synopsis_element
     {
-        std::string option_str;    //!< The formatted option string.
-        bool is_positional{false}; //!< Whether it's a positional argument.
+        //!\brief Kinds of options.
+        enum class option_type : uint8_t
+        {
+            flag,      //!< Option is a flag.
+            option,    //!< Option is a option with argument.
+            positional //!< Option is a positional option.
+        };
+        std::string option_str; //!< The formatted option string.
+        option_type type;       //!< Type of the option.
     };
 
     //!\brief Stores elements for automatic synopsis generation.
@@ -796,6 +806,7 @@ class format_help_base : public format_base
      * \param[in] type_str The type string for the option value.
      * \param[in] required Whether the option is required.
      * \param[in] is_list Whether it's a list of arguments.
+     * \sa https://pubs.opengroup.org/onlinepubs/9699919799
      */
     void store_synopsis_option(detail::id_pair const & id,
                                std::string const & type_str,
@@ -818,20 +829,23 @@ class format_help_base : public format_base
             opt_str = opt_str + " [" + opt_str + "]...";
         }
 
-        synopsis_elements.push_back({opt_str, false});
+        synopsis_elements.push_back({std::move(opt_str), synopsis_element::option_type::option});
     }
 
     /*!\brief Stores flag information for synopsis generation.
      * \param[in] id A sharg::detail::id_pair encapsulating both short and long id.
+     * \sa https://pubs.opengroup.org/onlinepubs/9699919799
      */
     void store_synopsis_flag(detail::id_pair const & id)
     {
-        synopsis_elements.push_back({prep_id_for_help(id, true), false});
+        std::string flag_str = "[" + prep_id_for_help(id, true) + "]";
+        synopsis_elements.push_back({std::move(flag_str), synopsis_element::option_type::flag});
     }
 
     /*!\brief Stores positional argument information for synopsis generation.
      * \param[in] type_str The type string for the positional argument.
      * \param[in] is_list Whether it's a list of arguments.
+     * \sa https://pubs.opengroup.org/onlinepubs/9699919799
      */
     void store_synopsis_positional(std::string const & type_str, bool const is_list)
     {
@@ -840,7 +854,7 @@ class format_help_base : public format_base
         if (is_list)
             pos_str += "...";
 
-        synopsis_elements.push_back({pos_str, true});
+        synopsis_elements.push_back({std::move(pos_str), synopsis_element::option_type::positional});
     }
 
     /*!\brief Adds a function object to parser_set_up_calls **if** the annotation in `config` does not prevent it.

include/sharg/platform.hpp

@@ -2,35 +2,85 @@
 // SPDX-FileCopyrightText: 2016-2025, Knut Reinert & MPI für molekulare Genetik
 // SPDX-License-Identifier: BSD-3-Clause
 
-#pragma once
-
 /*!\file
  * \brief Provides platform and dependency checks.
  * \author Svenja Mehringer <svenja.mehringer AT fu-berlin.de>
  */
 
+#pragma once
+
+#include <version>
+
+// ============================================================================
+//  Compiler support general
+// ============================================================================
+
+/*!\def SHARG_COMPILER_IS_GCC
+ * \brief Whether the current compiler is GCC.
+ * \details
+ * __GNUC__ is also used to indicate the support for GNU compiler extensions. To detect the presence of the GCC
+ * compiler, one has to rule out other compilers.
+ *
+ * \sa https://sourceforge.net/p/predef/wiki/Compilers
+ */
+#if defined(__GNUC__) && !defined(__llvm__) && !defined(__INTEL_COMPILER) && !defined(__INTEL_LLVM_COMPILER)
+#    define SHARG_COMPILER_IS_GCC 1
+#else
+#    define SHARG_COMPILER_IS_GCC 0
+#endif
+
+// ============================================================================
+//  Compiler support
+// ============================================================================
+
+#if SHARG_COMPILER_IS_GCC && (__GNUC__ < 12)
+#    error "Sharg requires at least GCC 12."
+#endif
+
+// clang-format off
+#if defined(__INTEL_LLVM_COMPILER) && (__INTEL_LLVM_COMPILER < 20240000)
+#    error "Sharg requires at least Intel OneAPI 2024."
+#endif
+// clang-format on
+
+#if defined(__clang__) && defined(__clang_major__) && (__clang_major__ < 17)
+#    error "Sharg requires at least Clang 17."
+#endif
+
+// ============================================================================
+//  Standard library support
+// ============================================================================
+
+#if defined(_LIBCPP_VERSION) && (_LIBCPP_VERSION < 170000)
+#    error "Sharg requires at least libc++ 17."
+#endif
+
+#if defined(_GLIBCXX_RELEASE) && (_GLIBCXX_RELEASE < 12)
+#    error "Sharg requires at least libstdc++ 12."
+#endif
+
 // ============================================================================
 //  C++ standard and features
 // ============================================================================
 
 // C++ standard [required]
 #ifdef __cplusplus
-static_assert(__cplusplus >= 201709L, "SHARG requires C++20, make sure that you have set -std=c++20.");
+#    if (__cplusplus < 202100)
+#        error "Sharg requires C++23, make sure that you have set -std=c++23."
+#    endif
 #else
 #    error "This is not a C++ compiler."
 #endif
 
-#include <version>
-
 // ============================================================================
 //  Dependencies
 // ============================================================================
 
-// SHARG [required]
+// Sharg [required]
 #if __has_include(<sharg/version.hpp>)
 #    include <sharg/version.hpp>
 #else
-#    error SHARG include directory not set correctly. Forgot to add -I ${INSTALLDIR}/include to your CXXFLAGS?
+#    error "Sharg include directory not set correctly. Forgot to add -I ${INSTALLDIR}/include to your CXXFLAGS?"
 #endif
 
 // ============================================================================

test/api_stability/1.1.1/0001-API-Update-TDL.patch

@@ -1,4 +1,4 @@
-From 7ed1d89ffe49487b0c9d2a25ab48a78d4b9fb43a Mon Sep 17 00:00:00 2001
+From 947ad6ee223e73c674f0e0a72c3c4ca43e21a7bc Mon Sep 17 00:00:00 2001
 From: Simon Gene Gottlieb <[email protected]>
 Date: Thu, 5 Oct 2023 13:43:30 +0200
 Subject: [PATCH 01/13] [API] Update TDL

test/api_stability/1.1.1/0002-API-Quoted-strings-and-paths.patch

@@ -1,4 +1,4 @@
-From e19583fdc827f80ee5feffc17161176a512bbdbb Mon Sep 17 00:00:00 2001
+From 2821481d732dfda7ac00ce9d3089053b482ed168 Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Mon, 5 Feb 2024 16:02:03 +0100
 Subject: [PATCH 02/13] [API] Quoted strings and paths

test/api_stability/1.1.1/0003-NOAPI-Update-copyright.patch

@@ -1,4 +1,4 @@
-From 796bb41ed97fb796ef40fb8c2825e4bf3ca6317b Mon Sep 17 00:00:00 2001
+From fc0e69c7ca7314c714bd0eab7386e861fa34fb6a Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Wed, 7 Feb 2024 13:31:22 +0100
 Subject: [PATCH 03/13] [NOAPI] Update copyright

test/api_stability/1.1.1/0004-INFRA-Update-TDL.patch

@@ -1,4 +1,4 @@
-From 955334f870ce233669a7bcfc113eec5c952e418d Mon Sep 17 00:00:00 2001
+From a34d50c1a7857b2f80d6c5a21bf007a2b45d4f8b Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Fri, 9 Feb 2024 16:17:21 +0100
 Subject: [PATCH 04/13] [INFRA] Update TDL

test/api_stability/1.1.1/0005-INFRA-Use-seqan3-main-branch.patch

@@ -1,4 +1,4 @@
-From a3c99aef4133582f650f2157109f7ee4ca2f4706 Mon Sep 17 00:00:00 2001
+From 322802cd1c9cffd9aea3bea8ab6e69972fbaa00e Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Fri, 9 Feb 2024 18:13:36 +0100
 Subject: [PATCH 05/13] [INFRA] Use seqan3 main branch

test/api_stability/1.1.1/0006-API-FIX-positional-options-in-CWL-CTD.patch

@@ -1,4 +1,4 @@
-From 4685eca0f5c736df67ccc35839b90fd93c741bfb Mon Sep 17 00:00:00 2001
+From 84601c1b132c57ae371a47191fcba0b82837af83 Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Wed, 14 Feb 2024 12:34:40 +0100
 Subject: [PATCH 06/13] [API][FIX] positional options in CWL/CTD

test/api_stability/1.1.1/0007-API-MISC-Defer-everything-to-parse.patch

@@ -1,4 +1,4 @@
-From 4754621a989483a5ac5dfbc34758696ebcaf21f7 Mon Sep 17 00:00:00 2001
+From ca85ddf6c295efaed871957536c4b339f938c9bc Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Mon, 29 Apr 2024 16:37:15 +0200
 Subject: [PATCH 07/13] [API][MISC] Defer everything to parse()

test/api_stability/1.1.1/0008-API-MISC-Allow-options-for-subcommands.patch

@@ -1,4 +1,4 @@
-From 144e300eb69c24edeef35d914a339efb608dc5b5 Mon Sep 17 00:00:00 2001
+From 908f693bfba73bb55518ada5d3eeda0eb40f2fb7 Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Mon, 29 Apr 2024 16:37:30 +0200
 Subject: [PATCH 08/13] [API][MISC] Allow options for subcommands

test/api_stability/1.1.1/0009-FIX-is_option_set-match-both-long-and-short-ids.patch

@@ -1,4 +1,4 @@
-From e964af74afdc29fd977da7160964dd25def39442 Mon Sep 17 00:00:00 2001
+From b7ce32d1e4ce38a66a02c15ceb8134868370a5ea Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Wed, 2 Apr 2025 18:02:31 +0200
 Subject: [PATCH 09/13] [FIX] is_option_set: match both long and short ids

test/api_stability/1.1.1/0010-NOAPI-Update-copyright.patch

@@ -1,4 +1,4 @@
-From 27a21372df603dc63077634fc7c17e5a2618c70a Mon Sep 17 00:00:00 2001
+From a0586d7b3c17c3688cbd87ee7b1d90aa43ec77ee Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Tue, 29 Jul 2025 14:21:32 +0200
 Subject: [PATCH 10/13] [NOAPI] Update copyright

test/api_stability/1.1.1/0011-INFRA-Bump-minor-version.patch

@@ -1,4 +1,4 @@
-From 8102b8baeec012fcd0b0f4a85477ee7a99f56f32 Mon Sep 17 00:00:00 2001
+From 1248561b0b60ee9983b1560c756fb742bfe2ff0e Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Tue, 29 Jul 2025 14:45:23 +0200
 Subject: [PATCH 11/13] [INFRA] Bump minor version

test/api_stability/1.1.1/0012-NOAPI-Multiple-citatation.patch

@@ -1,4 +1,4 @@
-From d9399e148665d184f56c4a270cdf8af6a831926a Mon Sep 17 00:00:00 2001
+From 67aaa4ebe238ed5f690668f14cc45ce6a52d659a Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Wed, 6 Aug 2025 10:29:26 +0200
 Subject: [PATCH 12/13] [NOAPI] Multiple citatation

test/api_stability/1.1.1/0013-NOAPI-Default-synopsis.patch

@@ -1,4 +1,4 @@
-From cf96efeb9af817062291b9aea4b16e7a1852e9eb Mon Sep 17 00:00:00 2001
+From 210033b2395a014535fa9e714b9666de7c48a3ad Mon Sep 17 00:00:00 2001
 From: Enrico Seiler <[email protected]>
 Date: Wed, 14 Jan 2026 21:20:35 +0100
 Subject: [PATCH 13/13] [NOAPI] Default synopsis
@@ -66,13 +66,13 @@ index 8451721..87b598c 100644
 +    external_custom_type_snippet [-f|--ext-bar external::bar]
      Try -h or --help for more information.
 diff --git a/doc/howto/subcommand_parser/subcommand_parse.out b/doc/howto/subcommand_parser/subcommand_parse.out
-index b60cad3..17bf306 100644
+index b60cad3..94065f9 100644
 --- a/doc/howto/subcommand_parser/subcommand_parse.out
 +++ b/doc/howto/subcommand_parser/subcommand_parse.out
 @@ -1,3 +1,4 @@
  mygit
  =====
-+    subcommand_parse_snippet -f|--flag
++    subcommand_parse_snippet [-f|--flag]
      Try -h or --help for more information.
 diff --git a/doc/tutorial/concepts/custom_validator_solution.out b/doc/tutorial/concepts/custom_validator_solution.out
 index 7769243..e7e2348 100644
@@ -84,43 +84,43 @@ index 7769243..e7e2348 100644
 +    custom_validator_solution_snippet [-i int32] [-j int16]
      Try -h or --help for more information.
 diff --git a/doc/tutorial/parser/solution3.out b/doc/tutorial/parser/solution3.out
-index 388c9fa..72d5642 100644
+index 388c9fa..cd9cf4c 100644
 --- a/doc/tutorial/parser/solution3.out
 +++ b/doc/tutorial/parser/solution3.out
 @@ -1,3 +1,5 @@
  Game-of-Parsing - Aggregate average Game of Thrones viewers by season.
  ======================================================================
-+    solution3_snippet -H|--header-is-set [-y|--year uint32] [-a|--aggregate-by
-+    string] [--] path
++    solution3_snippet [-H|--header-is-set] [-y|--year uint32]
++    [-a|--aggregate-by string] [--] path
      Try -h or --help for more information.
 diff --git a/doc/tutorial/parser/solution4.out b/doc/tutorial/parser/solution4.out
-index 388c9fa..1a2eb13 100644
+index 388c9fa..b484816 100644
 --- a/doc/tutorial/parser/solution4.out
 +++ b/doc/tutorial/parser/solution4.out
 @@ -1,3 +1,5 @@
  Game-of-Parsing - Aggregate average Game of Thrones viewers by season.
  ======================================================================
-+    solution4_snippet -H|--header-is-set [-s|--season uint8]...
++    solution4_snippet [-H|--header-is-set] [-s|--season uint8]...
 +    [-a|--aggregate-by string] [--] path
      Try -h or --help for more information.
 diff --git a/doc/tutorial/parser/solution5.out b/doc/tutorial/parser/solution5.out
-index 388c9fa..25601ce 100644
+index 388c9fa..94f7345 100644
 --- a/doc/tutorial/parser/solution5.out
 +++ b/doc/tutorial/parser/solution5.out
 @@ -1,3 +1,5 @@
  Game-of-Parsing - Aggregate average Game of Thrones viewers by season.
  ======================================================================
-+    solution5_snippet -H|--header-is-set -s|--season uint8 [-s|--season
++    solution5_snippet [-H|--header-is-set] -s|--season uint8 [-s|--season
 +    uint8]... [-a|--aggregate-by string] [--] path
      Try -h or --help for more information.
 diff --git a/doc/tutorial/parser/solution6.out b/doc/tutorial/parser/solution6.out
-index 388c9fa..02689dc 100644
+index 388c9fa..a3f2898 100644
 --- a/doc/tutorial/parser/solution6.out
 +++ b/doc/tutorial/parser/solution6.out
 @@ -1,3 +1,5 @@
  Game-of-Parsing - Aggregate average Game of Thrones viewers by season.
  ======================================================================
-+    solution6_snippet -H|--header-is-set -s|--season uint8 [-s|--season
++    solution6_snippet [-H|--header-is-set] -s|--season uint8 [-s|--season
 +    uint8]... [-a|--aggregate-by string] [--] path
      Try -h or --help for more information.
 diff --git a/test/snippet/custom_enumeration.out b/test/snippet/custom_enumeration.out
@@ -151,13 +151,13 @@ index 3255ec5..6e97748 100644
 +    is_option_set_snippet [-a|--aint int32]
      Try -h or --help for more information.
 diff --git a/test/snippet/parser_1.out b/test/snippet/parser_1.out
-index 84a563e..29f8528 100644
+index 84a563e..741b7bb 100644
 --- a/test/snippet/parser_1.out
 +++ b/test/snippet/parser_1.out
 @@ -1,3 +1,4 @@
  Grade-Average
  =============
-+    parser_1_snippet [-n|--name string] -b|--bonus [--] double...
++    parser_1_snippet [-b|--bonus] [-n|--name string] [--] double...
      Try -h or --help for more information.
 diff --git a/test/snippet/parser_2.out b/test/snippet/parser_2.out
 index b92fc13..a88378e 100644