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