Docs: Move rtlil_text (back) to appendix

docs/source/appendix/rtlil_text.rst

@@ -223,8 +223,8 @@ Cells
 Declares a cell, with zero or more attributes, with the given identifier and
 type in the enclosing module.
 
-Cells perform functions on input signals. See
-:doc:`/yosys_internals/formats/cell_library` for a detailed list of cell types.
+Cells perform functions on input signals. See :doc:`/cell_gate` and
+:doc:`/cell_word` for a detailed list of cell types.
 
 .. code:: BNF
 

docs/source/index.rst

@@ -44,6 +44,7 @@ available, go to :ref:`commandindex`.
    :includehidden:
 
    appendix/primer
+   appendix/rtlil_text
    appendix/auxlibs
    appendix/auxprogs
 

docs/source/yosys_internals/flow/overview.rst

@@ -20,7 +20,7 @@ given in :doc:`/yosys_internals/formats/rtlil_rep`.
 
 There is also a text representation of the RTLIL data structure that can be
 parsed using the RTLIL Frontend which is described in
-:doc:`/yosys_internals/formats/rtlil_text`.
+:doc:`/appendix/rtlil_text`.
 
 The design data may then be transformed using a series of passes that all
 operate on the RTLIL representation of the design.

docs/source/yosys_internals/formats/index.rst

@@ -1,13 +1,59 @@
 Internal formats
 ================
 
-.. todo:: brief overview for the internal formats index
+Yosys uses two different internal formats. The first is used to store an
+abstract syntax tree (AST) of a Verilog input file. This format is simply called
+AST and is generated by the Verilog Frontend. This data structure is consumed by
+a subsystem called AST Frontend [1]_. This AST Frontend then generates a design
+in Yosys' main internal format, the
+Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does
+that by first performing a number of simplifications within the AST
+representation and then generating RTLIL from the simplified AST data structure.
+
+The RTLIL representation is used by all passes as input and outputs. This has
+the following advantages over using different representational formats between
+different passes:
+
+-  The passes can be rearranged in a different order and passes can be removed
+   or inserted.
+
+-  Passes can simply pass-thru the parts of the design they don't change without
+   the need to convert between formats. In fact Yosys passes output the same
+   data structure they received as input and performs all changes in place.
+
+-  All passes use the same interface, thus reducing the effort required to
+   understand a pass when reading the Yosys source code, e.g. when adding
+   additional features.
+
+The RTLIL representation is basically a netlist representation with the
+following additional features:
+
+-  An internal cell library with fixed-function cells to represent RTL datapath
+   and register cells as well as logical gate-level cells (single-bit gates and
+   registers).
+
+-  Support for multi-bit values that can use individual bits from wires as well
+   as constant bits to represent coarse-grain netlists.
+
+-  Support for basic behavioural constructs (if-then-else structures and
+   multi-case switches with a sensitivity list for updating the outputs).
+
+-  Support for multi-port memories.
+
+The use of RTLIL also has the disadvantage of having a very powerful format
+between all passes, even when doing gate-level synthesis where the more advanced
+features are not needed. In order to reduce complexity for passes that operate
+on a low-level representation, these passes check the features used in the input
+RTLIL and fail to run when unsupported high-level constructs are used. In such
+cases a pass that transforms the higher-level constructs to lower-level
+constructs must be called from the synthesis script first.
 
 .. toctree:: 
    :maxdepth: 3
 
-	overview
    rtlil_rep
-	rtlil_text
-	cell_library
+
+.. [1]
+   In Yosys the term pass is only used to refer to commands that operate on the
+   RTLIL data structure.
 

docs/source/yosys_internals/formats/overview.rst

@@ -1,53 +0,0 @@
-Format overview
-===============
-
-Yosys uses two different internal formats. The first is used to store an
-abstract syntax tree (AST) of a Verilog input file. This format is simply called
-AST and is generated by the Verilog Frontend. This data structure is consumed by
-a subsystem called AST Frontend [1]_. This AST Frontend then generates a design
-in Yosys' main internal format, the
-Register-Transfer-Level-Intermediate-Language (RTLIL) representation. It does
-that by first performing a number of simplifications within the AST
-representation and then generating RTLIL from the simplified AST data structure.
-
-The RTLIL representation is used by all passes as input and outputs. This has
-the following advantages over using different representational formats between
-different passes:
-
--  The passes can be rearranged in a different order and passes can be removed
-   or inserted.
-
--  Passes can simply pass-thru the parts of the design they don't change without
-   the need to convert between formats. In fact Yosys passes output the same
-   data structure they received as input and performs all changes in place.
-
--  All passes use the same interface, thus reducing the effort required to
-   understand a pass when reading the Yosys source code, e.g. when adding
-   additional features.
-
-The RTLIL representation is basically a netlist representation with the
-following additional features:
-
--  An internal cell library with fixed-function cells to represent RTL datapath
-   and register cells as well as logical gate-level cells (single-bit gates and
-   registers).
-
--  Support for multi-bit values that can use individual bits from wires as well
-   as constant bits to represent coarse-grain netlists.
-
--  Support for basic behavioural constructs (if-then-else structures and
-   multi-case switches with a sensitivity list for updating the outputs).
-
--  Support for multi-port memories.
-
-The use of RTLIL also has the disadvantage of having a very powerful format
-between all passes, even when doing gate-level synthesis where the more advanced
-features are not needed. In order to reduce complexity for passes that operate
-on a low-level representation, these passes check the features used in the input
-RTLIL and fail to run when unsupported high-level constructs are used. In such
-cases a pass that transforms the higher-level constructs to lower-level
-constructs must be called from the synthesis script first.
-
-.. [1]
-   In Yosys the term pass is only used to refer to commands that operate on the
-   RTLIL data structure.