changeset 184:0ff84eeea2b0

Docs: move procedures to the wiki
author David Demelier <markand@malikania.fr>
date Wed, 01 Jun 2016 12:48:04 +0200
parents 166f589e30e5
children b5758826f5fc
files doc/CMakeLists.txt doc/procs/00.new-release.md doc/procs/00.tests.md doc/procs/10.new-plugin.md doc/procs/20.options.md doc/procs/30.options.md doc/procs/60.new-command.md doc/procs/README.md
diffstat 8 files changed, 0 insertions(+), 745 deletions(-) [+]
line wrap: on
line diff
--- a/doc/CMakeLists.txt	Wed Jun 01 12:37:00 2016 +0200
+++ b/doc/CMakeLists.txt	Wed Jun 01 12:48:04 2016 +0200
@@ -22,13 +22,6 @@
 add_custom_target(
 	all-docs ALL
 	COMMENT "Building irccd documentation"
-	SOURCES
-		${doc_SOURCE_DIR}/procs/README.md
-		${doc_SOURCE_DIR}/procs/00.tests.md
-		${doc_SOURCE_DIR}/procs/00.new-release.md
-		${doc_SOURCE_DIR}/procs/20.options.md
-		${doc_SOURCE_DIR}/procs/30.options.md
-		${doc_SOURCE_DIR}/procs/60.new-command.md
 )
 
 set_target_properties(
--- a/doc/procs/00.new-release.md	Wed Jun 01 12:37:00 2016 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,54 +0,0 @@
-Releasing new version
-=====================
-
-This procedure must be done before releasing a new irccd version.
-
-1. Switch to the appropriate release branch.
-
-Example, if about to release 2.0.5:
-
-    $ hg update release-2.0
-
-2. Change the version and date in the cmake/IrccdVersion.cmake file.
-
-Example:
-
-    set(IRCCD_VERSION_MAJOR "2")
-    set(IRCCD_VERSION_MINOR "0")
-    set(IRCCD_VERSION_PATCH "5")
-
-    set(IRCCD_RELEASE_DATE_YEAR 2016)
-    set(IRCCD_RELEASE_DATE_MONTH 12)
-    set(IRCCD_RELEASE_DATE_DAY 31)
-
-3. Update or verify the CHANGES.md file
-
-4. Update the README.md
-
-You must remove the "This is a development version" notice from the file and change the version.
-
-5. Change the version in the irccd guide.
-
-6. Create a new tag x.y.z
-
-    $ hg tag 2.0.5
-
-7. Create the signature of the tag
-
-    $ hg sign
-
-8. Push the changes and merge by top-porting it
-
-Example:
-
-    $ hg update stable-2
-    $ hg merge release-2.0
-    $ hg ci -m "Merge from release-2.0"
-    $ hg up @
-    $ hg merge release-2.0
-    $ hg ci -m "Merge from stable-2"
-    $ hg push
-
-9. Create the package
-
-    $ make release
--- a/doc/procs/00.tests.md	Wed Jun 01 12:37:00 2016 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,74 +0,0 @@
-Irccd test plan
-===============
-
-Use this file to test irccd in several ways where it can not be unit tested.
-
-Template:
-
-Action:
-Expected:
-Status:
-Remarks:
-
-Status:
-
-  - Ok,
-  - Incorrect.
-
-## Irccd command line options
-
-Action: -f must run in foreground and override configuration file (*)
-Expected: irccd does not go to background
-Status: Ok
-Remarks:
-
-Action: -v must enable more messages
-Expected: more messages appear
-Status: Ok
-Remarks:
-
-Action: -c must use the specified configuration file
-Expected: irccd loads the specified file
-Status: Ok
-Remarks:
-
-(*) has no effect on Windows.
-
-## Irccdctl command line options
-
-Action: specifying -t must connect to the command line arguments, not the configuration
-Expected: even if the configuration has a `[connect]`, irccdctl must connect to the command line arguments
-Status: Ok
-Remarks:
-
-Action: -v must enable more messages
-Expected: more messages appear
-Status: Ok
-Remarks:
-
-## Irccdctl aliases
-
-Action: Given `x = ""`, the alias must not be loaded
-Expected: error
-Status: Ok
-Remarks:
-
-Action: Given `x = "plugin-load %0"` typing `irccdctl x` should throw an error because argument is missing
-Expected: error
-Status: Ok
-Remarks:
-
-Action: Given `x = ( "plugin-unload %0", "plugin-load %0" )` typing `irccdctl x ask` should unload and load ask
-Expected: ask is unloaded and then loaded
-Status: Ok
-Remarks:
-
-Action: Given `x = "server-connect -n bertrand %1 %0"`, typing `irccdctl x host id` should execute `irccdctl server-connect -n bertrand id host`
-Expected: the `id` and `host` paremeters are inverted thanks to %1 and %0
-Status: Ok
-Remarks:
-
-Action: Given `x = "server-connect %0 %0"`, typing `irccdctl x localhost 7000` should execute `irccdctl server-connect localhost localhost 7000`
-Expected: irccd tries to connect to localhost (id localhost too) on port 7000
-Status: Ok
-Remarks:
--- a/doc/procs/10.new-plugin.md	Wed Jun 01 12:37:00 2016 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,45 +0,0 @@
-Writing new plugin
-==================
-
-This procedure let you bundle a new plugin within irccd.
-
-1. Create the plugin directory in plugins/plugin-name.
-
-2. Write the plugin JavaScript file
-
-The plugin file must be named exactly the same as the directory name plus the .js suffix.
-
-Example:
-
-- plugins/myplugin/myplugin.js
-
-3. Fill the plugin information.
-
-The plugin must have the **info** table set, see other plugins for example.
-
-````javascript
-info = {
-	author: "Firstname Lastname <email>",
-	license: "Your license",
-	summary: "Short summary without period",
-	version: "The version"
-};
-````
-
-If the plugin is intended to be bundled with irccd, license must be set to **ISC** and the version to **@IRCCD_VERSION@**.
-
-3. Write the documentation file
-
-Just like the JavaScript file, it must be named the same plus the .md suffix.
-
-Example:
-
-- plugins/myplugin/myplugin.md
-
-Document your plugin using markdown, see other plugins and try to be as close as possible.
-
-4. Update cmake/IrccdVersion.cmake
-
-Add the canonical plugin name to the **IRCCD_PLUGINS** variable, that's it.
-
-Note: please keep the variable ordered.
\ No newline at end of file
--- a/doc/procs/20.options.md	Wed Jun 01 12:37:00 2016 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,89 +0,0 @@
-Irccd configuration file (irccd.conf)
-=====================================
-
-This file describes how to add new options in the irccd configuration file.
-
-# Current options
-
-## general
-
-  - **uid**: (string or number) the user id to use (Optional, default: none),
-  - **gid**: (string or number) the group id to use (Optional, default: none),
-  - **foreground**: (bool) set to true to not daemonize (Optional, default: false),
-  - **pidfile**: (string) path to a file where to store the irccd pid (Optional, default: none).
-
-## format
-
-  - **debug**: (string) template to use to format debug messages (Optional, default: none),
-  - **info**: (string) template to use to format information messages (Optional, default: none),
-  - **warning**: (string) template to use to format warnings (Optional, default: none).
-
-## logs
-
-  - **verbose**: (bool) be verbose (Optional, default: false),
-  - **type**: (string) which kind of logging, console, file or syslog (Optional, default: console).
-
-The options for **file** type:
-
-  - **path-logs**: (string) path to the normal messages,
-  - **path-errors**: (string) path to the error messages.
-
-## identity
-
-  - **name**: (id) the identity unique id,
-  - **nickname**: (string) the nickname (Optional, default: irccd),
-  - **realname**: (string) the realname (Optional, default: IRC Client daemon),
-  - **username**: (string) the username name (Optional, default: irccd),
-  - **ctcp-version**: (string) what version to respond to CTCP VERSION (Optional, default: IRC Client Daemon),
-  - **ctcp-autoreply**: (bool) enable auto CTCP VERSION reply, (Optional, default: true).
-
-## server
-
-  - **name**: (id) the unique id,
-  - **host**: (string) the server address,
-  - **port**: (int) the server port (Optional, default: 6667),
-  - **identity**: (string) an identity to use (Optional, default: irccd's default),
-  - **password**: (string) an optional password (Optional, default: none),
-  - **auto-rejoin**: (bool) auto rejoin a channel after being kicked (Optional, default: false),
-  - **join-invite**: (bool) join channels upon invitation (Optional, default: false),
-  - **channels**: (list) list of channels to auto join, (Optional, default: empty),
-  - **command-char**: (string) the prefix for invoking special commands (Optional, default: !),
-  - **ssl**: (bool) enable or disable SSL (Optional, default: false),
-  - **ssl-verify**: (bool) verify the SSL certificates (Optional, default: true),
-  - **reconnect**: (bool) enable reconnection after failure (Optional, default: true),
-  - **reconnect-tries**: (int) number of tries before giving up. A value of 0 means indefinitely (Optional, default: 0),
-  - **reconnect-timeout**: (int) number of seconds to wait before retrying (Optional, default: 30).
-
-## plugins
-
-No options.
-
-## transport
-
-  - **type**: (string) type of listener "ip" or "unix"
-
-The options for **ip** type:
-
-  - **port**: (int) port number,
-  - **address**: (string) address to bind or "*" for any (Optional, default: *),
-  - **family**: (list) ipv6, ipv4. Both are accepted (Optional, default: ipv4).
-
-The options for **unix** type:
-
-  - **path**: (string) the file path to the socket.
-
-## rule
-
-  - **servers**, (list) a list of servers that will match the rule (Optional, default: empty),
-  - **channels**, (list) a list of channel (Optional, default: empty),
-  - **plugins**, (list) which plugins (Optional, default: empty),
-  - **events**, (list) which events (e.g onCommand, onMessage, ...) (Optional, default: empty),
-  - **action**, (string) set to **accept** or **drop**.
-
-# Add a new option
-
-  1. Update this file,
-  2. Open irccd/config.cpp and load your option into the appropriate function,
-  3. Update doc/html/guide/04-irccd/01-config.md,
-  4. Update doc/examples/irccd.conf,
-  5. Update doc/man/irccd.conf.5.in.
--- a/doc/procs/30.options.md	Wed Jun 01 12:37:00 2016 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,24 +0,0 @@
-Irccdctl configuration file (irccdctl.conf)
-===========================================
-
-This file describes how to add new options in the irccdctl configuration file.
-
-# Current options
-
-## general
-
-  - **verbose**: (bool) enable verbose message (Optional, default: false).
-
-## connect
-
-  - **type**: (string) type of listener "ip" or "unix".
-
-The options for **internet** type:
-
-  - **host**: (string) host to connect,
-  - **port**: (int) port number,
-  - **family**: (string) internet family: ipv6 or ipv4 (Optional, default: ipv4).
-
-The options for **unix** type:
-
-  - **path**: (string) the file path to the socket.
--- a/doc/procs/60.new-command.md	Wed Jun 01 12:37:00 2016 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,438 +0,0 @@
-All irccdctl commands
-=====================
-
-This file groups all irccdctl commands, help messages so that it's easier to maintain the manual pages, HTML
-documentation and command line help in case of change.
-
-This file can also been reviewed in case of spoken errors.
-
-Please update this file before updating any source code.
-
-All values that are marked optional MUST be silently discarded in the commands if they are not valid.
-
-# JavaScript API
-
-Whenever possible, if a function in the irccd's API is available, the arguments MUST be defined in the same order. For
-example, the method `Server.cnotice` should have **channel**, **message** arguments.
-
-# Updating the code
-
-Adding a new transport command is quite straightforward.
-
-You need to create two classes: one as irccdctl request and one as irccd command. Both files must be named
-`command-<name>.(h|cpp)`.
-
-# Irccd command
-
-To implement the command irccd's side, you must write a class like this:
-
-**command-mycommand.h**
-
-Inherit from `TransportCommand` and override the `exec` function.
-
-    #include "transport-command.hpp"
-
-    namespace irccd {
-
-    namespace command {
-
-    class MyCommand : public TransportCommand {
-    public:
-	void exec(Irccd &irccd, TransportClient &tc, const json::Value &object) const override
-	{
-		// Do what you want here
-	}
-    };
-
-    } // !command
-
-    } // !irccd
-
-Then, in the `irccd` main.cpp file, register the new class using `Irccd::addTransportCommand` function.
-
-# Irccdctl command
-
-In irccdctl, you must implement two functions. One to show the usage when calling `irccdctl help` and the one to
-execute.
-
-Inherit from `Command` and override both `usage` and `exec` functions.
-
-    #include "command.hpp"
-
-    namespace irccd {
-
-    namespace command {
-
-    class MyCommand : public Command {
-    public:
-	void usage(Irccdctl &irccdctl) const
-	{
-		// print the message using log::warning().
-	}
-
-	void exec(Irccdctl &irccdctl, const std::vector<std::string> &args) const
-	{
-		// send the command using irccdctl.send().
-	}
-    };
-
-    } // !command
-
-    } // !irccd
-
-And like irccd, you must register it in the `irccdctl` main.cpp file.
-
-# Updating the documentation
-
-  1. You must update doc/html/guide/05-irccdctl/02-commands.md to show the command usage,
-  2. You must update doc/man/irccdctl.1.in to show the command usage too,
-  3. You must update the appropriate command class in both irccd/irccdctl.
-
-**Note:** you must use the text from this file and propagate it to the files described above.
-
-# Server commands
-
-## server-cmode
-
-Change the mode of the specified channel.
-
-### Usage
-
-`irccdctl server-cmode server channel mode`
-
-### Arguments
-
-  - **command**: (string) "server-cmode",
-  - **server**: (string) the server unique id,
-  - **channel**: (string) the channel,
-  - **mode**: (string) the argument.
-
-### Responses
-
-  - An error if the server does not exist.
-
-## server-cnotice
-
-Send a message notice on a channel.
-
-### Usage
-
-`server-cnotice server channel message`
-
-### Arguments
-
-  - **command**: (string) "server-cnotice",
-  - **server**: (string) the server unique id,
-  - **channel**: (string) the channel name,
-  - **message**: (string) the notice message.
-
-## server-connect
-
-Connect to a server.
-
-### Usage
-
-`server-connect [options] id host [port]`
-
-**Options:**
-
-  - **-c, --command**: specify the command char,
-  - **-n, --nickname**: specify a nickname,
-  - **-r, --realname**: specify a real name,
-  - **-u, --username**: specify a user name,
-  - **-S, --ssl-verify**: verify SSL,
-  - **-s, --ssl**: connect using SSL,
-
-### Arguments
-
-  - **command**: (string) "server-connect",
-  - **name**: (string) the server unique id,
-  - **host**: (string) the host address,
-  - **port**: (int) the port number (Optional, default: 6667),
-  - **ssl**: (bool) use SSL (Optional, default: false),
-  - **sslVerify**: (bool) verify SSL (Optional, default: false),
-  - **nickname**: (string) the nickname to use (Optional, default: irccd),
-  - **username**: (string) the user name to use (Optional, default: irccd),
-  - **realname**: (string) the real name to use (Optional, default: IRC Client Daemon),
-  - **ctcpVersion**: (string) the CTCP Version to answer (Optional, default: the irccd's version),
-  - **commandChar**: (string) the command character to use to invoke commands (Optional, default: !),
-  - **reconnectTries**: (int) the number of reconnection to try (Optional, default: -1),
-  - **reconnectTimeout**: (int) the number of seconds to wait before retrying to connect (Optional, default: 30).
-
-### Responses
-
-  - An error if a server with the same name exists.
-
-## server-disconnect
-
-Disconnect from a server.
-
-If server is not specified, irccd disconnects all servers.
-
-### Usage
-
-`server-disconnect [name]`
-
-### Arguments
-
-  - **command**: (string) "server-disconnect",
-  - **server**: (string) the server unique id (Optional, default: none).
-
-### Responses
-
-  - An error if the server does not exist.
-
-## server-info
-
-Get server information.
-
-### Usage
-
-`server-info name`
-
-### Arguments
-
-  - **command**: (string) "server-info",
-  - **server**: (string) the server unique id.
-
-### Responses
-
-  - The following properties on success:
-    - **name**: (string) the server unique id,
-    - **host**: (string) the server hostname,
-    - **port**: (int) the port,
-    - **ipv6**: (bool) true if using IPv6,
-    - **ssl**: (bool) true if connection is using SSL,
-    - **sslVerify**: (bool) true if SSL was verified,
-    - **channels**: (string list) list of channels.
-    - **nickname**: (string) the current nickname in use,
-    - **username**: (string) the username in use,
-    - **realname**: (string) the realname in use.
-  - An error if the server does not exist.
-
-### Responses
-
-  - An error if the server does not exist.
-
-## server-invite
-
-Invite the specified target on the channel.
-
-### Usage
-
-`server-invite server target channel`
-
-### Arguments
-
-  - **command**: (string) "server-invite",
-  - **server**: (string) the server unique id,
-  - **target**: (string) the nickname to invite,
-  - **channel**: (string) the channel.
-
-## server-join
-
-Join the specified channel, the password is optional.
-
-### Usage
-
-`server-join server channel [password]`
-
-### Arguments
-
-  - **command**: (string) "server-join",
-  - **server**: (string) the server unique id,
-  - **channel**: (string) the channel to join,
-  - **password**: (string) the password (Optional, default: none).
-
-### Responses
-
-  - An error if the server does not exist.
-
-## server-kick
-
-Kick the specified target from the channel, the reason is optional.
-
-### Usage
-
-`server-kick server target channel [reason]`
-
-### Arguments
-
-  - **command**: (string) "server-kick",
-  - **server**: (string) the server unique id,
-  - **target**: (string) the target nickname,
-  - **channel**: (string) the channel,
-  - **reason**: (string) the reason (Optional, default: none).
-
-### Responses
-
-  - An error if the server does not exist.
-
-## server-list
-
-Get the list of all connected servers.
-
-### Usage
-
-`irccdctl server-list`
-
-### Arguments
-
-  - **command**: (string) "server-list".
-
-### Responses
-
-  - The following properties:
-    - **list**: (string list) the list of all server unique ids.
-
-## server-me
-
-Send an action emote.
-
-### Usage
-
-`irccdctl server-me server target message`
-
-### Arguments
-
-  - **command**: (string) "server-me",
-  - **server**: (string) the server unique id,
-  - **target**: (string) the target or channel,
-  - **message**: (string) the message.
-
-### Responses
-
-  - An error if the server does not exist.
-
-## server-message
-
-Send a message to the specified target or channel.
-
-### Usage
-
-`irccdctl server-message server target message`
-
-### Arguments
-
-  - **command**: (string) "server-message",
-  - **server**: (string) the server unique id,
-  - **target**: (string) the target or channel,
-  - **message**: (string) the message.
-
-### Responses
-
-  - An error if the server does not exist.
-
-## server-mode
-
-Set the irccd's user mode.
-
-### Usage
-
-`irccdctl server-mode server mode`
-
-### Arguments
-
-  - **command**: (string) "server-mode",
-  - **server**: (string) the server unique id,
-  - **mode**: (string) the mode.
-
-### Responses
-
-  - An error if server is specified and the server does not exist.
-
-## server-nick
-
-Change irccd's nickname.
-
-### Usage
-
-`irccdctl server-nick server nickname`
-
-### Arguments
-
-  - **command**: (string) "server-nick",
-  - **server**: (string) the server unique id,
-  - **nickname**: (string) the new nickname.
-
-### Responses
-
-  - An error if the server does not exist.
-
-## server-notice
-
-Send a private notice to the specified target.
-
-### Usage
-
-`irccdctl server-notice server target message`
-
-### Arguments
-
-  - **command**: (string) "server-notice",
-  - **server**: (string) the server unique id,
-  - **target**: (string) the target,
-  - **message**: (string) the notice message.
-
-### Responses
-
-  - An error if the server does not exist.
-
-## server-part
-
-Leave the specified channel, the reason is optional.
-
-Not all IRC servers support giving a reason to leave a channel, do not specify it if this is a concern.
-
-### Usage
-
-`irccdctl server-part server channel [reason]`
-
-### Arguments
-
-  - **command**: (string) "server-part",
-  - **server**: (string) the unique server id,
-  - **channel**: (string) the channel to leave,
-  - **reason**: (string) the reason (Optional, default: none).
-
-### Responses
-
-  - An error if the server does not exist.
-
-## server-reconnect
-
-Force reconnection of one or all servers.
-
-If server is not specified, all servers will try to reconnect.
-
-### Usage
-
-`irccdctl server-reconnect [server]`
-
-### Arguments
-
-  - **command**: (string) "server-reconnect",
-  - **server**: (string) the server unique id (Optional, default: none).
-
-### Responses
-
-  - An error if server is specified and the server does not exist.
-
-## server-topic
-
-Change the topic of the specified channel.
-
-### Usage
-
-`irccdctl server-topic server channel topic`
-
-### Arguments
-
-  - **command**: (string) "server-topic",
-  - **server**: (string) the unique server id,
-  - **channel**: (string) the channel,
-  - **topic**: (string) the new topic.
-
-### Responses
-
-  - An error if server is specified and the server does not exist.
--- a/doc/procs/README.md	Wed Jun 01 12:37:00 2016 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,14 +0,0 @@
-Irccd procedures
-================
-
-The files in this directory are small instructions to help irccd's development.
-
-Files are prefixed by a number which is a specific category:
-
-  - 0, release engineering
-  - 1, irccd's JavaScript plugins,
-  - 2, the irccd daemon,
-  - 3, the irccdctl utility,
-  - 4, the documentation process,
-  - 5, the build system within irccd,
-  - 6, miscellaneous.