<p>George Joseph has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.asterisk.org/c/asterisk/+/18789">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">Makefile: Allow XML documentation to exist outside source files<br><br>Moved the xmldoc build logic from the top-level Makefile into<br>its own script "make_xml_documentation" in the build_tools<br>directory.<br><br>Created a new utility script "get_sourceable_makeopts", also in<br>the build_tools directory, that dumps the top-level "makeopts"<br>file in a format that can be "sourced" from shell sscripts.<br>This allows scripts to easily get the values of common make<br>build variables such as the location of the GREP, SED, AWK, etc.<br>utilities as well as the AST* and library *_LIB and *_INCLUDE<br>variables.<br><br>Besides moving logic out of the Makefile, some optimizations<br>were done like removing "third-party" from the list of<br>subdirectories to be searched for documentation and changing some<br>assignments from "=" to ":=" so they're only evaluated once.<br>The speed increase is noticeable.<br><br>The makeopts.in file was updated to include the paths to<br>REALPATH and DIRNAME.  The ./conifgure script was setting them<br>but makeopts.in wasn't including them.<br><br>So...<br><br>With this change, you can now place documentation in any"c"<br>source file AND you can now place it in a separate XML file<br>altogether.  The following are examples of valid locations:<br><br>res/res_pjsip.c<br>    Using the existing /*** DOCUMENTATION ***/ fragment.<br><br>res/res_pjsip/pjsip_configuration.c<br>    Using the existing /*** DOCUMENTATION ***/ fragment.<br><br>res/res_pjsip/pjsip_doc.xml<br>    A fully-formed XML file.  The "configInfo", "manager",<br>    "managerEvent", etc. elements that would be in the "c"<br>    file DOCUMENTATION fragment should be wrapped in proper<br>    XML.  Example for "somemodule.xml":<br><br>    <?xml version="1.0" encoding="UTF-8"?><br>    <!DOCTYPE docs SYSTEM "appdocsxml.dtd"><br>    <docs><br>        <configInfo><br>        ...<br>        </configInfo><br>    </docs><br><br>It's the "appdocsxml.dtd" that tells make_xml_documentation<br>that this is a documentation XML file and not some other XML file.<br>It also allows many XML-capable editors to do formatting and<br>validation.<br><br>Other than the ".xml" suffix, the name of the file is not<br>significant.<br><br>As a start... This change also moves the documentation that was<br>in res_pjsip.c to 2 new XML files in res/res_pjsip:<br>pjsip_config.xml and pjsip_manager.xml.  This cut the number of<br>lines in res_pjsip.c in half. :)<br><br>Change-Id: I486c16c0b5a44d7a8870008e10c941fb19b71ade<br>---<br>M Makefile<br>A build_tools/get_sourceable_makeopts<br>A build_tools/make_xml_documentation<br>M makeopts.in<br>M res/res_pjsip.c<br>A res/res_pjsip/pjsip_config.xml<br>A res/res_pjsip/pjsip_manager.xml<br>7 files changed, 3,560 insertions(+), 3,301 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/89/18789/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span></span><br></pre><p>To view, visit <a href="https://gerrit.asterisk.org/c/asterisk/+/18789">change 18789</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.asterisk.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.asterisk.org/c/asterisk/+/18789"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: asterisk </div>
<div style="display:none"> Gerrit-Branch: certified/18.9 </div>
<div style="display:none"> Gerrit-Change-Id: I486c16c0b5a44d7a8870008e10c941fb19b71ade </div>
<div style="display:none"> Gerrit-Change-Number: 18789 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: George Joseph <gjoseph@digium.com> </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>