<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/2029/1/7/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/Documentation+Improvements">Documentation Improvements</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~russell">Russell Bryant</a>
</h4>
<br/>
<h4>Changes (4)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >h3. In Progress <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">* Migrate documentation from the doc/ directory to this wiki. <br>** This will be done manually. Once complete, most (if not all) content from the doc directory will be removed. <br>* Create a tool that syncs the built-in XML based documentation for applications, functions, etc. to this wiki <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">* Create a script that can export the wiki into PDF and plain text for inclusion with release tarballs. <br>** The [Confluence API|http://confluence.atlassian.com/display/CONFDEV/Remote+API+Specification] includes an exportSpace() API call that should do the trick. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h3. Done <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">_This space intentionally left blank._ <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">* Migrate documentation from the doc/ directory to this wiki. <br>* Create a tool that syncs the built-in XML based documentation for applications, functions, etc. to this wiki <br></td></tr>
<tr><td class="diff-unchanged" > <br>h1. XML to Wiki <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h1><a name="DocumentationImprovements-ImprovementsOverview"></a>Improvements Overview</h1>
<h3><a name="DocumentationImprovements-ToDo"></a>To-Do</h3>
<ul>
<li>Create a place for AMI event documentation, likely in the Asterisk XML docs. Make them available via the Asterisk CLI and Wiki.</li>
<li>Create a simplified set of sample configuration files and PBX starter configuration files</li>
</ul>
<h3><a name="DocumentationImprovements-InProgress"></a>In Progress</h3>
<ul>
<li>Create a script that can export the wiki into PDF and plain text for inclusion with release tarballs.
<ul>
<li>The <a href="http://confluence.atlassian.com/display/CONFDEV/Remote+API+Specification" class="external-link" rel="nofollow">Confluence API</a> includes an exportSpace() API call that should do the trick.</li>
</ul>
</li>
</ul>
<h3><a name="DocumentationImprovements-Done"></a>Done</h3>
<ul>
<li>Migrate documentation from the doc/ directory to this wiki.</li>
<li>Create a tool that syncs the built-in XML based documentation for applications, functions, etc. to this wiki</li>
</ul>
<h1><a name="DocumentationImprovements-XMLtoWiki"></a>XML to Wiki</h1>
<p>To get the reference information for applications, functions, etc. into the wiki, we need a tool that will keep what is in the source tree in sync with the wiki. The XML documentation in Asterisk should be the master, meaning that the content should never be modified in the wiki directly. The documentation should be imported into the following pages, which are all child pages of <a href="/wiki/display/AST/Asterisk+Command+Reference" title="Asterisk Command Reference">Asterisk Command Reference</a>:</p>
<div class="plugin_pagetree">
<ul class="plugin_pagetree_children_list plugin_pagetree_children_list_noleftspace">
<div class="plugin_pagetree_children">
</div>
</ul>
<fieldset class="hidden">
<input type="hidden" name="treeId" value="">
<input type="hidden" name="treeRequestId" value="/wiki/plugins/pagetree/naturalchildren.action?decorator=none&excerpt=false&sort=position&reverse=false&disableLinks=false">
<input type="hidden" name="treePageId" value="5242888">
<input type="hidden" name="noRoot" value="false">
<input type="hidden" name="rootPageId" value="5242900">
<input type="hidden" name="rootPage" value="">
<input type="hidden" name="startDepth" value="0">
<input type="hidden" name="spaceKey" value="AST" >
<input type="hidden" name="i18n-pagetree.loading" value="Loading...">
<input type="hidden" name="i18n-pagetree.error.permission" value="Unable to load page tree. It seems that you do not have permission to view the root page.">
<input type="hidden" name="i18n-pagetree.eeror.general" value="There was a problem retrieving the page tree. Please check the server log file for more information.">
<input type="hidden" name="loginUrl" value="/wiki/login.action?os_destination=%2Fpages%2Fdoeditpage.action%3FpageId%3D5242888">
<fieldset class="hidden">
<input type="hidden" name="ancestorId" value="4260122">
<input type="hidden" name="ancestorId" value="4259934">
<input type="hidden" name="ancestorId" value="3702828">
<input type="hidden" name="ancestorId" value="4259930">
</fieldset>
</fieldset>
</div>
<p>For example, the Dial() application should get its own page that is a child of <a href="/wiki/display/AST/Dialplan+Applications" title="Dialplan Applications">Dialplan Applications</a>.</p>
<h5><a name="DocumentationImprovements-Development"></a>Development</h5>
<p>The development of this tool should be done against a development instance of Confluence. An evaluation license can be used for that purpose. The APIs for Confluence are documented <a href="http://confluence.atlassian.com/display/CONFDEV/Remote+API+Specification" class="external-link" rel="nofollow">here</a>. Confluence has a set of REST APIs that are the newest development interface and will eventually be the preferred interface for development. However, the REST APIs do not yet support creating and updating pages. It is a read-only API. This tool will need to use the Confluence remote API, instead.</p>
<p>The programming language and supporting libraries are left as an option to the implementor.</p>
<h5><a name="DocumentationImprovements-Usage"></a>Usage</h5>
<p>The "astxmltowiki" tool should take the following arguments:</p>
<ul>
<li>path/to/core-en_US.xml
<ul>
<li>Asterisk XML documentation file</li>
</ul>
</li>
</ul>
<p>The tool should also take the following options:</p>
<ul>
<li><em>username</em> / <em>password</em>
<ul>
<li>for confluence authentication</li>
<li>if not specified, request it interactively at the command line</li>
</ul>
</li>
<li><em>server</em>
<ul>
<li>for the confluence URL</li>
<li>default to <a href="https://myth.asterisk.org" class="external-link" rel="nofollow">https://myth.asterisk.org</a></li>
</ul>
</li>
</ul>
<h5><a name="DocumentationImprovements-Highleveloperation"></a>High level operation</h5>
<p>This is the general operation of the tool, expressed in psuedo code.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>for each application/function/AGI command/AMI action {
if page does not exist {
create page
}
translate XML documentation into Confluence wiki syntax
update page with new content
}
</pre>
</div></div>
<h5><a name="DocumentationImprovements-WikiSyntax"></a>Wiki Syntax</h5>
<p>Use the following pages for development of the wiki syntax template to use for each command reference type. While there is already a first pass on the wiki templates to be used on these pages, feel free to tweak it further.</p>
<ul>
<li><a href="/wiki/display/AST/Dialplan+Application+Template+Page" title="Dialplan Application Template Page">Dialplan Application Template Page</a></li>
<li><a href="/wiki/display/AST/Dialplan+Function+Template+Page" title="Dialplan Function Template Page">Dialplan Function Template Page</a></li>
<li><a href="/wiki/display/AST/AMI+Action+Template+Page" title="AMI Action Template Page">AMI Action Template Page</a></li>
<li><a href="/wiki/display/AST/AGI+Command+Template+Page" title="AGI Command Template Page">AGI Command Template Page</a></li>
</ul>
<h5><a name="DocumentationImprovements-OtherFormattingNotes"></a>Other Formatting Notes</h5>
<p>In addition to the structural elements of the XML documentation which can be mapped into the templates, there are some other formatting elements used in the Asterisk XML documentation that need to be mapped to wiki syntax.</p>
<ul>
<li><para>
<ul>
<li>A paragraph.</li>
</ul>
</li>
<li><literal>
<ul>
<li>Literal (fixed-width). Wrap in <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[{{curly braces}}]]></script>
</div></div> and it will <tt>look like this</tt>.</li>
</ul>
</li>
<li><emphasis>
<ul>
<li>Make these italics by wrapping the next with underscores. It will <em>look like this</em>.</li>
</ul>
</li>
<li><replaceable>
<ul>
<li>...</li>
</ul>
</li>
<li><directory>
<ul>
<li>Do nothing.</li>
</ul>
</li>
<li><astcli>
<ul>
<li>...</li>
</ul>
</li>
</ul>
<h5><a name="DocumentationImprovements-AsteriskVersioning"></a>Asterisk Versioning</h5>
<p>Every page should include a note that identifies which version of Asterisk the documentation was imported from. There should <em>not</em> be more than one instance of a page for a particular application by version. Instead, we need to improve the documentation XML format to include the ability to tag elements with a version when they were first introduced. Once the mechanism for doing this has been decided, the base version for all documentation in this wiki will need to be Asterisk 1.8. From there, we can start tagging new additions with a version number of 1.10.</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;">
<a href="https://wiki.asterisk.org/wiki/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/Documentation+Improvements">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=5242888&revisedVersion=19&originalVersion=18">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Documentation+Improvements?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>