*****

1. Proposed user commands file format standard for chat clients

1.1. (note: each line is numbered for easy reference while arguing about it)
1.1.1. (note: all it takes for an argument is 1 free(dom) software user)
1.1.2. (note: the above is both wrong and the result of some cultish belief)
1.1.3. (note: your mama)

1.2. started: 2002-10-20
1.2.1. revised: 2002-10-21
1.2.2. extended: 2002-10-22
1.2.3. rewritten: 2002-10-22
1.2.4. reduced, accepted by "the_cpu_fan" and "buy_more_pepsi": 2002-10-26
1.2.5. revised: 2002-10-28

1.3. line numbering: <section>.<subsection>.<line>
1.3.1. repeat (.<subsection>.<line>) as needed

1.4. Cleanup of this document will be done when the standard settles more.

*****

2. current formats

2.1. gyach format

2.1.1. <name>]<command>|[optional alternate command with substitution variables]
2.1.1.1.  following '<name>]' with ':' = emote, '!' = shell, '!!' = local-only

2.2. curfloo format

2.2.1. <name>:<command>
2.2.1.2. following '<name>:' with ':' = emote, '!' = shell, '!!' = local-only

2.3. curphoo format

2.3.1.   :<name>
2.3.1.1. <command>
2.3.1.2.  preceeding ':<name>' with 2nd ':' = emote

2.3.2.   !<name>
2.3.2.1. <shell command>
2.3.2.2.  preceeding '!<name>' with 2nd '!' = local-only

2.4. Common:

2.4.1. Notations
2.4.1.1. : = comment to chat
2.4.1.2. :: = emote to chat
2.4.1.3. ! = shell command, echo to chat
2.4.1.4. !! = shell command, local-only echo

2.5. Distinguishing:

2.5.1. <name><separator><command> -- gyach, curfloo

2.5.2. <command>|<alt command> -- gyach only

2.5.3. multi-line, preformatted -- curphoo only

2.5.4. substitution variables

2.5.4.1. $0 = user name in gyach
2.5.4.2. %s = all typed after /<name> in curphoo
2.5.4.3. $* = all typed after /<name> in curfloo
2.5.4.4. $0 = <name> in curfloo
2.5.4.5. $1 - $9 = treat all after /<name> as space-separated list

*****

3. Proposed 2002-10-21

3.1. by "edge-op"

3.2. <foo>=req'd, [bar]=opt, foobar=const
3.2.1. filename = ~/.<client>/commands
3.2.1.1. REVISION: see 3.7.
3.2.2. 1 line per command

3.3. <name>:[[:][![!]]]<command>[|[cmd w/vars]]
3.3.0. REVISION, 2002-10-28: <name>:[[:][![!]]]<command>[<|>[alt command]]
3.3.1. <name> = user defined
3.3.1.1. Restrictions, 2002-10-28: lower case, no whitespace, max=32
3.3.2. : = plain, :: = emote, ! = shell, !! = local-only
3.3.3. [|[command]] = alt form of <command>,
3.3.3.1. using same <name>, with substitution variables
3.3.3.2. REVISION, 2002-10-28: vars may appear in <command> on either side
3.3.3.3. of optional <|>

3.4. substitution variables:
3.4.1. [$*][%s] = complete string typed with <name>
3.4.2. [$0]-[$9] = treat str typed with <name> as space-separated list of sub vars in <command>
3.4.3. \n and \t = newline and tab, respectively
3.4.4. [\$][\%s][\\n][\\t] = esc literals in <command>
3.4.5. empty vars should not echo at all

3.5. # = comment

3.6. Examples

3.6.1. format (legend)
3.6.1.1. first line is what is in users' commands file
3.6.1.2. > indicates what is typed in chat
3.6.1.3. "" indicates output

3.6.2. plain chat

3.6.2.1. docs:see http://www.tldp.org | $0, see http://www.tldp.org
3.6.2.2. >/docs 
3.6.2.3. "see http://www.tldp.org"
3.6.2.4. >/docs chat_joker
3.6.2.5. "chat_joker, see http://www.tldp.org"

3.6.3. emote

3.6.3.1. ducks::chases carnivorous ducks | chases $1 with carnivorous ducks
3.6.3.2. >/ducks
3.6.3.3. "(chat name here) chases carnivorous ducks"
3.6.3.4. >/ducks chat_joker
3.6.3.5. "(chat name here) chases chat_joker with carnivorous ducks"

3.6.4. shell

3.6.4.1. issue:!cat /etc/issue | !$*
3.6.4.2. >/issue
3.6.4.3. "(output from cat /etc/issue)"
3.6.4.4. >/issue cat /etc/issue; cat /etc/issue.net
3.6.4.5. "(output of command, if user screws up, tough)"

3.6.5. local-only

3.6.5.1. issue:!!cat /etc/issue | !!$*
3.6.5.2. >/issue
3.6.5.3. same as shell except it only shows on user's screen
3.6.5.4. >/issue cat /etc/issue; cat /etc/issue.net
3.6.5.5. same as shell except it only shows on user's screen
3.6.5.6. Note there is no reason why an alternate shell command couldn't be
3.6.5.7. a local-only version of the one on the left side of |

3.7 2002-10-26

3.7.1. by "buy_more_pepsi"

3.7.2. common location for client files = ~/.yahoorc/

3.7.2.1. each client to create and use a subdirectory of ~/.yahoorc/
3.7.2.2. example: ~/.yahoorc/gyach/, ~/.yahoorc/curphoo/, ~/.yahoorc/curfloo/
3.7.2.3. common files, such as ignore and commands, go in ~/.yahoorc/

3.7.3. transistion

3.7.3.1. clients read either old or new file formats and locations
3.7.3.2. clients save in new format and location

3.7.4. command chaining 2002-10-28

3.7.4.1. use <;> to chain commands within <command> or <alt command>
3.7.4.2. example (all on one line): 
3.7.4.2.1. foo:this is /foo <;> !echo "this is /foo" ; /foo <|>
3.7.4.2.2. Hey $* pay attention... this is /foo <;> !echo "this is /foo" ; /foo