Re: DOCBOOK-APPS: SQL commands markup

[Norman Walsh <ndw@nwalsh.com>]

/ Gary Lawrence Murphy <garym@canada.com> was heard to say:
| >>>>> "N" == Norman Walsh <ndw@nwalsh.com> writes:
| 
|     N> I think we'd need some imput from SQL experts here. At first glance,
|     N>that looks like it could be:
| 
|     N> <cmdsynopsis role="sql"> <command>load data</command>
|     N><arg>low_priority</arg> <arg>local</arg> <arg choice="req">infile <arg
|     N>choice="req">'<replaceable>file_name.txt</replaceable>'</arg> </arg>
|     N><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.

Commands are explicitly not limited to command line options. I might
argue that "M-x fill-paragraph" is an Emacs "command". The semantics
of the SQL (given my limited understanding of SQL) look more like command
semantics to me than function semantics. FuncSynopsis has pretty
explicit presentation semantics that run counter to what I see in the
SQL. (Of course, you can change those semantics to support SQL if that
really is a function and not a command :-)

| I do wonder about the choice= attributes.  What is the semantic meaning of
| these?

They indicate whether or not the argument is required. I interpreted the
square brackets in the original SQL statement to indicate required vs.
optional arguments. Was I mistaken?

|  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.

Commands can have arguments or options. I just used the markup that I
thought made that most explicit.

| 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?

It seems reasonable, But that's what I intended as well. I think :-)

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | Another month ends. All targets met.
http://nwalsh.com/            | All systems working. All customers
                              | satisfied. All staff eager and
                              | enthusiastic. All pigs fed and ready
                              | for take off.