Automatically open the man-page if interactive shell is detected.

[h-2]

Try git show --help. It will not print the help-page to stdout, but will instead open the man-page in the user's default pager. I think this is really nice, because man-pages are easier to read (color, scrolling, ...).
Since bioinformatics tools are often not installed system-wide, the man-pages are otherwise not available at all (and no-one does man -l <(bin/tool --export-help man) ).

[smehringer]

hm, although I agree that this could be nice, I think that it is somewhat unexpected behaviour. Usually calling -h on a program prints the help page.

And I personally don't think the man page is much more pretty regarding colors. Scrolling works with ./tool -h | less, which is intuitive (to me :D).

[eseiler]

We could also think about adding something like --man to open the man page?
It's a bit non-standard, but then we have both the text-based output and a man page.

[eseiler]

If we have a format format_man_terminal, which holds a pointer to the executable_name, we could do:

    void parse(parser_meta_data &) const
    {
        std::string command{"bash -c \"man -l <("};
        for (auto && element : *executable_name)
        {
            command += element;
            command += ' ';
        }
        command += "--export-help man)\"";
        if (std::system(command.c_str()) != 0)
            throw std::invalid_argument{"error"};
        std::exit(EXIT_SUCCESS);
    }

To be portable to systems without bash, one could do

mkfifo p1
/path/to/command --export-help man > p1
man -l < p1
rm p1

The other question is whether it would be possible to inject malicious commands :)

Full patch

[eseiler]

The other question is whether it would be possible to inject malicious commands :)

You could symlink, e.g.

ln -s raptor raptor\;bash\ -c\ \'touch\ file\'

and then

./'raptor;bash -c '\''touch file'\''' --man

would execute touch file.

The problem is that usually a symlink does not require special permission, but the command then uses the permissions of the binary.

You could also execute some script that is in your PATH.
Maybe a bit constructed, but if some binary was set to execute with sudo rights, any script could be executed with sudo.

It doesn't seem like you can do much via the subcommand itself.
The symlink thing might be resolvable by std::filesystem::read_symlink.

std::system calls are always a bit sketchy, but I don't think you can open the man page without it.

We could also probably just call export-help internally, put it into some tmp directory, and then call man on that. It should be relatively safe.

[eseiler]

git seems to set MANPATH to where the man page files are, then execute man.

[h-2]

And I personally don't think the man page is much more pretty regarding colors.

I think it definitely adds structure to the text. It lets you quickly see other subcommands, options etc:

But of course there are different personal preferences.

We could also think about adding something like --man to open the man page?

Possible, but would add more defined-by-default arguments and there already are quite a few.

It's a bit non-standard, but then we have both the text-based output and a man page.

The whole "show-manpage" thing only happens on interactive shells. As soon, as there is a | or when invoked from a script, everything stays the same. So ./foo --help | less will behave exactly as before.

git seems to set MANPATH to where the man page files are, then execute man.

Yes, the easiest thing would be to write the manpage to a temporary file, set the MANPATH to that and invoke man. I wouldn't start doing any fancy shell-tricks as that seems like a portability and maintenance nightmare.

[eseiler]

This should work (quick and dirty): https://gist.github.com/eseiler/5fd00ef5c3579952201258a68bdf4453

We should probably explicitly only check for /usr/bin/man instead of man.

Details

diff --git a/include/sharg/detail/format_base.hpp b/include/sharg/detail/format_base.hpp
index 2ef9375..7b05f4c 100644
--- a/include/sharg/detail/format_base.hpp
+++ b/include/sharg/detail/format_base.hpp
@@ -283,7 +283,7 @@ public:
     /*!\brief Initiates the printing of the help page to std::cout.
      * \param[in] parser_meta The meta information that are needed for a detailed help page.
      */
-    void parse(parser_meta_data & parser_meta)
+    void parse(parser_meta_data & parser_meta, bool const skip_exit = false)
     {
         meta = parser_meta;
 
@@ -358,7 +358,8 @@ public:
 
         derived_t().print_footer();
 
-        std::exit(EXIT_SUCCESS); // program should not continue from here
+        if (!skip_exit)
+            std::exit(EXIT_SUCCESS); // program should not continue from here
     }
 
     /*!\brief Adds a print_section call to parser_set_up_calls.
diff --git a/include/sharg/detail/format_man.hpp b/include/sharg/detail/format_man.hpp
index 215fa70..42cddb5 100644
--- a/include/sharg/detail/format_man.hpp
+++ b/include/sharg/detail/format_man.hpp
@@ -13,6 +13,7 @@
 #pragma once
 
 #include <sharg/detail/format_base.hpp>
+#include <sharg/test/tmp_filename.hpp>
 
 namespace sharg::detail
 {
@@ -52,10 +53,40 @@ public:
     //!\copydoc sharg::detail::format_help_base::format_help_base
     format_man(std::vector<std::string> const & names,
                update_notifications const version_updates,
-               bool const advanced = false) :
-        base_type{names, version_updates, advanced} {};
+               bool const advanced = false,
+               bool const skip_exit = false) :
+        base_type{names, version_updates, advanced},
+        skip_exit{skip_exit} {};
     //!\}
 
+    void parse(parser_meta_data & parser_meta)
+    {
+        if (!skip_exit)
+            base_type::parse(parser_meta);
+
+        // Scope to ensure destruction of the tmp_file. std::exit does not call destructors of local variables.
+        {
+            sharg::test::tmp_filename tmp_file{"man.tmpfile"};
+
+            {
+                std::ofstream out{tmp_file.get_path()};
+                std::streambuf * coutbuf = std::cout.rdbuf();
+                std::cout.rdbuf(out.rdbuf());
+
+                base_type::parse(parser_meta, true);
+
+                std::cout.rdbuf(coutbuf);
+            }
+
+            std::string command{"man -l "};
+            command += tmp_file.get_path().c_str();
+            if (std::system(command.c_str()) != 0)
+                throw std::invalid_argument{"error"};
+        }
+
+        std::exit(EXIT_SUCCESS);
+    }
+
 private:
     //!\brief Prints a help page header in man page format to std::cout.
     void print_header()
@@ -161,6 +192,8 @@ private:
 
     //!\brief Needed for correct indentation and line breaks.
     bool is_first_in_section{true};
+
+    bool skip_exit{false};
 };
 
 } // namespace sharg::detail
diff --git a/include/sharg/detail/terminal.hpp b/include/sharg/detail/terminal.hpp
index f2525b3..7c453a7 100644
--- a/include/sharg/detail/terminal.hpp
+++ b/include/sharg/detail/terminal.hpp
@@ -44,6 +44,21 @@ inline bool is_terminal()
 #endif
 }
 
+/*!\brief Check whether the output is interactive.
+ * \ingroup parser
+ * \return True if code is run in a terminal, false otherwise.
+ * \details
+ * For example "./some_binary --help | less" will return false. "./some_binary --help" will return true.
+ */
+inline bool terminal_output_is_interactive()
+{
+#ifndef _WIN32
+    return isatty(STDOUT_FILENO);
+#else
+    return false;
+#endif
+}
+
 // ----------------------------------------------------------------------------
 // Function get_terminal_size()
 // ----------------------------------------------------------------------------
diff --git a/include/sharg/parser.hpp b/include/sharg/parser.hpp
index 71cd959..e5ed28a 100644
--- a/include/sharg/parser.hpp
+++ b/include/sharg/parser.hpp
@@ -774,12 +774,18 @@ private:
 
             if (arg == "-h" || arg == "--help")
             {
-                format = detail::format_help{subcommands, version_check_dev_decision, false};
+                if (detail::terminal_output_is_interactive() && !system("which man > /dev/null 2>&1"))
+                    format = detail::format_man{subcommands, version_check_dev_decision, false, true};
+                else
+                    format = detail::format_help{subcommands, version_check_dev_decision, false};
                 special_format_was_set = true;
             }
             else if (arg == "-hh" || arg == "--advanced-help")
             {
-                format = detail::format_help{subcommands, version_check_dev_decision, true};
+                if (detail::terminal_output_is_interactive() && !system("which man > /dev/null 2>&1"))
+                    format = detail::format_man{subcommands, version_check_dev_decision, true, true};
+                else
+                    format = detail::format_help{subcommands, version_check_dev_decision, true};
                 special_format_was_set = true;
             }
             else if (arg == "--version")

[eseiler]

I'll do a PR when I have time in the evening

[eseiler]

#173