[prev in list] [next in list] [prev in thread] [next in thread]
List: asterisk-dev
Subject: Re: [asterisk-dev] [Code Review] 2811: New pjsip.conf.sample with 100% more pjsip
From: "Alec Davis" <reviewboard () asterisk ! org>
Date: 2013-08-30 23:50:29
Message-ID: 20130830235029.5875.41366 () hotblack ! digium ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviewboard.asterisk.org/r/2811/#review9584
-----------------------------------------------------------
I tend to disagree with the wiki being the main source of documentation, due to \
feature additions as we move forward new versions. The WIKI \
https://wiki.asterisk.org/wiki/display/AST/Configuring+res_pjsip is a generic \
resource to browse and get a general understanding.
The configs/pjsip.conf.sample should be the definitive reference for the version \
specific options.
- Alec Davis
On Aug. 30, 2013, 8:34 p.m., rnewton wrote:
>
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviewboard.asterisk.org/r/2811/
> -----------------------------------------------------------
>
> (Updated Aug. 30, 2013, 8:34 p.m.)
>
>
> Review request for Asterisk Developers.
>
>
> Bugs: ASTERISK-22145
> https://issues.asterisk.org/jira/browse/ASTERISK-22145
>
>
> Repository: Asterisk
>
>
> Description
> -------
>
> pjsip.conf!
>
> The file consists of two main bodies of text.
> 1. Manually written examples - fulfilling a variety of basic configuration \
> scenarios. A few of which are detailed on the ASTERISK-22145 issue. 2. A full \
> config option list - Output from a python script I wrote. It takes an xml config \
> dump from Asterisk and parses the pjsip.conf config options out into the format you \
> see in the file. (I may throw that script up here later after I improve it)
> Before the examples there is a blurb talking about where the official documentation \
> is and a brief security notice.
> Notes on the thought process behind what we have so far:
>
> * We want this to be easy to maintain
>
> In writing this I found it's easy to turn it into exhaustive documentation and make \
> it very redundant with our other documentation sources. For maintenance sake I \
> trimmed it all back to be about as simple as possible and tried to aim it towards a \
> "quick reference sheet", rather than "demonstrate every config option in action \
> document".
> The full option list is easy to update thanks to it being pulled from a script and \
> not hand edited.
> * The sample files should start moving towards "sample" files and not be exhaustive \
> documentation.
> * The sample file is not a tutorial.
>
> The examples provided in the file are geared towards someone who has already read \
> the basics on the wiki[1] or elsewhere. The examples also helpful to serve as \
> context for when you are looking at specific options through the cli config help or \
> referencing the full option list in the bottom of the file.
> * The examples in the sample file should be simple for a user to understand and \
> modify
> The examples don't have every option listed under them because it makes it a bit \
> confusing to look at. I've tried to arrange them realistically for basic \
> configurations so that it would be easy for you to copy paste options from the big \
> list at the bottom to the examples at the top.
> * Every example is not explained in detail
>
> I tried to pick out key points or options used in the examples, rather than just \
> explaining them line by line (since that would lead to a lot of redundancy)
> *** Don't provide feedback here for all the individual option names, synopsis, \
> descriptions etc. That is all pulled from the XML config documentation. If you see \
> errors in those areas please file a JIRA issue ***
> Please provide feedback on the example configurations and text that is not in the \
> big list of options at the bottom of the file. That is any obviously wrong \
> configuration (option that couldn't be used in a section), horrible spelling, \
> grammar or logic and flow problems. Suggestions for additional configuration \
> examples that are crucial or essential would be very helpful, especially if you can \
> write the example. Feedback is also very welcome on the formatting of the options \
> list at the bottom. :)
> Moving around all this text, I'm sure I missed quite a few things! Thanks in \
> advance for the help!
> [1]: https://wiki.asterisk.org/wiki/display/AST/Asterisk+12+Installation+and+Configuration
>
>
> Diffs
> -----
>
> /trunk/configs/pjsip.conf.sample 398037
>
> Diff: https://reviewboard.asterisk.org/r/2811/diff/
>
>
> Testing
> -------
>
> I tested pretty much all the configurations in this file or pulled them from other \
> peoples working configurations, there are probably a few option combinations and \
> configurations that I missed, but added in.
>
> Thanks,
>
> rnewton
>
>
[Attachment #5 (text/html)]
<html>
<body>
<div style="font-family: Verdana, Arial, Helvetica, Sans-Serif;">
<table bgcolor="#f9f3c9" width="100%" cellpadding="8" style="border: 1px #c9c399 \
solid;"> <tr>
<td>
This is an automatically generated e-mail. To reply, visit:
<a href="https://reviewboard.asterisk.org/r/2811/">https://reviewboard.asterisk.org/r/2811/</a>
</td>
</tr>
</table>
<br />
<pre style="white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: \
-pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">I tend to disagree with \
the wiki being the main source of documentation, due to feature additions as we move \
forward new versions. The WIKI \
https://wiki.asterisk.org/wiki/display/AST/Configuring+res_pjsip is a generic \
resource to browse and get a general understanding.
The configs/pjsip.conf.sample should be the definitive reference for the version \
specific options.</pre> <br />
<p>- Alec</p>
<br />
<p>On August 30th, 2013, 8:34 p.m. UTC, rnewton wrote:</p>
<table bgcolor="#fefadf" width="100%" cellspacing="0" cellpadding="8" \
style="background-image: \
url('https://reviewboard.asterisk.org/static/rb/images/review_request_box_top_bg.png'); \
background-position: left top; background-repeat: repeat-x; border: 1px black \
solid;"> <tr>
<td>
<div>Review request for Asterisk Developers.</div>
<div>By rnewton.</div>
<p style="color: grey;"><i>Updated Aug. 30, 2013, 8:34 p.m.</i></p>
<div style="margin-top: 1.5em;">
<b style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Bugs: </b>
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-22145">ASTERISK-22145</a>
</div>
<div style="margin-top: 1.5em;">
<b style="color: #575012; font-size: 10pt;">Repository: </b>
Asterisk
</div>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Description </h1>
<table width="100%" bgcolor="#ffffff" cellspacing="0" cellpadding="10" \
style="border: 1px solid #b8b5a0"> <tr>
<td>
<pre style="margin: 0; padding: 0; white-space: pre-wrap; white-space: \
-moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: \
break-word;">pjsip.conf!
The file consists of two main bodies of text.
1. Manually written examples - fulfilling a variety of basic configuration scenarios. \
A few of which are detailed on the ASTERISK-22145 issue. 2. A full config option list \
- Output from a python script I wrote. It takes an xml config dump from Asterisk and \
parses the pjsip.conf config options out into the format you see in the file. (I may \
throw that script up here later after I improve it)
Before the examples there is a blurb talking about where the official documentation \
is and a brief security notice.
Notes on the thought process behind what we have so far:
* We want this to be easy to maintain
In writing this I found it's easy to turn it into exhaustive documentation and \
make it very redundant with our other documentation sources. For maintenance sake I \
trimmed it all back to be about as simple as possible and tried to aim it towards a \
"quick reference sheet", rather than "demonstrate every config option \
in action document".
The full option list is easy to update thanks to it being pulled from a script and \
not hand edited.
* The sample files should start moving towards "sample" files and not be \
exhaustive documentation.
* The sample file is not a tutorial.
The examples provided in the file are geared towards someone who has already read the \
basics on the wiki[1] or elsewhere. The examples also helpful to serve as context for \
when you are looking at specific options through the cli config help or referencing \
the full option list in the bottom of the file.
* The examples in the sample file should be simple for a user to understand and \
modify
The examples don't have every option listed under them because it makes it a bit \
confusing to look at. I've tried to arrange them realistically for basic \
configurations so that it would be easy for you to copy paste options from the big \
list at the bottom to the examples at the top.
* Every example is not explained in detail
I tried to pick out key points or options used in the examples, rather than just \
explaining them line by line (since that would lead to a lot of redundancy)
*** Don't provide feedback here for all the individual option names, synopsis, \
descriptions etc. That is all pulled from the XML config documentation. If you see \
errors in those areas please file a JIRA issue ***
Please provide feedback on the example configurations and text that is not in the big \
list of options at the bottom of the file. That is any obviously wrong configuration \
(option that couldn't be used in a section), horrible spelling, grammar or logic \
and flow problems. Suggestions for additional configuration examples that are crucial \
or essential would be very helpful, especially if you can write the example. Feedback \
is also very welcome on the formatting of the options list at the bottom. :)
Moving around all this text, I'm sure I missed quite a few things! Thanks in \
advance for the help!
[1]: https://wiki.asterisk.org/wiki/display/AST/Asterisk+12+Installation+and+Configuration</pre>
</td>
</tr>
</table>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Testing </h1>
<table width="100%" bgcolor="#ffffff" cellspacing="0" cellpadding="10" style="border: \
1px solid #b8b5a0"> <tr>
<td>
<pre style="margin: 0; padding: 0; white-space: pre-wrap; white-space: \
-moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: \
break-word;">I tested pretty much all the configurations in this file or pulled them \
from other peoples working configurations, there are probably a few option \
combinations and configurations that I missed, but added in.</pre> </td>
</tr>
</table>
<h1 style="color: #575012; font-size: 10pt; margin-top: 1.5em;">Diffs</b> </h1>
<ul style="margin-left: 3em; padding-left: 0;">
<li>/trunk/configs/pjsip.conf.sample <span style="color: grey">(398037)</span></li>
</ul>
<p><a href="https://reviewboard.asterisk.org/r/2811/diff/" style="margin-left: \
3em;">View Diff</a></p>
</td>
</tr>
</table>
</div>
</body>
</html>
--
_____________________________________________________________________
-- Bandwidth and Colocation Provided by http://www.api-digital.com --
asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
http://lists.digium.com/mailman/listinfo/asterisk-dev
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic