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


_______________________________________________
Firebird-docs mailing list
Firebird-docs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/firebird-docs

Reply via email to