XEP-tool usage

The XEP-tool is the answer for developers who wonder how to maintain an actual list of supported XEPs. It's a fast and easy way to automatically produce documentation from raw, beam files. This is a quick guide on how to enjoy the usage of the XEP-tool.

Sign your module file first

The architecture of MongooseIM determines that almost every XEP or feature implementation resides in its own file. It is not strictly enforced but usually the file is named with a mod_ prefix. For example mod_privacy file implements XEP-0016: Privacy Lists.

Mandatory xep and version

In order to let the XEP-tool know about your module, we add a special attribute xep at the begining of the mod_privacy module:

-xep([{xep, 16}, {version, "1.6"}]).

Now we know that this module implements to XEP-0016: Privacy Lists with version 1.6.

It gives the tool enough information to generate a URL to the XEP homepage. There are also some variations of the xep attribute like:

You ought to remember to specify xep and version attributes every time. You can also put several xep attributes in one module. For example mod_mam_muc implements attributes of XEP-0313: Message Archive Management and also XEP-0045: Multi-User Chat.

Just list them one after another:

-xep([{xep, 45}, {version, "1.25"}]).
-xep([{xep, 313}, {version, "0.5.1"}]).

Specific URL

-xep([{xep, 16}, {version, "1.6"}, {url, "http://xmpp.org/extensions/xep-0016.html"}]).

Comment

-xep([{xep, 16}, {version, "1.6"}, {comment, "Example comment: Partial Implemented"}]).

And the XEP-tool will do the work!

Compile and run

You've just finished marking your modules. The only thing left is to make compile MongooseIM in order to generate the .beam files. To run the XEP tool, you must issue an additional subcommand. There are two choices:

  • markdown: to produce a markdown list of supported XEPs. This option also needs an output file as an argument.
  • list: to print out supported XEPs to the console.

For example, to run our XEP-tool with a markdown command, type:

make xeplist

Or do it manually:

$MONGOOSEIM_ROOT/tools/xep_tool/xep_tool.escript markdown <PATH_TO_EBIN> <OPTIONAL_OUTPUT_FILE>

In our case, from MongooseIM root directory:

./tools/xep_tool/xep_tool.escript markdown ebin list.md

The Markdown list with unique XEP names and URLs is saved to file list.md You can copy-paste the content of this file to your main README file.

Generated file example

XEP-0012: Last Activity XEP-0016: Privacy Lists XEP-0018: Invisible Presence XEP-0022: Message Events
XEP-0023: Message Expiration XEP-0030: Service Discovery XEP-0045: Multi-User Chat XEP-0049: Private XML Storage
XEP-0050: Ad-Hoc Commands XEP-0054: vcard-temp XEP-0055: Jabber Search XEP-0059: Result Set Management
XEP-0068: Field Standardization for Data Forms XEP-0077: In-Band Registration XEP-0078: Non-SASL Authentication XEP-0079: Advanced Message Processing
XEP-0082: XMPP Date and Time Profiles XEP-0083: Nested Roster Groups XEP-0085: Chat State Notifications XEP-0086: Error Condition Mappings
XEP-0093: Roster Item Exchange XEP-0114: Jabber Component Protocol XEP-0124: Bidirectional-streams Over Synchronous HTTP (BOSH) XEP-0126: Invisibility
XEP-0138: Stream Compression XEP-0157: Contact Addresses for XMPP Services XEP-0160: Best Practices for Handling Offline Messages XEP-0170: Recommended Order of Stream Feature Negotiation
XEP-0175: Best Practices for Use of SASL ANONYMOUS XEP-0198: Stream Management XEP-0199: XMPP Ping XEP-0202: Entity Time
XEP-0206: XMPP Over BOSH XEP-0212: XMPP Basic Server 2008 XEP-0237: Roster Versioning XEP-0279: Server IP Check
XEP-0280: Message Carbons XEP-0313: Message Archive Management