@@ -51,6 +51,8 @@ usage examples:
 - echo -en "secret" | codext strength base64 rot-13
 - codext compose
 - codext compose -a alphanumeric -l 4 -k mysecret -m mychain -n
+- codext show rle
+- codext show base64-url rot-13 example-macro
 ```
 
 !!! note "Input/output"
@@ -63,6 +65,10 @@ usage examples:
 
     Encodings can be chained as shown in the last examples of the help message. This can be practical for quickly manipulating data.
 
+!!! note "Codecs documentation"
+    
+    `codext show` displays the documentation of the given codecs, encodings or macros: the codec's name, category and module, then the docstring of this module (for a native codec, the one of its module from the `encodings` package), or the chain of encodings of a macro. An unknown name is reported with similar names (e.g. `codext show vigener` suggests `vigenere`).
+
 ### Execution examples
 
 **Scenario 1**: 2-stages encoded flag
 
@@ -4,8 +4,13 @@
 """
 import argparse
 import sys
+from difflib import get_close_matches
+from encodings import normalize_encoding
+from encodings.aliases import aliases
 from getpass import getpass
+from importlib import import_module
 
+from . import __common__
 from .__common__ import *
 from .__common__ import PERS_MACROS_FILE
 from .compose import QUESTIONS, report as compose_report
@@ -90,6 +95,30 @@ def __ask(question, given=None):
         print(f"    please answer with a number from 1 to {len(choices)}", file=sys.stderr)
 
 
+def __show(name):
+    """ Describe a codec, an encoding or a macro: its name, its category, its module and the docstring of this module,
+         which documents the codec ; a macro is described by its chain of encodings. """
+    ci = lookup(name)
+    if isinstance(ci, CodecMacro):
+        pers = name in __common__.PERS_MACROS
+        chain = (__common__.PERS_MACROS if pers else __common__.MACROS)[name]
+        return f"macro    : {name} ({f'personal, in {PERS_MACROS_FILE}' if pers else 'embedded'})\n" \
+               f"chain    : {' · '.join(chain)}"
+    p = ci.parameters
+    codec, cat, module = p.get('name', ci.name), p.get('category'), p.get('module')
+    # the native codecs are documented by their module from the encodings package (e.g. encodings.cp500)
+    if cat == "native":
+        n = normalize_encoding(ci.name).lower()
+        module = f"encodings.{aliases.get(n, n)}"
+    try:
+        doc = (import_module(module).__doc__ or "").strip()
+    except (ImportError, TypeError, ValueError):
+        doc = ""
+    lines = [f"codec    : {codec} ({cat})"] + ([f"encoding : {name}"] if name != codec else []) + \
+            [f"module   : {module}", "", doc or "No description available."]
+    return "\n".join(lines)
+
+
 def main():
     class _CustomFormatter(argparse.RawTextHelpFormatter):
         def __init__(self, prog, **kwargs):
@@ -121,6 +150,8 @@ def _format_action_invocation(self, action):
         "echo -en \"test\" | codext encode base64 gzip | codext guess gzip -c base",
         "codext compose",
         "codext compose -a alphanumeric -l 4 -k mysecret -m mychain -n",
+        "codext show rle",
+        "codext show base64-url rot-13 example-macro",
     ])
     kw = {'formatter_class': _CustomFormatter}
     parser = argparse.ArgumentParser(prog="codext", description=descr, epilog=examples, **kw)
@@ -218,6 +249,8 @@ def _format_action_invocation(self, action):
     compose.add_argument("-s", "--seed", type=int, help="seed for drawing the chain (default: random)")
     compose.add_argument("-x", "--expansion", choices=list(QUESTIONS[2]['choices']),
                          help="how many times larger than the input the output may be (default: 5)")
+    show = sparsers.add_parser("show", help="show the documentation of codecs, encodings or macros")
+    show.add_argument("encoding", nargs="+", help="names of codecs, encodings or macros")
     search = sparsers.add_parser("search", help="search for codecs")
     search.add_argument("pattern", nargs="+", help="encoding pattern to search")
     listi = sparsers.add_parser("list", help="list items")
@@ -241,6 +274,20 @@ def _format_action_invocation(self, action):
                 results.extend(codecs.search(enc))
             print(", ".join(results) or "No encoding found")
             return 0
+        # show the documentation of codecs, encodings or macros
+        elif args.command == "show":
+            status, out = 0, []
+            for name in args.encoding:
+                try:
+                    out.append(__show(name))
+                except LookupError as e:
+                    status = 1
+                    similar = get_close_matches(name, list_encodings() + list_macros(), 5, .7)
+                    print(f"codext: {str(e)[0].lower()}{str(e)[1:]}" +
+                          (f" (similar: {', '.join(similar)})" if similar else ""), file=sys.stderr)
+            if out:
+                print(("\n\n" + "-" * 80 + "\n\n").join(out))
+            return status
         # add/remove macros (not requiring to input a file or text)
         elif args.command == "add-macro":
             add_macro(args.name, *args.encoding)
 
@@ -12,6 +12,7 @@
 """
 from argparse import ArgumentParser, RawTextHelpFormatter
 from functools import lru_cache
+from inspect import currentframe
 from math import lcm, log
 from string import ascii_lowercase as lower, ascii_uppercase as upper, digits, printable
 from sys import stderr, stdout
@@ -266,6 +267,11 @@ def _decode(input, errors="strict"):
     except AttributeError:
         g = [n]
     kwargs['guess'] = kwargs.get('guess', g)
+    # the codec is documented by the module that declares it (e.g. baseN for base64), not by this factory
+    f = currentframe().f_back
+    while f.f_globals.get('__name__') in (__name__, __name__ + "2n"):
+        f = f.f_back
+    kwargs.setdefault('module', f.f_globals.get('__name__'))
     add(n, encode, decode, pattern, entropy=nb, **kwargs)
 
 
 
@@ -465,6 +465,33 @@ def test_handle_macros(self):
             self.assertIsNone(codext.add_macro("VALID-MACRO", first, "base64"))
             self.assertIsNone(codext.remove("VALID-MACRO"))
 
+    def test_main_show(self):
+        import os, subprocess
+        src = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "src")
+        env = {**os.environ, 'PYTHONPATH': src + os.pathsep + os.environ.get('PYTHONPATH', "")}
+        cli = lambda *args: subprocess.run([sys.executable, "-m", "codext", "show"] + list(args), input=b"", env=env,
+                                           capture_output=True)
+        # a codec is described by the docstring of its module, an encoding by the one of its codec
+        r = cli("rle")
+        self.assertEqual(r.returncode, 0)
+        self.assertIn(b"codec    : rle (compression)", r.stdout)
+        self.assertIn(b"Run-Length Encoding Codec", r.stdout)
+        r = cli("base64-url")
+        self.assertIn(b"encoding : base64-url", r.stdout)
+        self.assertIn(b"module   : codext.base.baseN", r.stdout)
+        # a native codec is described by its module from the encodings package, a macro by its chain
+        self.assertIn(b"module   : encodings.cp500", cli("cp500").stdout)
+        r = cli("rot-13", "example-macro")
+        self.assertIn(b"-" * 80, r.stdout)
+        self.assertIn("chain    : gzip · base62".encode(), r.stdout)
+        # unknown names are reported with similar ones, while the known ones are still shown
+        r = cli("vigener", "rle")
+        self.assertEqual(r.returncode, 1)
+        self.assertIn(b"unknown encoding: vigener (similar: vigenere)", r.stderr)
+        self.assertIn(b"Run-Length Encoding Codec", r.stdout)
+        # the codecs made by the base factory are documented by the module that declares them
+        self.assertEqual(codext.lookup("base32").parameters['module'], "codext.base.baseN")
+    
     def test_main_binary_output(self):
         import os, subprocess
         src = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "src")