Menu
▾
▴
Re: [Firebird-docs] Improve TOC and searchability of Firebird Language Reference
|
From: Paul V. <pa...@vi...> - 2016-05-08 12:08:39
|
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 |