SQL Reference: too long page without subsections

[msiomkin]

https://www.tarantool.io/en/doc/latest/reference/reference_sql/sql/

1. The page is too long and definitely should be split into several pages.
2. Each page should contain a table of subsections at the beginning. The tree on the side panel also should contain these subsections.

[pgulutzan]

SQL Reference
https://www.tarantool.io/en/doc/latest/reference/reference_sql/
has five parts:
SQL beginners’ guide
SQL user guide
SQL statements and clauses
SQL PLUS LUA – Adding Tarantool/NoSQL to Tarantool/SQL
SQL features
which we could split into five pages, if everyone wanted that.
(I do not, I found that it is easier to navigate within this page
rather than jumping back and forth between pages, but if
everyone else agrees with you that's fine.)

The SQL statements and clauses part
https://www.tarantool.io/en/doc/latest/reference/reference_sql/sql/#sql-statements-and-clauses
and the SQL Plus Lua part
https://www.tarantool.io/en/doc/latest/reference/reference_sql/sql/#sql-plus-lua-adding-tarantool-nosql-to-tarantool-sql
are already split up into sections, and the section headers
appear in the table of contents on the left of the page
(which I believe is what is meant by "the tree on the side panel").

The SQL beginners' guide part
https://www.tarantool.io/en/doc/latest/reference/reference_sql/sql/
is an introduction whose short materials will be explained in later
parts. For example it has a paragraph about "Creating an index"
but the main description is in the SQL Statements and Clauses
https://www.tarantool.io/en/doc/latest/reference/reference_sql/sql/#create-index
so if we put "Creating an index" in the table of contents in the
left we might confuse the reader -- the table of contents on the
left of the page would have both "Creating an index" and "CREATE INDEX".

The SQL Features part
https://www.tarantool.io/en/doc/latest/reference/reference_sql/sql-features/
is just a single table of features, splitting it into sub-sections
would make no sense, and so the table of contents on the left of the
page has only one entry.

So, mostly, the current situation is desirable.
But of course, if there is a specific matter that clearly is in error
-- a missing heading, a markup error, etc. --
then it should be addressed. So please give examples that show
exactly where these matters are.

[msiomkin]

I believe that each of the five parts should be a separate page with table of subsections at the beginning!

[pgulutzan]

@lenkis: I can try the suggestions of @msiomkin thus: I will assign this issue to myself, split sql.rst into five files in the reference_sql directory, change the markdown of the headers, add more headers, and put a directory at the start of each file. Then I will push only to version 2.5, so that people can easily compare with the format in version 2.4 and decide whether they like Mike Siomkin's way better. If there are no objections, I'll try tomorrow (2020-10-22).

[pgulutzan]

@msiomkin: Please look at
https://www.tarantool.io/en/doc/2.5/reference/reference_sql/
which now has smaller pages. For some, there are tables of contents on the top and on the left.
Is this what you wanted?
If so, if you find anyone else who thinks it is better than
https://www.tarantool.io/en/doc/2.4/reference/reference_sql/
then I will copy to the latest version. Otherwise I think we should revert the changes marked "Fixes gh-1612".

[msiomkin]

@pgulutzan yes, I think it's much better now.

If so, if you find anyone else who thinks it is better than ... then I will copy to the latest version

How do you suggest we should make a polling? ) Here? In a telegram channel?

[pgulutzan]

Ask anybody at all. If one person thinks it is better, fine.

[pgulutzan]

This is now settled via Telegram chat. An overwhelming majority said version 2.5 is better. The change has been copied to version 2.6 as well. @msiomkin: are you satisfied?

[pgulutzan]

I will assume this is satisfactory. If somebody thinks the same change should apply to version 2.4, no problem, just re-open this issue.

[msiomkin]

are you satisfied?

Yes, it's great now, thank you!