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 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"}]).

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

It gives the tool enough information to generate URL link 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 to XEP-0313: Message Archive Management and also to 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 XEP-tool will do the work!

Compile and run

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

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

For example, to run our XEP-tool with 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 apps/ejabberd/ebin list.md

The Markdown 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.

Example look of generated file

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