doc/synth: clarify that we need '-e' for resolving the ambiguity between a unit name and a filename

1 files changed, 21 insertions, 13 deletions

diff --git a/doc/using/Synthesis.rst b/doc/using/Synthesis.rst
index fccfad9c6..c1a954e31 100644
--- a/doc/using/Synthesis.rst
+++ b/doc/using/Synthesis.rst
@@ -8,7 +8,8 @@ Synthesis
   This is experimental and work in progress! If you find crashes or unsupported features, please
   :ref:`report them <reporting_bugs>`!
 
-Since ``v0.37``, GHDL features a built-in (experimental) synthesis kernel with two backends: ``synth`` and ``yosys-plugin``.
+Since ``v0.37``, GHDL features a built-in (experimental) synthesis kernel with two backends: ``synth`` and
+``yosys-plugin``.
 Currently, synthesis is supported as a front-end of other synthesis and technology mapping tools.
 Hence, the netlists generated by GHDL are not optimised.
 
@@ -31,18 +32,23 @@ See :option:`--out` and :ghdlsharp:`1174` for on-going discussion about other ou
 
 .. option:: --synth <[options] [library.]top_unit [arch]>
 
-Elaborates for synthesis the design whose top unit is indicated by ``[library.]top_unit [arch]``.
+  Elaborates for synthesis the design whose top unit is indicated by ``[library.]top_unit [arch]``.
 
-.. ATTENTION::
-  All the units must have been analyzed; that is, the artifacts of previously executed :option:`-a` calls must exist.
+  .. ATTENTION::
+    All the units must have been analyzed; that is, the artifacts of previously executed :option:`-a` calls must exist.
 
-.. option:: --synth <[options] files... -e top_unit [arch]>
+.. option:: --synth <[options] files... -e [top_unit [arch]]>
 
-Analyses and elaborates for synthesis the files present on the command line only.
-Elaboration starts from the top unit indicated by ``top_unit [arch]``.
+  Analyses and elaborates for synthesis the files present on the command line only.
+  Elaboration starts from the top unit indicated by ``[top_unit [arch]]``.
+  If no top unit is specified, GHDL will try guessing it and a note will be printed.
 
-.. TIP::
-  Files can be provided in any order.
+  .. IMPORTANT::
+    Files can be provided in any order, but ``-e`` must be provided after them.
+    That is, ``--synth <[options] files...>`` is NOT supported.
+    This is because we want to unambiguously tell files and the unit specification apart.
+    We don't want to rely on parsing the items and guessing whether we are dealing with files or a top unit name.
+    In corner cases, a filename might exist which matches the name of a primary unit: ``ghdl synth name``.
 
 .. _synthesis_options:
 
@@ -164,13 +170,15 @@ etc. A relevant feature of combining GHDL and Yosys is that mixed-language (VHDL
 tools is possible.
 
 The command line syntax for this plugin is the same as for :option:`--synth`, except that the command name (``--synth``)
-is neither required nor supported. Instead, ``yosys``, ``yosys -m ghdl`` or ``yosys -m path/to/ghdl.so`` need to be used,
-depending of how is the plugin built. See `README <https://github.com/ghdl/ghdl-yosys-plugin>`_ for building and installation
+is neither required nor supported.
+Instead, ``yosys``, ``yosys -m ghdl`` or ``yosys -m path/to/ghdl.so`` need to be used, depending of how is the plugin
+built.
+See `ghdl/ghdl-yosys-plugin: README <https://github.com/ghdl/ghdl-yosys-plugin>`_ for building and installation
 guidelines.
 
 .. HINT::
-  ghdl-yosys-plugin is a thin layer that converts the internal representation of :option:`--synth` to Yosys' C API. Hence,
-  it is suggested to check the designs with :option:`--synth` before running synthesis with Yosys.
+  ghdl-yosys-plugin is a thin layer that converts the internal representation of :option:`--synth` to Yosys' C API.
+  Hence, it is suggested to check the designs with :option:`--synth` before running synthesis with Yosys.
 
 Convert (V)HDL to other formats
 ===============================