I've been using the Firebird Language Reference for a while now, and I
have some annoyances with its searchability.
As an example, yesterday I was looking for a built-in function. The TOC
unhelpfully only lists:
8. Built-in functions and Variables
Context variables
Scalar Functions
Aggregate Functions
If I go to "Scalar Functions" I have:
Functions for Working with Context Variables
Mathematical Functions
Functions for Working with Strings
Date and Time Functions
Type Casting Functions
Functions for Bitwise Operations
Functions for Working with UUID
Functions for Working with Generators (Sequences)
Conditional Functions
And if I then go to "Functions for Working with Strings" I am on my own.
At minimum I would like each of these sections to have a TOC of their
own, so I can 1) quickly navigate to the right function and 2) easily
link to them without having to dive into the HTML for the section id.
However compare this to the Firebird 2.5 Language Reference **Update**,
where "Context variables", "Aggregate functions" and "Internal
functions" are chapters on their own and the function names are listed
in the main TOC, which makes it a lot simpler to go directly to the
function you want.
As another example, I was looking for the section on Global Temporary
Tables. The TOC only has:
5. Data Definition (DDL) Statements
DATABASE
SHADOW
DOMAIN
TABLE
INDEX
VIEW
TRIGGER
PROCEDURE
EXTERNAL FUNCTION
FILTER
SEQUENCE (GENERATOR)
EXCEPTION
COLLATION
CHARACTER SET
ROLE
COMMENTS
When I go to TABLE, I get
CREATE TABLE
ALTER TABLE
DROP TABLE
RECREATE TABLE
And from CREATE TABLE I am on my own, and have to look myself for the
section "Global Temporary Tables (GTT)" (which - on my screen - is 7
pages down from the start of CREATE TABLE). And if I want to link to it,
I again have to dive into the HTML to get the section id.
In general I think the searchability of the documentation would be
greatly improved if the TOC was three levels deep, and/or if the
sections were reorganized. It would also be helpful if chapters and
important sections start with a TOC of that section, and where already
present, a TOC with more levels might be helpful.
Sometimes I can only get quickly to a section by the presence of the
"List of Tables" in the TOC. But the anchor is not the right anchor for
the section as a whole, which makes it less suitable for linking.
It would also be helpful if sections themselves have a self-referencing
link. For an example see http://asciidoctor.org/docs/user-manual/ where
the mouseover on a section titles, will display a symbol that links to
the section. This allows for quickly and easily getting the URL to that
specific section.
Mark
--
Mark Rotteveel
------------------------------------------------------------------------------
Find and fix application performance issues faster with Applications Manager
Applications Manager provides deep performance insights into multiple tiers of
your business applications. It resolves application problems quickly and
reduces your MTTR. Get your free trial!
https://ad.doubleclick.net/ddm/clk/302982198;130105516;z
_______________________________________________
Firebird-docs mailing list
Firebird-docs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/firebird-docs
