Re: “Function finder”, issue #1469

> 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