Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview
Hello, Looks good! Thank you for your efforts, Mark! What is the next - Firebird Developers Guide? Or Quick Start Guide? Or something else? Regards, Alexey On 06.06.2020 11:37, Mark Rotteveel wrote: I have updated the documentation section on the site to point to the new version. Mark ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview
I have updated the documentation section on the site to point to the new version. Mark -- Mark Rotteveel ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview
Mark Rotteveel wrote: >> 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 must admit that the growth of functions is a good argument for keeping the thematic subdivision. > The current list of functions in each section should already be ordered > alphabetically, but I'll double check. Yes, it looks like they are. Cheers, Paul ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview
Mark Rotteveel 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 ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview
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
Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview
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
Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview
I favour option 1 then option 2 Mark. Cheers, Norm. -- Sent from my Android device with K-9 Mail. Please excuse my brevity.___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview
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. 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). I'm a bit split between option 2 and 3, but what do you think? Mark -- Mark Rotteveel ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview
Hello Mark, PDF link is the same as HTML. Regards, Alexey On 01.06.2020 18: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/html/en/refdocs/fblangref25/firebird-25-language-reference.html I haven't linked it yet from the documentation page, and I still need to do some changes like removing that incorrect caution we discussed earlier. This isn't a direct migration: after the migration I touched a lot of things (like syntax blocks) for consistency, and here and there I clarified or corrected some texts. I had to revert my changes to the padding of the tables in PDF, because it caused rather tight columns in Appendix B. Mark ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview
On 01-06-2020 18:09, Paul Vinkenoog wrote: Mark Rotteveel wrote: HTML: https://firebirdsql.org/file/documentation/html/en/refdocs/fblangref25/firebird-25-language-reference.html PDF: https://firebirdsql.org/file/documentation/html/en/refdocs/fblangref25/firebird-25-language-reference.html That's two links to the HTML ;-) Of course it wasn't rocket science to find the PDF: https://firebirdsql.org/file/documentation/pdf/en/refdocs/fblangref25/firebird-25-language-reference.pdf Thanks. I guess I forgot to 'copy' the link from my PDF browser tab before pasting in the email. Mark -- Mark Rotteveel ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Firebird 2.5 Language Reference migration preview
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/html/en/refdocs/fblangref25/firebird-25-language-reference.html > That's two links to the HTML ;-) Of course it wasn't rocket science to find the PDF: https://firebirdsql.org/file/documentation/pdf/en/refdocs/fblangref25/firebird-25-language-reference.pdf Cheers, Paul Vinkenoog ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
