From 31a9b3fc886412295ac773952052bf0ff27ea411 Mon Sep 17 00:00:00 2001
From: Sebastiaan Huber <mail@sphuber.net>
Date: Tue, 12 Sep 2023 12:14:00 +0200
Subject: [PATCH] Docs: Improve section on installing custom archive

Add more information on how the command will fail if the pseudopotential
files do not respect the expected naming scheme and how the format can
be specified explicitly as a fix.
---
 docs/source/howto.rst | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/source/howto.rst b/docs/source/howto.rst
index 5cf93c9..c193db6 100644
--- a/docs/source/howto.rst
+++ b/docs/source/howto.rst
@@ -45,10 +45,16 @@ In case the pseudopotential family you want to use is not supported, you can ins
 
 where ``<ARCHIVE_OR_FOLDER>`` should be replaced with the archive or folder that contains the pseudopotential files and ``<LABEL>`` with the label to give to the family.
 
-.. important::
+The unpacked archive should contain nothing else besides the pseudopotential files (i.e. no other files or folders) and the pseudopotentials should be present at the top level (not nested in subfolders).
+The command expects pseudopotential files to have the format ``ELEMENT.EXTENSION`` such that it can automatically parse the element for each pseudopotential.
+If the files do not respect this naming convention, the following error message is displayed:
+
+.. code-block:: console
 
-    In order to properly parse the elements from the pseudopotential files, they must adhere ``ELEMENT.EXTENSION`` filename format.
-    The unpacked archive should also contain nothing else besides the pseudopotential files (i.e. no other files or folders) and the pseudopotentials should be present at the top level (not nested in subfolders)..
+    Critical: ``PseudoPotentialData`` constructor did not define the element and could not parse a valid element symbol from the filename `{filename}` either.
+    It should have the format ``ELEMENT.EXTENSION``.
+
+Instead of renaming the files, specify the format of the pseudopotentials so the command can attempt to parse the element from the file itself, as explained :ref:`here <how-to:install_archive:pseudopotential_format>`.
 
 The command will attempt to automatically detect the compression format of the archive.
 If this fails, you can specify the format manually with the ``--archive-format/-f`` option, for example, for a ``.tar.gz`` archive:
@@ -59,6 +65,8 @@ If this fails, you can specify the format manually with the ``--archive-format/-
 
 The valid archive formats are those defined by the `shutil.unpack_archive <https://docs.python.org/3/library/shutil.html#shutil.unpack_archive>`_ function of the standard Python library.
 
+.. _how-to:install_archive:pseudopotential_format:
+
 Pseudopotential format
 ----------------------