Text Formatting:Syntax
From Anope Wiki
Contents |
Syntax Formatting
Basic Rules
This rules are here so a user doesn't have to learn a new way of syntax formatting for every single module. The rules are quite basic, especially if you can already code (which you all can, or you're just reading this because you're bored or so). Note that it's best to put bold codes around the syntax to use. Also keep the syntax short so it can stay on one line and won't confuse people etc. If a user needs to fill in a value, put down a basic description of the value which should be entered, and underline it. For example:
Syntax: NICK newnick
This would describe the use of the NICK command. It's obvious the only paramenter, which is also required, is the new nick.
Optional paramenters
Next we're talking about optional paramenters. If you have optional paramenters, for example you want an oper to be able to use our NICK command to change the nick of any other user too, you put them between square brackets ([]). This would give us the following syntax:
Syntax: NICK [nick] newnick
As you can see, the optional paramenter doesn't have to be at the end. It can basically be anywhere, as long as you can figure out what paramenter is what in your code. Consider the next two syntaxes:
Syntax: NICK [nick] [newnick] Syntax: NICK [nick] TO [newnick]
The first one isn't clear. You only pass one paramenter, is it nick or newnick?. If we add in a small required word (like TO in this example) we know what's passed. You can also nest the 'optional tags', so this syntax would require newnick if nick is specified:
Syntax: NICK [[nick] newnick]
A or B
We can also present a number of choises to the user (s)he can choose from. This is done by putting a | between the choices and putting all choices between square brackets when optional, and between curly brackets ({}) when required. If, for example, we want the user to specify whether he wants to change his own or some other's nick, we put it down like this:
Syntax: NICK {MY|OTHER} [nick] newnick
Last Word
Ofcourse you can combine this tactics to create wonderful and weird syntaxes:
Syntax: HIDE {USER|CHAN} [name]
Syntax: BEEP nick [[title] text]
Syntax: SET option {YES|NO} [moreinfo]
And many more, only limited by your imagination ;) Let it play around a bit, and don't hestitate to ask me questions. Here we end this tutorial, hoping you've learned something about adding help to your modules. If you didn't there's something wrong anyways ;)
