[asterisk-dev] Conditional sections in XML

[Matthew Jordan]

On Thu, Jun 13, 2013 at 4:12 AM, Tony Mountifield <tony at softins.co.uk>wrote:

> I have been porting some of my custom modifications to app_meetme from 1.2
> to
> Asterisk 11 (yes, I know about ConfBridge - that's for later
> investigation).
>
> I have some of my modifications conditionally included using #ifdef.
>
> In 1.2, I could use #ifdef conditions to control the contents of the
> application help in static const char *descrip, like this:
>
> static const char *descrip =
> "  MeetMe([confno][,[options][,pin]]): Enters the user into a specified
> MeetMe conference.\n"
> .......
> "      'F' -- Pass DTMF through the conference.\n"
> #ifdef LOCKHOLD
> "      'h' -- Locked conference keeps user on hold instead of exiting.\n"
> #endif
> "      'i' -- announce user join/leave\n"
> .......
>
> However, in Asterisk 11, it appears that the application help is generated
> from the XML in the DOCUMENTATION comments. Putting #ifdef within that does
> not seem to have any effect. Everything gets included.
>
> So my question is, how can I make conditional variations in the application
> help that is compiled?
>
> I'm really hoping that the answer isn't just a blunt "you can't"...
>
>
>
Alas, that is the case.

In general, we've taken the approach to use compile time options as little
as possible. We try hard to relegate their usage only to cases that prevent
compilation issues when module dependencies aren't present. I'd speculate
that a patch that proposed an application parameter that was optionally
included at compile time would most likely not be accepted for inclusion in
mainline Asterisk. Hence, this idea is not something we built into the XML
documentation generation - we've never had a use case for it.

A few possible options:

The first would be to not have application options be determined at compile
time.

The second would be to modify the XML parser in xmldoc.c to pass over
elements if an attribute is present on the XML element. It would be an
additional step to 'include' the documentation if you choose to compile
Asterisk; however it would at least give you the ability to toggle on/off a
particular element.

Another option would be to have a script that updates the produced
doc-en_US.xml file with the documentation if someone has enabled the build
option. The script could read in the XML DOM, update the contents, and
re-write the file. Asterisk determines the documentation by reading this
file on startup, so you can manipulate it outside of the source and the
build process.

Matt

-- 
Matthew Jordan
Digium, Inc. | Engineering Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: http://digium.com & http://asterisk.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20130613/5f74dcf1/attachment.htm>