Mark Rotteveel wrote: > > 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.
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? > 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. > 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 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. Paul Vinkenoog _______________________________________________ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
