[asterisk-dev] Conditional sections in XML

[Tony Mountifield]

Matt, thanks for the reply and the ideas. I'll give them some thought.

Another idea I had was to pass the .c file through cpp when extracting
the XML. I haven't yet studied what happens in the Makefile to see
whether this is a possibility.

Cheers
Tony

In article <CAN2PU+7VOoM790m69ouHNG6FOY057U00gC+fUAVxR15DAvvSYQ at mail.gmail.com>,
Matthew Jordan <mjordan at digium.com> wrote:
> 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
-- 
Tony Mountifield
Work: tony at softins.co.uk - http://www.softins.co.uk
Play: tony at mountifield.org - http://tony.mountifield.org