Re: Community improvements to the Emacs Widget Library manual?

[Bryce]

[...]

To quote the library,

    | This is the general syntax of a type specification:
    |
    |      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
    |           |   NAME
    |
    |    Where, NAME is a widget name, KEYWORD is the name of a
    | property, ARGUMENT is the value of the property, and ARGS are
    | interpreted in a widget specific way.

When I first approached the manual I had a difficult time understanding
the full meaning of this meta-language. I did not know what BNF or EBNF
are, and even after having a friend explain it to me I still struggled
to realize that NAME on the second bar is an alternative right-hand
side.

I'm a competent self-taught programmer (and I have a year of formal
education in CS under my belt), but I wasn't familialr with BNF. I now
know it is widely used when describing a formal language grammar, but we
should include something in the manual to at least make it clear that
this is what follows.

We /might/ elect to include a new manual in Emacs overall, or write a
new GNU manual to describe the concepts of Backus-Naur forms (BNF), or
Extended BNF. GNU Bison has a section (§1.1) in its manual which
describes some of the basic concepts of BNF and context-free grammars.
We might simply refer uses to that manual, or link to an external
reference document with a GPL compatible license which could be
redistributed by the FSF or another party friendly to GNU Emacs.


    | 5 Basic Types
    | *************
    |
    | This is the general syntax of a type specification:
    |
    |      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
    |           |   NAME
    |
    |    Where, NAME is a widget name, KEYWORD is the name of a property,
    | ARGUMENT is the value of the property, and ARGS are interpreted in a
    | widget specific way.

I feel there is some ambiguity in the description of this syntax as
well. NAME is said to be a widget name (the symbol which refers to the
type being defined), but in every following use of the syntax the
uppercase word "TYPE" is repeated verbatim, except for ITEM in §5.9.

Shouldn't all type specifications read as follows?

    | 5.5 The ‘editable-field’ Widget
    | ===============================
    |
    | Syntax:
    |
    |      EDITABLE-FIELD ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ])
    |
    |    The VALUE, if present, is used to initialize the ‘:value’ property.
    | The value should be a string, which will be inserted in the field.  This
    | widget will match all string values.

TYPE is said to be a type name, so it should be the name of the type
being specified throughout the manual. If I've misunderstood the grammar
or the description, we should instead correct the description in §5
(Basic Types) and fix ITEMs type.