Man page fixes (#1364)

- Highlighting for options (-x, --x) now doesn't strip the prefix (may be whitespace).
- Escape sequences are now cross-platform compatible (directly taken by groff/troff [man's renderer])
- Now we check for the section before displaying the man pages.
- On MacOS, there is HTTP(n) which is different from our HTTP(1). This used to conflict with it, and we showed the wrong page. Now we specifically ask foir HTTP(1).
- Errors that might happen (e.g non executable man command) is now suppressed. So in the worst case (if anything regarding man execution goes wrong), we'll always display the manual.
- Docs for man pages.
- HTTPie man pages.
- Epilog for the man pages (see also)
- Auto-generated comments.

httpie/cli/definition.py

@@ -26,16 +26,13 @@ options = ParserSpec(
     'http',
     description=f'{__doc__.strip()} <https://httpie.io>',
     epilog="""
-    To learn more, you can try:
-        -> running 'http --manual'
-        -> visiting our full documentation at https://httpie.io/docs/cli
-
     For every --OPTION there is also a --no-OPTION that reverts OPTION
     to its default value.
 
     Suggestions and bug reports are greatly appreciated:
         https://github.com/httpie/httpie/issues
     """,
+    source_file=__file__
 )
 
 

httpie/cli/options.py

@@ -35,17 +35,6 @@ def drop_keys(
     }
 
 
-def _get_first_line(source: str) -> str:
-    parts = []
-    for line in source.strip().splitlines():
-        line = line.strip()
-        parts.append(line)
-        if line.endswith("."):
-            break
-
-    return " ".join(parts)
-
-
 PARSER_SPEC_VERSION = '0.0.1a0'
 
 
@@ -55,6 +44,8 @@ class ParserSpec:
     description: Optional[str] = None
     epilog: Optional[str] = None
     groups: List['Group'] = field(default_factory=list)
+    man_page_hint: Optional[str] = None
+    source_file: Optional[str] = None
 
     def finalize(self) -> 'ParserSpec':
         if self.description:
@@ -248,10 +239,11 @@ def to_data(abstract_options: ParserSpec) -> Dict[str, Any]:
     return {'version': PARSER_SPEC_VERSION, 'spec': abstract_options.serialize()}
 
 
-def parser_to_parser_spec(parser: argparse.ArgumentParser) -> ParserSpec:
+def parser_to_parser_spec(parser: argparse.ArgumentParser, **kwargs) -> ParserSpec:
     """Take an existing argparse parser, and create a spec from it."""
     return ParserSpec(
         program=parser.prog,
         description=parser.description,
-        epilog=parser.epilog
+        epilog=parser.epilog,
+        **kwargs
     )