Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview

[Simonov D. <sim...@li...>]

Mark Rotteveel <ma...@la...> wrote Wed, 03 Jun 2020 21:37:12  
+0300:

> On 01-06-2020 17:52, Mark Rotteveel wrote:
>> I have migrated the Firebird 2.5 Language Reference, and it is  
>> available for preview on:
>>  HTML:  
>> https://firebirdsql.org/file/documentation/html/en/refdocs/fblangref25/firebird-25-language-reference.html  
>>  PDF:
> https://firebirdsql.org/file/documentation/pdf/en/refdocs/fblangref25/firebird-25-language-reference.pdf
>
> I have found an issue (which already existed in the TOC page of the old  
> PDF) which I think is annoying for usability. In the 'Built-in functions  
> and Variables' chapter, the actual functions don't appear in the TOC,  
> because they are on the fourth level. This makes them harder to find.
>
> There are several ways to address this:
>
> 1. Increase the TOC depth to 4. Overall, I thinks this inflates the TOC  
> too much.
>
> 2. Add a section TOC to the sections of 'Scalar Functions'. Defining  
> these TOCs would be manual work, but the advantage is that the list is  
> 'inline' in the main body of text.

I prefer this option


> 3. Remove the section 'Scalar Functions', so the sections inside it go a  
> level up. This would be the simplest, but reduces the organization of  
> the chapter.

Firebird 4.0 has a lot more function subgroups. There at least security  
functions are added (encryption, etc.)

>
> 4. Split chapter 'Built-in functions and Variables' into three chapters,  
> 'Context Variables', 'Scalar Functions' and 'Aggregate Functions'. This  
> will fix the immediate problem, but feels a bit strange to do, and  
> reduces the cohesion (especially between Scalar Functions and Aggregate  
> Functions).

Don’t forget that there are still window functions in Firebird 3.0.

>
> I'm a bit split between option 2 and 3, but what do you think?
>
> Mark


-- 
Simonov Denis