We need to come up with some standards for our command helpdocs. Its not very evident when you only list the help docs for 1 command at a time, but if you do a \help -d, you will notice all the short descriptions of the command and how they are not standardized in any way.
task: come up with a standard for command descriptions.
currently -d option will extract the first sentence in the description of the command.
|
32 KB
influenced by http://ss64.com/bash/alias.html
I made the command descriptions more direct and immediate
"Creates an alias"
becomes the more active
"Create an alias"
Let me know if these are improvements over the existing version.
alias Create an alias, aliases allow a string to be substituted for a word when it is used as the first word of a simple command
ask Allows typing a value directly into a variable
autocommit Control the current connection's autocommit mode
cat Concatenate and print files
cd Change the current working directory
change Change the current connection database or schema
clear Clear the terminal screen
cli Command line interface configuration tool
commit End the current transaction and make permanent all changes performed in the transaction
compare Compare files
connect Establish a connection to a database
cp Copy files
declare Declare variables and/or give them attributes
describe Display information about the columns as well as access privileges in an OBJECT which can be either a table or a view
disconnect Disconnect the current connection
echo Write arguments to the standard output
exec Execute a command
export Set the export attribute for the shell variables specified by NAMEs
fluidshell Open a new fluidshell tab
go Send the contents of the Work Buffer to the database
grep Search file(s) for specific text
gunzip Decompress named files using the GZIP algorithm
gzip Compress named files using the GZIP algorithm
help Display helpful information about commands
history Command Line history
list Display the currently connected database or displays the list of databases, schemas, tables or views defined in the connected RDBMS server
ls List information about files
mkdir Create named directories, if they do not already exist
more Display output one screen at a time
mv Move or rename files or directories
open Open a file in its default application
pwd Print the working directory
reconnect Force a reconnection to the database using a new database, username, or password
rename Rename a file or a directory
rm Remove named files and directories
rmdir Remove named directories, if they are empty
rollback Rolls back the current transaction to the beginning of that transaction
run Executes an OS Command
scp Secure copy
sendmail Send a message to one or more recipients
sleep Delay for a specified time, pause for an amount of time specified by the sum of the values of the command line arguments
source Execute a script from a file
sqlbuffer Work with the local shell's sql buffer
sqlexport Retreive data from the named Table(s) and writes the result to the Destination file
sqlhistory Display the SQL statement history table
sqlimport Import data stored in FILE into TABLE
ssh Open an SSH terminal tab
syncdir Synchronize the DESTINATION directory with files and sub-directories as defined in the SOURCE directory
tail Print the last 10 lines of each FILE; with more than one FILE, precedes each with a header giving the file name
tar Store, list or extract files in an archive
tee Redirect output to multiple files, copies standard input to standard output and also to any files given as arguments
touch Update the last-modified time of each named FILE to the current time
unalias Remove NAME alias
unset Destroy one or more variables
unzip Extract files from a ZIP archive to the named directory, or current directory if no directory specified
zip Compressand pack FILE(s) into a single ZIP archive that is compatible with PKZIP
example of man pages syntax conventions... We currently don't have standards for this, but we should come up with some.
Convention |
Used for |
---|---|
UPPERCASE |
Transact-SQL keywords. |
italic |
User-supplied parameters of Transact-SQL syntax. |
bold |
Database names, table names, column names, index names, stored procedures, utilities, data type names, and text that must be typed exactly as shown. |
underline |
Indicates the default value applied when the clause that contains the underlined value is omitted from the statement. |
| (vertical bar) |
Separates syntax items enclosed in brackets or braces. You can use only one of the items. |
[ ] (brackets) |
Optional syntax items. Do not type the brackets. |
{ } (braces) |
Required syntax items. Do not type the braces. |
[,...n] |
Indicates the preceding item can be repeated n number of times. The occurrences are separated by commas. |
[...n] |
Indicates the preceding item can be repeated n number of times. The occurrences are separated by blanks. |
; |
Transact-SQL statement terminator.Although the semicolon is not required for most statements in this version of SQL Server, it will be required in a future version. |
<label> ::= |
The name for a block of syntax. This convention is used to group and label sections of lengthy syntax or a unit of syntax that can be used in more than one location within a statement. Each location in which the block of syntax can be used is indicated with the label enclosed in chevrons: <label>. A set is a collection of expressions, for example <grouping set>; and a list is a collection of sets, for example <composite element list>. |
example of man pages syntax conventions... We currently don't have standards for this, but we should come up with some.
Convention |
Used for |
---|---|
UPPERCASE |
Transact-SQL keywords. |
italic |
User-supplied parameters of Transact-SQL syntax. |
bold |
Database names, table names, column names, index names, stored procedures, utilities, data type names, and text that must be typed exactly as shown. |
underline |
Indicates the default value applied when the clause that contains the underlined value is omitted from the statement. |
| (vertical bar) |
Separates syntax items enclosed in brackets or braces. You can use only one of the items. |
[ ] (brackets) |
Optional syntax items. Do not type the brackets. |
{ } (braces) |
Required syntax items. Do not type the braces. |
[,...n] |
Indicates the preceding item can be repeated n number of times. The occurrences are separated by commas. |
[...n] |
Indicates the preceding item can be repeated n number of times. The occurrences are separated by blanks. |
; |
Transact-SQL statement terminator.Although the semicolon is not required for most statements in this version of SQL Server, it will be required in a future version. |
<label> ::= |
The name for a block of syntax. This convention is used to group and label sections of lengthy syntax or a unit of syntax that can be used in more than one location within a statement. Each location in which the block of syntax can be used is indicated with the label enclosed in chevrons: <label>. A set is a collection of expressions, for example <grouping set>; and a list is a collection of sets, for example <composite element list>. |
Perhaps we should follow UNIX man page layout and add the following sections:
NAME
SYNOPSIS
The short description from the NAME section can be used by 'help -d', extract the first sentence from the DESCRIPTION section deos not sound right.
Perhaps we should follow UNIX man page layout and add the following sections:
NAME
SYNOPSIS
The short description from the NAME section can be used by 'help -d', extract the first sentence from the DESCRIPTION section deos not sound right.
Added NAME and SYNOPSIS sections to all of fluid man pages. 'help -d' now displays the short description from the NAME section. Output of 'help -d' is listed below FYI:
alias : define or print aliases
ask : define a variable interactively
autocommit : set or print the current connection's autocommit mode
cat : concatenate files and print on the standard output
cd : change the current working directory
change : change or print current connection's database or schema
clear : clear the terminal screen
cli : configure command line interface
commit : make database changes permanent
compare : compare files line by line
connect : establish a database connection
cp : copy files and directories
declare : define or print variables
describe : provide information about database objects
disconnect : close the current database connection
echo : display a line of text
exec : execute an OS command
export : export variables to the environment of subsequently executed commands
fluidshell : open a new fluidshell tab
go : execute database statements
grep : print lines matching a pattern
gunzip : uncompress files
gzip : compress files
help : an interface to the on-line reference manuals
history : display the command history list
list : display databases, schemas, tables or views defined in a database server
ls : list directory contents
mkdir : make directories
more : file perusal filter for viewing
mv : move (rename) files
open : open files
pwd : print the current working directory
reconnect : reestablish a database connection
rename : rename a file or a directory
rm : remove files or directories
rmdir : remove empty directories
rollback : undo database changes
run : execute an OS command asynchronously
scp : secure copy
sendmail : send a message to one or more recipients
sleep : delay for a specified amount of time
source : execute commands or SQL statements from a file
sqlbuffer : manage shell's SQL buffer
sqlexport : export data from database tables into files
sqlhistory : display the SQL statement history table
sqlimport : import data from a file into a database table
ssh : run SSH client in a new tab
syncdir : synchronize directories
tail : output the last part of files
tar : a simple version of the tar archiving utility
tee : read from standard input and write to standard output and file
touch : change file timestamps
unalias : remove aliases
unset : remove variables
unzip : extract compressed files in a ZIP archive
zip : package and compress files into a ZIP archive
Added NAME and SYNOPSIS sections to all of fluid man pages. 'help -d' now displays the short description from the NAME section. Output of 'help -d' is listed below FYI:
alias : define or print aliases
ask : define a variable interactively
autocommit : set or print the current connection's autocommit mode
cat : concatenate files and print on the standard output
cd : change the current working directory
change : change or print current connection's database or schema
clear : clear the terminal screen
cli : configure command line interface
commit : make database changes permanent
compare : compare files line by line
connect : establish a database connection
cp : copy files and directories
declare : define or print variables
describe : provide information about database objects
disconnect : close the current database connection
echo : display a line of text
exec : execute an OS command
export : export variables to the environment of subsequently executed commands
fluidshell : open a new fluidshell tab
go : execute database statements
grep : print lines matching a pattern
gunzip : uncompress files
gzip : compress files
help : an interface to the on-line reference manuals
history : display the command history list
list : display databases, schemas, tables or views defined in a database server
ls : list directory contents
mkdir : make directories
more : file perusal filter for viewing
mv : move (rename) files
open : open files
pwd : print the current working directory
reconnect : reestablish a database connection
rename : rename a file or a directory
rm : remove files or directories
rmdir : remove empty directories
rollback : undo database changes
run : execute an OS command asynchronously
scp : secure copy
sendmail : send a message to one or more recipients
sleep : delay for a specified amount of time
source : execute commands or SQL statements from a file
sqlbuffer : manage shell's SQL buffer
sqlexport : export data from database tables into files
sqlhistory : display the SQL statement history table
sqlimport : import data from a file into a database table
ssh : run SSH client in a new tab
syncdir : synchronize directories
tail : output the last part of files
tar : a simple version of the tar archiving utility
tee : read from standard input and write to standard output and file
touch : change file timestamps
unalias : remove aliases
unset : remove variables
unzip : extract compressed files in a ZIP archive
zip : package and compress files into a ZIP archive
Went through the command descriptions from above, I would add a 'the' article for the following cases:
* cli : configure the command line interface
* ssh : run the SSH client in a new tab
as they refer to something specific.
This would be similar with the cases from:
* clear : clear the terminal screen
* sqlhistory : display the SQL statement history table
Otherwise they look great respecting the same format, with minor exceptions for \help, \more, and \tar.
Went through the command descriptions from above, I would add a 'the' article for the following cases:
* cli : configure the command line interface
* ssh : run the SSH client in a new tab
as they refer to something specific.
This would be similar with the cases from:
* clear : clear the terminal screen
* sqlhistory : display the SQL statement history table
Otherwise they look great respecting the same format, with minor exceptions for \help, \more, and \tar.
>> Went through the command descriptions from above, I would add a 'the' article for the following cases:
>> * cli : configure the command line interface
>> * ssh : run the SSH client in a new tab
>> as they refer to something specific.
Done.
>> Went through the command descriptions from above, I would add a 'the' article for the following cases:
>> * cli : configure the command line interface
>> * ssh : run the SSH client in a new tab
>> as they refer to something specific.
Done.
Issue #6837 |
Closed |
Fixed |
Resolved |
Completion |
No due date |
Fixed Build trunk/28710 |
No time estimate |
influenced by http://ss64.com/bash/alias.html
I made the command descriptions more direct and immediate
"Creates an alias"
becomes the more active
"Create an alias"
Let me know if these are improvements over the existing version.
alias Create an alias, aliases allow a string to be substituted for a word when it is used as the first word of a simple command
ask Allows typing a value directly into a variable
autocommit Control the current connection's autocommit mode
cat Concatenate and print files
cd Change the current working directory
change Change the current connection database or schema
clear Clear the terminal screen
cli Command line interface configuration tool
commit End the current transaction and make permanent all changes performed in the transaction
compare Compare files
connect Establish a connection to a database
cp Copy files
declare Declare variables and/or give them attributes
describe Display information about the columns as well as access privileges in an OBJECT which can be either a table or a view
disconnect Disconnect the current connection
echo Write arguments to the standard output
exec Execute a command
export Set the export attribute for the shell variables specified by NAMEs
fluidshell Open a new fluidshell tab
go Send the contents of the Work Buffer to the database
grep Search file(s) for specific text
gunzip Decompress named files using the GZIP algorithm
gzip Compress named files using the GZIP algorithm
help Display helpful information about commands
history Command Line history
list Display the currently connected database or displays the list of databases, schemas, tables or views defined in the connected RDBMS server
ls List information about files
mkdir Create named directories, if they do not already exist
more Display output one screen at a time
mv Move or rename files or directories
open Open a file in its default application
pwd Print the working directory
reconnect Force a reconnection to the database using a new database, username, or password
rename Rename a file or a directory
rm Remove named files and directories
rmdir Remove named directories, if they are empty
rollback Rolls back the current transaction to the beginning of that transaction
run Executes an OS Command
scp Secure copy
sendmail Send a message to one or more recipients
sleep Delay for a specified time, pause for an amount of time specified by the sum of the values of the command line arguments
source Execute a script from a file
sqlbuffer Work with the local shell's sql buffer
sqlexport Retreive data from the named Table(s) and writes the result to the Destination file
sqlhistory Display the SQL statement history table
sqlimport Import data stored in FILE into TABLE
ssh Open an SSH terminal tab
syncdir Synchronize the DESTINATION directory with files and sub-directories as defined in the SOURCE directory
tail Print the last 10 lines of each FILE; with more than one FILE, precedes each with a header giving the file name
tar Store, list or extract files in an archive
tee Redirect output to multiple files, copies standard input to standard output and also to any files given as arguments
touch Update the last-modified time of each named FILE to the current time
unalias Remove NAME alias
unset Destroy one or more variables
unzip Extract files from a ZIP archive to the named directory, or current directory if no directory specified
zip Compressand pack FILE(s) into a single ZIP archive that is compatible with PKZIP