Docs: rearrange manual section layout.

Also, use the word "blocks" consistently instead of "directives".

Makefile.am

@@ -224,43 +224,46 @@ re2c_SRC_DOC = doc/manpage.rst
 # To build the list of examples for all backends, run:
 # find examples -regex '.*\.re\|.*\(state\|01_basic\|definitions\)\..*' -printf '\t%p \\\n' | sort
 re2c_SRC_DOC_EXT = \
-	doc/manual/api/api1.rst_ \
-	doc/manual/api/api2_c.rst_ \
-	doc/manual/api/api2_go.rst_ \
-	doc/manual/api/api2_rust.rst_ \
-	doc/manual/api/api3.rst_ \
-	doc/manual/conditions/blocks.rst_ \
-	doc/manual/conditions/conditions.rst_ \
-	doc/manual/configurations/configurations.rst_ \
-	doc/manual/dot/dot.rst_ \
-	doc/manual/encodings/encodings.rst_ \
+	doc/manual/basics/api/api1.rst_ \
+	doc/manual/basics/api/api2_c.rst_ \
+	doc/manual/basics/api/api2_go.rst_ \
+	doc/manual/basics/api/api2_rust.rst_ \
+	doc/manual/basics/api/api3.rst_ \
+	doc/manual/basics/blocks.rst_ \
+	doc/manual/basics/directives.rst_ \
+	doc/manual/basics/configurations.rst_ \
+	doc/manual/basics/regular_expressions.rst_ \
+	doc/manual/basics/syntax.rst_ \
+	doc/manual/basics/options/debug.rst_ \
+	doc/manual/basics/options/internal.rst_ \
+	doc/manual/basics/options/options.rst_ \
+	doc/manual/basics/warnings/warnings_general.rst_ \
+	doc/manual/basics/warnings/warnings_list.rst_ \
 	doc/manual/eof/01_sentinel.rst_ \
 	doc/manual/eof/02_bounds_checking.rst_ \
 	doc/manual/eof/03_eof_rule.rst_ \
 	doc/manual/eof/04_fake_sentinel.rst_ \
 	doc/manual/eof/eof.rst_ \
+	doc/manual/features/conditions/blocks.rst_ \
+	doc/manual/features/conditions/conditions.rst_ \
+	doc/manual/features/dot/dot.rst_ \
+	doc/manual/features/encodings/encodings.rst_ \
+	doc/manual/features/headers/headers.rst_ \
+	doc/manual/features/includes/includes.rst_ \
+	doc/manual/features/reuse/reuse.rst_ \
+	doc/manual/features/skeleton/skeleton.rst_ \
+	doc/manual/features/state/state.rst_ \
+	doc/manual/features/submatch/submatch_example_mtags.rst_ \
+	doc/manual/features/submatch/submatch_example_captures.rst_ \
+	doc/manual/features/submatch/submatch_example_stags_fill.rst_ \
+	doc/manual/features/submatch/submatch_example_stags.rst_ \
+	doc/manual/features/submatch/submatch.rst_ \
 	doc/manual/fill/01_fill.rst_ \
 	doc/manual/fill/02_fill.rst_ \
 	doc/manual/fill/fill.rst_ \
-	doc/manual/headers/headers.rst_ \
-	doc/manual/includes/includes.rst_ \
-	doc/manual/options/debug.rst_ \
-	doc/manual/options/internal.rst_ \
-	doc/manual/options/options.rst_ \
-	doc/manual/regexps/regular_expressions.rst_ \
-	doc/manual/reuse/reuse.rst_ \
-	doc/manual/skeleton/skeleton.rst_ \
-	doc/manual/state/state.rst_ \
-	doc/manual/submatch/submatch_example_mtags.rst_ \
-	doc/manual/submatch/submatch_example_captures.rst_ \
-	doc/manual/submatch/submatch_example_stags_fill.rst_ \
-	doc/manual/submatch/submatch_example_stags.rst_ \
-	doc/manual/submatch/submatch.rst_ \
+	doc/manual/authors.rst_ \
+	doc/manual/intro.rst_ \
 	doc/manual/synopsis.rst_ \
-	doc/manual/syntax/intro.rst_ \
-	doc/manual/syntax/syntax.rst_ \
-	doc/manual/warnings/warnings_general.rst_ \
-	doc/manual/warnings/warnings_list.rst_ \
 	examples/c/01_basic.c \
 	examples/c/01_basic.re \
 	examples/c/conditions/parse_u32_blocks.re \

doc/help.rst.in

@@ -8,12 +8,12 @@ Usage
 OPTIONS
 =======
 
-.. include:: @top_srcdir@/doc/manual/options/options.rst_
-.. include:: @top_srcdir@/doc/manual/options/debug.rst_
-.. include:: @top_srcdir@/doc/manual/options/internal.rst_
+.. include:: @top_srcdir@/doc/manual/basics/options/options.rst_
+.. include:: @top_srcdir@/doc/manual/basics/options/debug.rst_
+.. include:: @top_srcdir@/doc/manual/basics/options/internal.rst_
 
 WARNINGS
 ========
 
-.. include:: @top_srcdir@/doc/manual/warnings/warnings_general.rst_
-.. include:: @top_srcdir@/doc/manual/warnings/warnings_list.rst_
+.. include:: @top_srcdir@/doc/manual/basics/warnings/warnings_general.rst_
+.. include:: @top_srcdir@/doc/manual/basics/warnings/warnings_list.rst_

doc/manpage.rst.in

@@ -9,6 +9,7 @@ generate fast lexical analyzers for RE2C_LANG_NAME
 :Manual section: 1
 
 .. |re2c| replace:: RE2C_PROG
+.. |lang_name| replace:: RE2C_LANG_NAME
 
 SYNOPSIS
 ========
@@ -20,7 +21,7 @@ RE2C_DISCLAIMER
 Introduction
 ============
 
-.. include:: @top_srcdir@/doc/manual/syntax/intro.rst_
+.. include:: @top_srcdir@/doc/manual/intro.rst_
 
 Here is an example of a small program that checks if a given string contains a
 decimal number:
@@ -29,52 +30,57 @@ decimal number:
     :literal:
     :code: RE2C_LANG
 
-In the output everything between ``/*!re2c`` and ``*/`` has been replaced with
-the generated code:
+In the output |re2c| replaced the block in the middle with the generated code:
 
 .. include:: @top_srcdir@/examples/RE2C_LANG/01_basic.RE2C_SOURCE_EXT
     :literal:
     :code: RE2C_LANG
 
-Syntax
+Basics
 ======
+.. include:: @top_srcdir@/doc/manual/basics/syntax.rst_
 
-.. include:: @top_srcdir@/doc/manual/syntax/syntax.rst_
+Blocks
+------
+.. include:: @top_srcdir@/doc/manual/basics/blocks.rst_
 
-Program interface
-=================
+Directives
+----------
+.. include:: @top_srcdir@/doc/manual/basics/directives.rst_
+
+Regular expressions
+-------------------
+.. include:: @top_srcdir@/doc/manual/basics/regular_expressions.rst_
+
+Configurations
+--------------
+.. include:: @top_srcdir@/doc/manual/basics/configurations.rst_
 
-.. include:: @top_srcdir@/doc/manual/api/api1.rst_
-.. include:: @top_srcdir@/doc/manual/api/api2_RE2C_LANG.rst_
-.. include:: @top_srcdir@/doc/manual/api/api3.rst_
+Program interface
+-----------------
+.. include:: @top_srcdir@/doc/manual/basics/api/api1.rst_
+.. include:: @top_srcdir@/doc/manual/basics/api/api2_RE2C_LANG.rst_
+.. include:: @top_srcdir@/doc/manual/basics/api/api3.rst_
 
 Options
-=======
+-------
 
 Some of the options have corresponding `configurations`_,
 others are global and cannot be changed after re2c starts reading the input file.
 Debug options generally require building re2c in debug configuration.
 Internal options are useful for experimenting with the algorithms used in re2c.
 
-.. include:: @top_srcdir@/doc/manual/options/options.rst_
-.. include:: @top_srcdir@/doc/manual/options/debug.rst_
-.. include:: @top_srcdir@/doc/manual/options/internal.rst_
+.. include:: @top_srcdir@/doc/manual/basics/options/options.rst_
+.. include:: @top_srcdir@/doc/manual/basics/options/debug.rst_
+.. include:: @top_srcdir@/doc/manual/basics/options/internal.rst_
 
 Warnings
-========
+--------
 
 Warnings can be invividually enabled, disabled and turned into an error.
 
-.. include:: @top_srcdir@/doc/manual/warnings/warnings_general.rst_
-.. include:: @top_srcdir@/doc/manual/warnings/warnings_list.rst_
-
-Configurations
-==============
-.. include:: @top_srcdir@/doc/manual/configurations/configurations.rst_
-
-Regular expressions
-===================
-.. include:: @top_srcdir@/doc/manual/regexps/regular_expressions.rst_
+.. include:: @top_srcdir@/doc/manual/basics/warnings/warnings_general.rst_
+.. include:: @top_srcdir@/doc/manual/basics/warnings/warnings_list.rst_
 
 Handling the end of input
 =========================
@@ -108,115 +114,118 @@ Buffer refilling
     :literal:
     :code: RE2C_LANG
 
+Features
+========
+
 Multiple blocks
-===============
-.. include:: @top_srcdir@/doc/manual/conditions/blocks.rst_
+---------------
+.. include:: @top_srcdir@/doc/manual/features/conditions/blocks.rst_
 .. include:: @top_srcdir@/examples/RE2C_LANG/conditions/parse_u32_blocks.re
     :literal:
     :code: RE2C_LANG
 
 Start conditions
-================
-.. include:: @top_srcdir@/doc/manual/conditions/conditions.rst_
+----------------
+.. include:: @top_srcdir@/doc/manual/features/conditions/conditions.rst_
 .. include:: @top_srcdir@/examples/RE2C_LANG/conditions/parse_u32_conditions.re
     :literal:
     :code: RE2C_LANG
 
 Storable state
-==============
-.. include:: @top_srcdir@/doc/manual/state/state.rst_
+--------------
+.. include:: @top_srcdir@/doc/manual/features/state/state.rst_
 .. include:: @top_srcdir@/examples/RE2C_LANG/state/push.re
     :literal:
     :code: RE2C_LANG
 
 Reusable blocks
-===============
-.. include:: @top_srcdir@/doc/manual/reuse/reuse.rst_
+---------------
+.. include:: @top_srcdir@/doc/manual/features/reuse/reuse.rst_
 
 Example of a ``!use`` directive
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. include:: @top_srcdir@/examples/RE2C_LANG/reuse/usedir.re
     :literal:
     :code: RE2C_LANG
 
 Example of a ``/*!use:re2c ... */`` block
------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. include:: @top_srcdir@/examples/RE2C_LANG/reuse/reuse.re
     :literal:
     :code: RE2C_LANG
 
 Submatch extraction
-===================
-.. include:: @top_srcdir@/doc/manual/submatch/submatch.rst_
-.. include:: @top_srcdir@/doc/manual/submatch/submatch_example_stags.rst_
+-------------------
+.. include:: @top_srcdir@/doc/manual/features/submatch/submatch.rst_
+.. include:: @top_srcdir@/doc/manual/features/submatch/submatch_example_stags.rst_
 .. include:: @top_srcdir@/examples/RE2C_LANG/submatch/01_stags.re
     :literal:
     :code: RE2C_LANG
-.. include:: @top_srcdir@/doc/manual/submatch/submatch_example_stags_fill.rst_
+.. include:: @top_srcdir@/doc/manual/features/submatch/submatch_example_stags_fill.rst_
 .. include:: @top_srcdir@/examples/RE2C_LANG/submatch/01_stags_fill.re
     :literal:
     :code: RE2C_LANG
-.. include:: @top_srcdir@/doc/manual/submatch/submatch_example_captures.rst_
+.. include:: @top_srcdir@/doc/manual/features/submatch/submatch_example_captures.rst_
 .. include:: @top_srcdir@/examples/RE2C_LANG/submatch/03_captures.re
     :literal:
     :code: RE2C_LANG
-.. include:: @top_srcdir@/doc/manual/submatch/submatch_example_mtags.rst_
+.. include:: @top_srcdir@/doc/manual/features/submatch/submatch_example_mtags.rst_
 .. include:: @top_srcdir@/examples/RE2C_LANG/submatch/02_mtags.re
     :literal:
     :code: RE2C_LANG
 
 Encoding support
-================
-.. include:: @top_srcdir@/doc/manual/encodings/encodings.rst_
+----------------
+.. include:: @top_srcdir@/doc/manual/features/encodings/encodings.rst_
 .. include:: @top_srcdir@/examples/RE2C_LANG/encodings/unicode_identifier.re
     :literal:
     :code: RE2C_LANG
 
 Include files
-=============
-.. include:: @top_srcdir@/doc/manual/includes/includes.rst_
+-------------
+.. include:: @top_srcdir@/doc/manual/features/includes/includes.rst_
 
 Include file 1 (definitions.RE2C_HEADER_EXT)
-------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. include:: @top_srcdir@/examples/RE2C_LANG/includes/definitions.RE2C_HEADER_EXT
     :literal:
     :code: RE2C_LANG
 
 Include file 2 (extra_rules.re.inc)
------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. include:: @top_srcdir@/examples/RE2C_LANG/includes/extra_rules.re.inc
     :literal:
     :code: RE2C_LANG
 
 Input file
-----------
+~~~~~~~~~~
 .. include:: @top_srcdir@/examples/RE2C_LANG/includes/include.re
     :literal:
     :code: RE2C_LANG
 
 Header files
-============
-.. include:: @top_srcdir@/doc/manual/headers/headers.rst_
+------------
+.. include:: @top_srcdir@/doc/manual/features/headers/headers.rst_
 
 Input file
-----------
+~~~~~~~~~~
 .. include:: @top_srcdir@/examples/RE2C_LANG/headers/header.re
     :literal:
     :code: RE2C_LANG
 
 Header file
------------
+~~~~~~~~~~~
 .. include:: @top_srcdir@/examples/RE2C_LANG/headers/lexer/state.RE2C_HEADER_EXT
     :literal:
     :code: RE2C_LANG
 
 Skeleton programs
-=================
-.. include:: @top_srcdir@/doc/manual/skeleton/skeleton.rst_
+-----------------
+.. include:: @top_srcdir@/doc/manual/features/skeleton/skeleton.rst_
 
 Visualization and debug
-=======================
-.. include:: @top_srcdir@/doc/manual/dot/dot.rst_
+-----------------------
+.. include:: @top_srcdir@/doc/manual/features/dot/dot.rst_
 
 SEE ALSO
 ========