Re: “Function finder”, issue #1469

 > I appreciate your efforts, Dimitre, but I’m troubled by the formatting
that results.
> The fact that the arrow (or the ellipsis; and yes, I agree, the ellipses
is nicer) *must *appear
> on the next line is distracting to my eyes. And uses a lot of vertical
space.

Norm, actually the ellipses must not appear on the next line and what we
see is solely due to the current styling (css classes) of the document.

One can verify this if the html file is placed not in
...\qtspecs\build\www\xpath-functions-40   but in any other, arbitrary
directory.Then the .css files are not found and not applied.

Then opening the document in the browser shows the ellipses on the same
line. Have a look at the screen snapshot below taken when the file was
placed in the \temp directory, and then opened.

I am not too-good at CSS and the people who produced the current styling
are the best to adjust it so that the ellipses appear on the same line.

[image: image.png]


> The follow-on questions are:
>
> Does the document, in its current, imperfect state satisfy the needs of
implementors?
>
> What changes should we make to improve it for its target audience?

I cannot answer as an implementor (not being one), but having ways for
faster navigation and seeing exactly what one currently needs, is a benefit
for any type of reader - implementor or not.

As for the second question above, I hope that I am part of the target
audience, and it is a very significant improvement to be able to quickly
navigate through only those parts of the huge TOC, in which I have been
interested lately.

I have attached a third (zipped) html file - here any section that has
subsections, regardless of its level, is collapsible/expandable.

Thanks,
Dimitre


On Wed, Oct 30, 2024 at 9:17 AM Norm Tovey-Walsh <norm@saxonica.com> wrote:

> > Norm, I would appreciate it if you try it and if anyone shares any
> impressions/comments.
>
> Yes, it would be nice to hear what others think.
>
> I appreciate your efforts, Dimitre, but I’m troubled by the formatting
> that results. The fact that the arrow (or the ellipsis; and yes, I agree,
> the ellipses is nicer) must appear on the next line is distracting to my
> eyes. And uses a lot of vertical space.
>
> I don’t actually find the collapsed ToC very useful. If a ToC that can be
> expanded and collapsed is something we want, I think we’ll have to bite the
> bullet and do more of it in JavaScript. I think it needs at least “expand
> all” and “collapse all” buttons.
>
> The document has grown organically, as these things always do, and maybe
> we need to think about the actual information architecture problem at a
> higher level than just tweaking the ToC.
>
> Just looking at the top level sections,
>
>     1 Introduction
>     2 Functions on nodes and node sequences
>     3 Errors and diagnostics
>     4 Functions and operators on numerics
>     5 Functions on strings
>     6 Functions that manipulate URIs
>     7 Functions and operators on Boolean values
>     8 Functions and operators on durations
>     9 Functions and operators on dates and times
>     10 Functions related to QNames
>     11 Operators on base64Binary and hexBinary
>     12 Operators on NOTATION
>     13 Functions and operators on sequences
>     14 Parsing and serializing
>     15 Context functions
>     16 Higher-order functions
>     17 Maps
>     18 Arrays
>     19 Constructor functions
>     20 Casting
>     A References
>     B Error summary
>     C Schemas
>     D Glossary
>     E Other Functions
>     F Checklist of implementation-defined features
>     G Changes since version 3.1
>     H Compatibility with Previous Versions
>
>     That’s slightly messy. If we collapse all the actual function and
> operator sections under one heading (and ignore the non-normative
> appendixes), we get:
>
>     1 Introduction
>     3 Errors and diagnostics
>     2 Functions and Operators
>     14 Parsing and serializing
>     16 Higher-order functions
>     17 Maps
>     18 Arrays
>     20 Casting
>     A References
>     B Error summary
>     C Schemas
>
> Which still looks a little messy.
>
> The most paramount question, I think, is “who is this document for?”
>
> I think it’s a language specification for implementors.
>
> (Yes, language users are going to refer to it. Especially in the
> short-to-medium term when books and articles and tutorials haven’t caught
> up with 4.0 yet, but we aren’t writing documentation for users. We’re
> trying to write documentation that users can understand, of course, but it
> isn’t a user guide.)
>
> The follow-on questions are:
>
> Does the document, in its current, imperfect state satisfy the needs of
> implementors?
>
> What changes should we make to improve it for its target audience?
>
> We have limited resources and we want to finish in the next few years.
> Undertaking a substantial editorial task that won’t advance the language
> and won’t provide a substantial payoff for the intended audience, is not
> something to undertake lightly.
>
>                                         Be seeing you,
>                                           norm
>
> --
> Norm Tovey-Walsh
> Saxonica
>