Improve TOC and searchability of Firebird Language Reference

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Improve TOC and searchability of Firebird Language Reference

Mark Rotteveel-2
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: Improve TOC and searchability of Firebird Language Reference

Paul Vinkenoog
Hi Mark,

> I've been using the Firebird Language Reference for a while now, and I
> have some annoyances with its searchability.

8<

> 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.

I will look into the TOC issue this week. IIRC (it's been a while since
I did any extensive work on the transformation stylesheets) TOCs are
relatively easy to add and configure.

I also agree that some restructuring might be in order. But that will
take more time and we should be well prepared before we do this.
Personally I think finishing the LR proofreading has a higher priority.

> 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.

Frankly, I wonder why all these parameter tables should be formal tables
at all (and thus be present in that mile-long LOT), but at least they
serve a purpose now ;-)

> 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.

It took me a while before I saw this, but yes, I get the dollar sign
linking to the section. Not at all intuitive. Might be better to have
the title itself link to the section. Then again, with enough TOCs in
the right places (where you can also pick up the URLs) we could probably
do without this.


Cheers,
Paul Vinkenoog


------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: Improve TOC and searchability of Firebird Language Reference

Lester Caine
On 01/05/16 00:12, Paul Vinkenoog wrote:
> I will look into the TOC issue this week. IIRC (it's been a while since
> I did any extensive work on the transformation stylesheets) TOCs are
> relatively easy to add and configure.

Paul ... I still have my own local copy of the fbwiki which provided an
on-line editable view of the language reference. One of the main reasons
*I* use that is simply the easy at which the wiki search tools allow
finding relevant pages, and the backlink structure allows stepping back
through the document tree out of order.

Not really pushing any point, but I get pigged off with the PHP searches
now passing the buck to google to provide results and the mess that
brings. A search mechanism using firebird built into the website offers
a lot of possibilities including much better handing of translated pages ...

--
Lester Caine - G8HFL
-----------------------------
Contact - http://lsces.co.uk/wiki/?page=contact
L.S.Caine Electronic Services - http://lsces.co.uk
EnquirySolve - http://enquirysolve.com/
Model Engineers Digital Workshop - http://medw.co.uk
Rainbow Digital Media - http://rainbowdigitalmedia.co.uk

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: Improve TOC and searchability of Firebird Language Reference

Paul Vinkenoog
In reply to this post by Paul Vinkenoog
Hi all,

> I will look into the TOC issue this week. IIRC (it's been a while since
> I did any extensive work on the transformation stylesheets) TOCs are
> relatively easy to add and configure.

OK, that turned out to be infeasible from my holiday address, with a half-broken laptop and a limited Internet connection.

But I'm back now, and I've created a couple of alternatives. I will put them online tonight so we can compare.

Cheers,
Paul

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: Improve TOC and searchability of Firebird Language Reference

Paul Vinkenoog
Hi all,

>> I will look into the TOC issue this week. IIRC (it's been a while since
>> I did any extensive work on the transformation stylesheets) TOCs are
>> relatively easy to add and configure.

Presence and appearance of ToCs in the output are controlled by a number of XSLT parameters, the most important of which are:

- toc.section.depth
  determines the deepest section level that can appear in a ToC

- toc.max.depth
  determines the maximum depth (= number of levels) in any ToC
 
- generate.section.toc.level
  determines up to (or rather down to) which section level ToCs will be generated
  (for levels above section, like chapter and book, ToCs are always generated - at least by default)

Note: if generate.section.toc.level >= toc.section.depth, ToCs will be generated for that level, even though the child sections listed therein exceed toc.section.depth. Such ToCs will always be 1 level deep - i.e. they will only list the immediate subsections - regardless of toc.max.depth.

Please see http://firebird.vinkenoog.nl for a couple of alternatives.


Cheers,
Paul

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: Improve TOC and searchability of Firebird Language Reference

Mark Rotteveel-2
On 8-5-2016 03:32, Paul Vinkenoog wrote:

> Hi all,
>
>>> I will look into the TOC issue this week. IIRC (it's been a while since
>>> I did any extensive work on the transformation stylesheets) TOCs are
>>> relatively easy to add and configure.
>
> Presence and appearance of ToCs in the output are controlled by a number of XSLT parameters, the most important of which are:
>
> - toc.section.depth
>    determines the deepest section level that can appear in a ToC
>
> - toc.max.depth
>    determines the maximum depth (= number of levels) in any ToC
>
> - generate.section.toc.level
>    determines up to (or rather down to) which section level ToCs will be generated
>    (for levels above section, like chapter and book, ToCs are always generated - at least by default)
>
> Note: if generate.section.toc.level >= toc.section.depth, ToCs will be generated for that level, even though the child sections listed therein exceed toc.section.depth. Such ToCs will always be 1 level deep - i.e. they will only list the immediate subsections - regardless of toc.max.depth.
>
> Please see http://firebird.vinkenoog.nl for a couple of alternatives.

I think I'd prefer the last one, "Max. levels in each ToC: 3 - Deepest
section level in any ToC: 3 - Deepest section level for which ToCs are
created: 2"

In the main TOC it gives a clear overview, and it allows for quick
navigation to the right information.

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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: Improve TOC and searchability of Firebird Language Reference

Paul Vinkenoog
Hello Mark,

> > - toc.section.depth
> >    determines the deepest section level that can appear in a ToC
> >
> > - toc.max.depth
> >    determines the maximum depth (= number of levels) in any ToC
> >
> > - generate.section.toc.level
> >    determines up to (or rather down to) which section level ToCs will be generated
> >    (for levels above section, like chapter and book, ToCs are always generated - at least by default)
> >
> > Note: if generate.section.toc.level >= toc.section.depth, ToCs will be generated for that level, even though the child sections listed therein exceed toc.section.depth. Such ToCs will always be 1 level deep - i.e. they will only list the immediate subsections - regardless of toc.max.depth.
> >
> > Please see http://firebird.vinkenoog.nl for a couple of alternatives.
>
> I think I'd prefer the last one, "Max. levels in each ToC: 3 - Deepest
> section level in any ToC: 3 - Deepest section level for which ToCs are
> created: 2"
>
> In the main TOC it gives a clear overview, and it allows for quick
> navigation to the right information.

Personally, I think that 3-level ToCs become way too long and you can't see the forest for the trees anymore. This goes for the main ToC, but also for e.g. Chapter 8: Built-in functions and Variables http://firebird.vinkenoog.nl/fblangref-tsd3-tmd3-gstl2/fblangref25-functions.html

My preference would be the second variant (2 - 2 - 2), where no ToC has more than 2 levels and section ToCs are single-level. Since each top-level section has its own page, having a multilevel ToC at the top is not very useful IMO, as the subsections are on the same page and have their own ToCs. A good place to see the difference with "2 - 3 - 2" is the Scalar Functions section:

 http://firebird.vinkenoog.nl/fblangref-tsd2-tmd2-gstl2/fblangref25-functions-scalarfuncs.html
 http://firebird.vinkenoog.nl/fblangref-tsd3-tmd2-gstl2/fblangref25-functions-scalarfuncs.html

Anyway, let's hear some more opinions!

Cheers,
Paul

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: Improve TOC and searchability of Firebird Language Reference

firebirdlists
Hello Paul,

Monday, May 9, 2016, 12:08:27 AM, you wrote:


> My preference would be the second variant (2 - 2 - 2), where no ToC
> has more than 2 levels and section ToCs are single-level. Since each
> top-level section has its own page, having a multilevel ToC at the
> top is not very useful IMO, as the subsections are on the same page
> and have their own ToCs.

I prefer the second version too.  It uses a bit more real estate but
it means one doesn't have to keep reverting to the top-level TOC if
browsing for a specific function while not knowing exactly the one you
want.

I guess time will tell, once we see the feature in action with the
whole book and in the PDF.

Got your corrections for the BIN* functions, thanks.  I will probably
defer a new build until I have the new template on board.

Helen


------------------------------------------------------------------------------
Mobile security can be enabling, not merely restricting. Employees who
bring their own devices (BYOD) to work are irked by the imposition of MDM
restrictions. Mobile Device Manager Plus allows you to control only the
apps on BYO-devices by containerizing them, leaving personal data untouched!
https://ad.doubleclick.net/ddm/clk/304595813;131938128;j
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: Improve TOC and searchability of Firebird Language Reference

Paul Vinkenoog
Helen wrote:

>> My preference would be the second variant (2 - 2 - 2), where...

> I prefer the second version too.  It uses a bit more real estate but
> it means one doesn't have to keep reverting to the top-level TOC if
> browsing for a specific function while not knowing exactly the one you
> want.
>
> I guess time will tell, once we see the feature in action with the
> whole book and in the PDF.

The four HTML builds at firebird.vinkenoog.nl each comprise the entire
book.

But notice that the (local) changes I made only apply to multipage HTML.
Of course we can do the same for monohtml (as you use for the rlsnotes),
but we can also leave that build as-is or make other adjustments.

PDF is very different and already has the navigation pane, so local
ToCs are probably less useful there. However, we can do it if we want.
I've added a PDF with chapter ToCs to the above page as an example.

> Got your corrections for the BIN* functions, thanks.  I will probably
> defer a new build until I have the new template on board.

I'll commit the '2-2-2' variant then for now. But shall I do it just for
the refdocs set or for all our HTML docs?


Cheers,
Paul

------------------------------------------------------------------------------
Mobile security can be enabling, not merely restricting. Employees who
bring their own devices (BYOD) to work are irked by the imposition of MDM
restrictions. Mobile Device Manager Plus allows you to control only the
apps on BYO-devices by containerizing them, leaving personal data untouched!
https://ad.doubleclick.net/ddm/clk/304595813;131938128;j
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: Improve TOC and searchability of Firebird Language Reference

firebirdlists
Hello Paul,

Wednesday, May 11, 2016, 1:03:39 AM, you wrote:

> Helen wrote:

> But notice that the (local) changes I made only apply to multipage HTML.
> Of course we can do the same for monohtml (as you use for the rlsnotes),
> but we can also leave that build as-is or make other adjustments.

I've stopped using monohtml for release notes - so far, only the FB3
notes are multi-page but I have set up places in the web structure for
the others, when I get around to building them.  The reason for this
is the lack of breadcrumbs in the monohtml.

> PDF is very different and already has the navigation pane, so local
> ToCs are probably less useful there. However, we can do it if we want.
> I've added a PDF with chapter ToCs to the above page as an example.

Actually, the PDF bookmarks do the job efficiently, without resorting
to sub-TOCs - "not broke, don't fix" would be a good strategy,
methinks.

> I'll commit the '2-2-2' variant then for now. But shall I do it just for
> the refdocs set or for all our HTML docs?

It would likely make a big mess of release notes as, since v.2.0,
AFAIR, the DDL and DML sections have a hard-coded "TOC" at the
beginning of each of those chapters, anyway.  I am loath to start
mucking around with the sources of older release notes, which would
put them out of synch with the translations.

As for the other docs, I haven't worked with the sources of them.
Perhaps Norm would like to comment.

Helen


------------------------------------------------------------------------------
Mobile security can be enabling, not merely restricting. Employees who
bring their own devices (BYOD) to work are irked by the imposition of MDM
restrictions. Mobile Device Manager Plus allows you to control only the
apps on BYO-devices by containerizing them, leaving personal data untouched!
https://ad.doubleclick.net/ddm/clk/304595813;131938128;j
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: Improve TOC and searchability of Firebird Language Reference

Paul Vinkenoog
Hi Helen,

>> PDF is very different and already has the navigation pane, so local
>> ToCs are probably less useful there. However, we can do it if we want.
>> I've added a PDF with chapter ToCs to the above page as an example.
>
> Actually, the PDF bookmarks do the job efficiently, without resorting
> to sub-TOCs - "not broke, don't fix" would be a good strategy,
> methinks.

I agree, although I must say that chapter ToCs - not section ToCs -
in the LangRef may be useful. But we can always see about that later.

So for now, let's take the most conservative approach and apply this
change to the multi-page HTML build of the refdocs set only (i.e.
LangRef and LangRefUpds) and leave everything else untouched.

Cheers,
Paul

------------------------------------------------------------------------------
Mobile security can be enabling, not merely restricting. Employees who
bring their own devices (BYOD) to work are irked by the imposition of MDM
restrictions. Mobile Device Manager Plus allows you to control only the
apps on BYO-devices by containerizing them, leaving personal data untouched!
https://ad.doubleclick.net/ddm/clk/304595813;131938128;j
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Reply | Threaded
Open this post in threaded view
|

Re: Improve TOC and searchability of Firebird Language Reference

Paul Vinkenoog
Hi all,

> So for now, let's take the most conservative approach and apply this
> change to the multi-page HTML build of the refdocs set only (i.e.
> LangRef and LangRefUpds) and leave everything else untouched.

I've committed the changes.

Cheers,
Paul

------------------------------------------------------------------------------
Mobile security can be enabling, not merely restricting. Employees who
bring their own devices (BYOD) to work are irked by the imposition of MDM
restrictions. Mobile Device Manager Plus allows you to control only the
apps on BYO-devices by containerizing them, leaving personal data untouched!
https://ad.doubleclick.net/ddm/clk/304595813;131938128;j
_______________________________________________
Firebird-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/firebird-docs