Re: DOCBOOK-APPS: SQL commands markup

[Gary Lawrence Murphy <garym@canada.com>]

>>>>> "N" == Norman Walsh <ndw@nwalsh.com> writes:

    N> I think we'd need some imput from SQL experts here. At first
    N> glance, that looks like it could be:

    N> <cmdsynopsis role="sql"> <command>load data</command>
    N> <arg>low_priority</arg> <arg>local</arg> <arg
    N> choice="req">infile <arg
    N> choice="req">'<replaceable>file_name.txt</replaceable>'</arg>
    N> </arg> <group> <arg>replace</arg> <arg>ignore</arg> </group>
    N> ...  </cmdsynopsis>

The only comment I would make here is to distinguish from commands,
which I take to be command line commands, and functions, which I take
to be computer language builtins.  Thus I would do the markup the
same as here, but make "load data" into a function rather than a
command.  I'd save command for dataserver utilities such as bcp or
isql.

I do wonder about the choice= attributes.  What is the semantic meaning
of these?  Also, with the group tag, does this denote a list of
optional items?  I would instead thing that replace and ignore would
be options rather than args, as would low_priority and local.

What we want is a means to delimit what is optional from what is required,
and to denote what goes together.  Ideally, I would expect a cmdsynopsis
(or is it a function synopsis?) to mirror the BNF notation for the function.

Thus I would have (totally naively and without regard for SGML correctness)

<cmdsynopsis role="sql">
<function>load data</function>
        <group>
                <option>low_priority</option>
                <option>local</option>
        </group>
        <arg>infile <replaceable>file_name.txt</replaceable></arg>
        <group>
                <option>replace</option>
                <option>ignore</option>
        </group>
</cmdsynopsis>

I intend this to mean that "infile data.dat" is _required_ although
the filename is obviously variable, while the other keywords are
literal keywords but are optional and order is arbitrary within each
group.

Do I have this correct?

-- 
Gary Lawrence Murphy <garym@teledyn.com> TeleDynamics Communications Inc
Business Innovations Through Open Source Systems: http://www.teledyn.com
"Computers are useless.  They can only give you answers."(Pablo Picasso)