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

[Mark R. <ma...@la...>]

On 2020-06-04 11:37, Paul Vinkenoog wrote:
> Mark Rotteveel wrote:
>> There are several ways to address this:
>> 
>> 1. Increase the TOC depth to 4. Overall, I thinks this inflates the 
>> TOC
>> too much.
> 
> Agreed. However, I would be in favour of extending the number of 
> 'Bookmarks'
> (i.e. the links in the nav pane) levels to four. We had this in our 
> previous
> build system and it works fine, provided the PDF doesn't open with all 
> levels
> expanded by default. (We had this set at one level, i.e. chapter level 
> in a
> book, and top section level in an article.)
> 
> Would that be possible in the current system as well?

I will need to double check, by default the depth is tied to the depth 
of the TOC, but I found mention of a property (outlinelevels) that might 
control this separately (both depth and what is expanded). However, that 
would be specific to the PDF. For the HTML I would need to increase the 
TOC depth overall.

>> 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 personally don't like inline ToCs in the text. They don't really help
> navigation if you're ten pages down. I'd rather have all levels 
> available in
> the bookmarks then.

Ok, that makes sense. I was more thinking about a solution for going to 
- for example - the "Functions for Working with Strings" section, and 
then seeing the entire list and go from there.

>> 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.
>> 
>> 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).
> 
> 5. Split chapter 'Built-in functions and Variables' into two chapters:
> 'Context variables' and 'Internal Functions' (the latter without 
> further
> subdivisions for scalar vs. aggregate functions).
> 
> I'd be in favour of this regardless of the ToC issue.
> 
> I also don't like the thematic subdivisioning of the current Scalar 
> Functions
> chapter. It has certain advantages, but they are small in my opinion.

I generally like the subdivision by target datatype: it allows me to 
drill down quickly to what I need, while also supporting looking for a 
function for say - string manipulation - without knowing its name (or 
even its existence) and not getting distracted by functions for other 
datatypes. Especially with the growth of functions in Firebird 3 and 
Firebird 4, such a sub-division seems a good thing to retain to me.

> I think it's far more practical to have the functions ordered 
> alphabetically.
> In most cases, the name tells you immediately what kind of function it 
> is.
> Furthermore, this is a reference guide, not a language course or 
> tutorial.
> Most people will look here for information on a function whose name 
> they
> already know or can reasonably guess. (Again, this wil work best if you
> can click the list open in the nav pane.)
> 
> Option 4 is also fine IMO, but please with alphabetic ordering.

Right now I'm leaning to option 4 (subdivision per primary datatype of a 
function, with the chapter division you proposed under option 5.

The current list of functions in each section should already be ordered 
alphabetically, but I'll double check.

Mark