rewrite help menus

1 files changed, 175 insertions, 181 deletions

diff --git a/src/frontend/cli/sisyphus-cli.py b/src/frontend/cli/sisyphus-cli.py
index 253e192..93928c4 100755
--- a/src/frontend/cli/sisyphus-cli.py
+++ b/src/frontend/cli/sisyphus-cli.py
@@ -14,9 +14,10 @@ app.add_typer(mirrorSetup, name="mirror",
 
 @app.callback()
 def app_callback(ctx: typer.Context):
-    """Sisyphus is a simple python wrapper around portage, gentoolkit, and portage-utils
-    which provides an apt-get/yum-alike interface to these commands,
-    to assist newcomer people transitioning from Debian/RedHat-based systems to Gentoo.
+    """
+    Sisyphus is a simple python wrapper around portage, gentoolkit, and portage-utils\n
+    which provides an apt-get/yum-alike interface to these commands, to assist newcomers\n
+    transitioning from Debian/RedHat-based systems to Gentoo.\n
 
     Use 'sisyphus COMMAND --help' for detailed usage.
     """
@@ -40,64 +41,48 @@ def search(package: List[str] = typer.Argument(...),
            quiet: bool = typer.Option(
                False, '-q', help='Short (one line) output.'),
            ebuild: bool = typer.Option(False, "--ebuild", "-e", help='Search in ebuilds (slower).')):
-    """Search for binary and/or ebuild (source) packages.
-
-    By default will search for binary packages, using internal database.
-    The search term can be provided also in the category/name format, e.g:
-
-        sisyphus search openbox
-
-            OR
-
-        sisyphus search x11-wm/openbox
-
-    Using * and ? wildcards is supported. An empty string will match everything (similar to *).
-
-    * Examples:
-
-    to search for all packages belonging to a category, use '*' or leave the name empty:
-
-        sisyphus search x11-wm/
-
-        sisyphus search x11-wm/*
-
-    In addition, search can be performed by package description, using the -d (--description) option:
-
-        sisyphus search x11/open -d 'window manager'
-
-    (use single or double quotes when the description contains spaces)
-
-    Use the -f (--filter) option to select only packages of interest. Possible values:
-
-        all (default) - search the entire database
-
-        alien - search for installed packages but not available
-        (this filter can match packages installed from e-builds or packages no longer maintained as binaries)
-
-        installed - search in all installed packages
-
-        available - search for available packages but not installed
-
-        upgradable - search for installed packages where installed version is different from available version
-
-    !!! NOTE !!!:
-
-    bash will expand a single * character as current folder listing.
-    To search for all matching '--filter' packages escape it, or surround it with quotes, or use an empty string:
-
-        sisyphus search * -f installed          # this is not valid!
-
-        sisyphus search \* -f alien             # OK
-
-        sisyphus search '*' -f available        # OK
-
-        sisyphus search '' -f upgradable       # OK
-
-
-    To search for all (including source) packages, use the --ebuild option.
-    This is slower since will perform an emerge --search actually.
-    With this option, more than one package can be provided as search term.
-    '-d', '-f' and '-q' (quiet) options are ignored in this mode.
+    """Search for binary and/or ebuild (source) packages.\n
+    By default will search for binary packages, using internal database.\n
+    The search term can be provided also in the category/name format.\n
+    \n
+    * Examples:\n
+        sisyphus search openbox\n
+        sisyphus search x11-wm/openbox\n
+    \n
+    Using * and ? wildcards is supported. An empty string will match everything (similar to *).\n
+    \n
+    * Examples:\n
+        sisyphus search x11-wm/     # search all packages in the x11-wm category\n
+        sisyphus search x11-wm/*    # search all packages in the x11-wm category\n
+    \n
+    In addition, search can be performed by package description, using the -d (--description) option:\n
+    \n
+    * Examples:\n
+        sisyphus search x11/open -d 'window manager'    # use single or double quotes when the description contains spaces\n
+    \n
+    Use the -f (--filter) option to select only packages of interest. Possible values:\n
+    \n
+        all (default)   - search the entire database\n
+        alien           - search for installed packages but not available     # (this filter can match packages installed from ebuilds or packages no longer maintained as binaries)\n
+        installed       - search in all installed packages\n
+        available       - search for available packages but not installed\n
+        upgradable      - search for installed packages where installed version is different from available version\n
+    \n
+    !!! NOTE !!!\n
+    \n
+    Bash will expand a single * character as current folder listing.\n
+    To search for all matching '--filter' packages you need to escape it, surround it with quotes, or just use an empty string.\n
+    \n
+    * Examples:\n
+        sisyphus search * -f installed          # not valid\n
+        sisyphus search \* -f alien             # valid\n
+        sisyphus search '*' -f available        # valid\n
+        sisyphus search '' -f upgradable        # valid\n
+    \n
+    To search for all (including source) packages, use the --ebuild option.\n
+    This is slower since will perform an 'emerge --search' actually.\n
+    With this option, more than one package can be provided as search term.\n
+    '-d', '-f' and '-q' (quiet) options are ignored in this mode.\n
     """
     if not ebuild:
         if '/' in package[0]:
@@ -116,28 +101,26 @@ def search(package: List[str] = typer.Argument(...),
 @app.command("install")
 def install(pkgname: List[str],
             ebuild: bool = typer.Option(
-                False, "--ebuild", "-e", help='Install ebuild (source) package if binary package is not found (slower)'),
-            oneshot: bool = typer.Option(False, "--oneshot", "-1", help='Do not mark the package as explicitly installed, and do not add it to world set')):
-    """Install binary and/or ebuild(source) packages.
-    By default, only binary packages will be installed.
-    Use the --ebuild option to install ebuild(source) packages.
-
-    * Examples:
-
-        sisyphus install pidgin
-
-    will install pidgin binary package (if available); if there is none, but the ebuild(source) package for pidgin is found, it will stop and suggest the --ebuild option.
-
-        sisyphus install pidgin --ebuild
-
-    will compile pidgin from source
-
-    The --ebuild option will preffer to reuse binary packages(if available) to satisfy the dependencies for the ebuild(source) package, speeding up the installation.
-    You can use the --ebuild option even if you don't want to install any ebuild(source) packages; It will fall back to binary packages only.
-
-    The --oneshot option will install the packages as described above, however it will not add them to the 'world' set, which means they will not be marked as
-    explicitly installed. As a result, they will be treated as orphans and they will be uninstalled with 'sisyphus autoremove' if no other package needs them as
-    a depencency, unless they are explicitly added to the 'world' set using 'emerge --noreplace pkgname'.
+                False, "--ebuild", "-e", help='Install ebuild(source) package if binary package is not found (slower)'),
+            oneshot: bool = typer.Option(False, "--oneshot", "-1", help='Do not mark the package as explicitly installed')):
+    """
+    Install binary and/or ebuild(source) packages.\n
+    Binary packages are default, however the --ebuild option can be used to install ebuild(source) packages.\n
+    The --ebuild option will be automatically suggested if a binary package is not found, but an ebuild(source) package is found.\n
+    The --ebuild option will fall back to binary packages if installation from ebuild(source) package is not required. (Can be used at all times, *SAFELY*).\n
+    The --ebuild option will prefer to use binary packages (if available) to satisfy dependencies for the ebuild(source) package, speeding up the installation.\n
+    The --oneshot option follows the above rules, however it will not mark the package as explicitly installed. (In Gentoo Linux terms: not added to world set).\n
+    The --ebuild and the --oneshot options can be used both independently of each other and/or combined with each other.\n
+    \n
+    * Examples:\n
+        sisyphus install firefox\n
+        sisyphus install pidgin --ebuild\n
+        sisyphus install xonotic -e\n
+        sisyphus install filezilla --oneshot\n
+        sisyphus install thunderbird -1\n
+        sisyphus install falkon -e -1\n
+        sisyphus install opera --ebuild --oneshot\n
+        sisyphus install vivaldi --oneshot --ebuild\n
     """
     if ebuild:
         sisyphus.install.start(pkgname, ebuild=True,
@@ -148,36 +131,20 @@ def install(pkgname: List[str],
 
 
 @app.command("uninstall")
-def uninstall(pkgname: List[str], force: bool = typer.Option(False, "--force", "-f")):
-    """Uninstall packages *SAFELY* by checking for reverse dependencies.
-    If reverse dependencies exist, the package(s) will NOT be uninstalled to prevent the possible breakage of the system.
-    If you really want to uninstall the package, make sure you uninstall all reverse dependencies as well.
-    This will not allways be possible, as the reverse dependency chain may be way to long and require you to uninstall critical system packages.
-
-    * Examples:
-
-        sisyphus uninstall firefox
-
-    will succeed, nothing depends on it
-
-        sisyphus uninstall pulseaudio
-
-    will fail, many packages depend on it
-
-    With --force option, packages are uninstalled *UNSAFELY* by ignoring reverse dependencies.
-    This may break your system if you uninstall critical packages.
-    It will try the best it can to preserve the libraries required by other packages to prevent such a breakage.
-    Upgrading the system may pull the packages back in, to fix the reverse dependency chain.
-
-    * Examples :
-
-        sisyphus uninstall pulseaudio --force
-
-    will succeed, but you may no longer have audio
-
-        sisyphus uninstall openrc --force
-
-    will succeed, but the system will be broken
+def uninstall(pkgname: List[str], force: bool = typer.Option(False, "--force", "-f", help='Ignore the reverse dependencies and force uninstall the package (DANGEROUS)')):
+    """
+    Uninstall packages *SAFELY* by checking for reverse dependencies.\n
+    If there are any reverse dependencies, the package or packages will NOT be uninstalled to prevent the system from breaking.\n
+    If you are serious about uninstalling the package, it is recommended you uninstall all the reverse dependencies of it as well.\n
+    This will not always be possible because the reverse dependency tree may be too long and you may need to uninstall important system packages.\n
+    DANGEROUS : The --force option will ignore the reverse dependencies and uninstall the package *UNSAFELY*, without safeguards.\n
+    WARNING   : The --force option will break your system if you uninstall important system packages (bootloader, kernel, init).\n
+    \n
+    * Examples:\n
+        sisyphus uninstall firefox              # this will succeed, no package depends on firefox\n
+        sisyphus uninstall pulseaudio           # this will fail, many packages depend on pulseaudio\n
+        sisyphus uninstall pulseaudio --force   # this will succeed, but the sound may no longer work\n
+        sisyphus uninstall openrc -f            # this will succeed, but the system will no longer boot\n
     """
     if force:
         sisyphus.uninstall.start(
@@ -189,17 +156,27 @@ def uninstall(pkgname: List[str], force: bool = typer.Option(False, "--force", "
 
 @app.command("autoremove")
 def autoremove():
-    """Uninstall packages that are no longer needed.
-    When you uninstall a package without it's reverse dependencies, those dependencies will become orphans if nothing else requires them.
-    In addition, a package may no longer depend on another one, so that other package becomes orphan as well if nothing else requires it.
-    Use this option to check the whole dependency chain for such packages, and uninstall them.
+    """
+    Uninstall packages which become orphans and which are no longer needed.\n
+    Uninstalling a package will usually leave it's dependencies behind. Those dependencies become orphans if no other package requires them.\n
+    A package may also gain extra dependencies, or loose some dependencies. The lost dependencies become orphans if no other package requires them.\n
+    In both cases, the orphan packages are no longer needed and can be safely removed.\n
+    Use this option to check the whole dependency tree for orphan packages, and remove them.\n
+    \n
+    * Examples:\n
+        sisyphus autoremove\n
     """
     sisyphus.autoremove.start(gfx_ui=False)
 
 
 @app.command("autoclean")
 def autoclean():
-    """Clean the binary package cache and the source tarball cache"""
+    """
+    Clean the binary package cache and the source tarball cache.\n
+    \n
+    * Examples:\n
+        sisyphus autoclean\n
+    """
     if sisyphus.checkenv.root():
         sisyphus.purgeenv.cache()
     else:
@@ -208,7 +185,12 @@ def autoclean():
 
 @app.command("update")
 def update():
-    """Update the Portage tree, the Redcore Overlay(s), Portage configs and Sisyphus's package database."""
+    """
+    Update the source trees, package configs (USE flags, keywords, masks, etc) and the binary package database.\n
+    \n
+    * Examples:\n
+        sisyphus update\n
+    """
     if sisyphus.checkenv.root():
         sisyphus.update.start(gfx_ui=False)
     else:
@@ -217,24 +199,18 @@ def update():
 
 @app.command("upgrade")
 def upgrade(
-        ebuild: bool = typer.Option(False, "--ebuild", "-e", help='Upgrade all packages, including ebuild (source) packages previously installed (slower)')):
-    """Upgrade the system using binary and/or ebuild (source) packages.
-    By default, only binary packages will be upgraded.
-    However, if you installed any ebuild(source) packages with the '--ebuild' option, it would make sense to upgrade them too.
-    Use the --ebuild option to upgrade **EVERYTHING**, binary and/or ebuild(source) packages.
-
-    * Examples:
-
-        sisyphus upgrade
-
-    will upgrade the system using binary packages; if any ebuild(source) package upgrade is detected, it will stop and suggest the --ebuild option
-
-        sisyphus upgrade --ebuild
-
-    will upgrade the system using both binary and/or ebuild(source) packages
-
-    The --ebuild option will preffer to reuse binary packages(if available) to satisfy the dependencies for the ebuild(source) packages, speeding up the upgrade.
-    You can use the --ebuild option even if you don't have any ebuild(source) packages installed; It will fall back to binary packages only.
+        ebuild: bool = typer.Option(False, "--ebuild", "-e", help='Upgrade all packages, including ebuild(source) packages (slower)')):
+    """
+    Upgrade the system using binary and/or ebuild(source) packages.\n
+    Binary packages are default, however the --ebuild option can be used to upgrade the ebuild(source) packages as well, alongside the binary packages.\n
+    The --ebuild option will be automatically suggested if the ebuild(source) packages need to be upgraded as well, alongside the binary packages.\n
+    The --ebuild option will fall back to binary packages if the ebuild(source) packages don't require any upgrade. (Can be used at all times, *SAFELY*).\n
+    The --ebuild option will prefer to use binary packages (if available) to satisfy dependencies for the ebuild(source) packages, speeding up the upgrade.\n
+    \n
+    * Examples:\n
+        sisyphus upgrade\n
+        sisyphus upgrade --ebuild\n
+        sisyphus upgrade -e\n
     """
     if ebuild:
         sisyphus.upgrade.start(ebuild=True, gfx_ui=False)
@@ -244,19 +220,27 @@ def upgrade(
 
 @app.command("spmsync")
 def spmsync():
-    """Sync Sisyphus's package database with Portage's package database.
-    When you install something with Portage directly (emerge), Sisyphus is not aware of that package, and it doesn't track it in it's database.
-    Use this command to synchronize Sisyphus's package database with Portage's package database.
+    """
+    Sync Sisyphus's package database with Portage's package database.\n
+    Sisyphus does not track packages installed directly via Portage in it's package database.\n
+    Use this command to synchronize Sisyphus's package database with Portage's package database.\n
+    \n
+    * Examples:\n
+        sisyphus spmsync\n
     """
     sisyphus.syncspm.start()
 
 
 @app.command("rescue")
 def rescue():
-    """Resurrect Sisyphus's package database if lost or corrupted.
-    If for some reason Sisyphus's package database is lost or corrupted, it can be resurrected using Portage's package database.
-    If Portage's package database is corrupted (in this case you're screwed anyway :D), only a partial resurrection will be possible.
-    If Portage's package database is intact, full resurrection will be possible.
+    """
+    Resurrect Sisyphus's package database if lost or corrupted.\n
+    If for some reason Sisyphus's package database is lost or corrupted, it can be resurrected using Portage's package database.\n
+    If Portage's package database is corrupted (in this case you're screwed anyway :D), only a partial resurrection will be possible.\n
+    If Portage's package database is intact, full resurrection will be possible.\n
+    \n
+    * Examples:\n
+        sisyphus rescue\n
     """
     sisyphus.recoverdb.start()
 
@@ -274,59 +258,69 @@ class Remote(str, Enum):
 
 @app.command("branch")
 def branch(branch: Branch = typer.Argument(...), remote: Remote = typer.Option(Remote.gitlab, "--remote", "-r")):
-    """Pull the selected branch of the Portage tree, Redcore overlay and Portage configs.
-    The remote can be selected by using the --remote option.
-
-    'BRANCH' can be one of the following : master, next
-
-    'REMOTE' can be one of the following : github, gitlab, pagure (default is gitlab)
-
-    * Examples:
-
-        branch next --remote=github     # pull the branch 'next' from github.com
-
-        branch master --remote=gitlab   # pull the branch 'master' from gitlab.com
-
-        branch next --remote=pagure     # pull the branch 'next' from pagure.io
-
-    !!! WARNING !!!
-
-    Once you changed the branch, you must pair it with the correct binhost (binary repository).
-
-    Branch 'master' must be paired with the stable binhost (binary repository) (odd numbers in 'sisyphus mirror list').
-
-    * Examples:
-
-        sisyphus mirror set 1
-
-        sisyphus mirror set 5
-
-    Branch 'next' must be paired with the testing binhost (binary repository) (even numbers in 'sisyphus mirror list').
-
-    * Examples:
-
-        sisyphus mirror set 2
-
-        sisyphus mirror set 8
+    """
+    Switch between the branches of Redcore Linux : 'master' (stable) or 'next' (testing), default branch is 'master' (stable)\n
+    Reconfigure the source trees, package configs (USE flags, keywords, masks, etc) and the binhost (binary repository)\n
+    Selection of a remote is optional (default is gitlab), but it can be accomplished by using the --remote option.\n
+    'BRANCH' can be one of the following : master, next\n
+    'REMOTE' can be one of the following : github, gitlab, pagure (default is gitlab)\n
+    \n
+    * Examples:\n
+        sisyphus branch master                  # switch to branch 'master', use default remote (gitlab)\n
+        sisyphus branch next                    # switch to branch 'next', use default remote (gitlab)\n
+        sisyphus branch master --remote=github  # switch to branch 'master', use github remote\n
+        sisyphus branch next --remote=pagure    # switch to branch 'next', use pagure remote\n
+    \n
+    Sisyphus will automatically pair the selected branch with the correct binhost (binary repository).\n
+    However, since no geolocation is ever used, it may select one which is geographically far from you.\n
+    If that is inconvenient, you can manually select a binhost (binary repository) closer to your location,\n
+    \n
+    !!! WARNING !!!\n
+    \n
+    Branch 'master' must be paired with the stable binhost (binary repository) (odd numbers in 'sisyphus mirror list').\n
+    * Examples:\n
+        sisyphus mirror set 1\n
+        sisyphus mirror set 5\n
+    \n
+    Branch 'next' must be paired with the testing binhost (binary repository) (even numbers in 'sisyphus mirror list').\n
+    * Examples:\n
+        sisyphus mirror set 2\n
+        sisyphus mirror set 8\n
     """
     sisyphus.setbranch.start(branch.value, remote.value)
 
 
 @app.command("sysinfo")
 def sysinfo():
-    """Display information about installed core packages and portage configuration."""
+    """
+    Display information about installed core packages and portage configuration.\n
+    \n
+    * Examples:\n
+        sisyphus sysinfo\n
+    """
     sisyphus.sysinfo.show()
 
 
 @mirrorSetup.command("list")
 def mirrorlist():
-    """List available binary package repository mirrors (the active one is marked with *)."""
+    """
+    List available binary package repository mirrors (the active one is marked with *).\n
+    \n
+    * Examples:\n
+        sisyphus mirror list\n
+    """
     sisyphus.mirrors.printList()
 
 
 @mirrorSetup.command("set")
 def mirrorset(index: int):
-    """Change the binary package repository to the selected mirror."""
+    """
+    Change the binary package repository to the selected mirror.\n
+    \n
+    * Examples:\n
+        sisyphus mirror set 2\n
+        sisyphus mirror set 5\n
+    """
     sisyphus.mirrors.setActive(index)