Posted: Tue May 02, 2006 8:48 pm Post subject: [asterisk-doc] Application Documentation
Hey guys,
After looking at the format used to document the Authenticate application, I
figured I would try to do something to help jumpstart the process for
documenting all of the applications.
I have written an Asterisk CLI command which will generate a basic file for each
application that contains the documentation we currently have inside of the
Asterisk source tree. Unfortunately, due to the limits of the way we store this
documentation internally, I am not able to break up the arguments individually.
However, I'm hoping this will help provide a starting point.
Posted: Tue May 02, 2006 9:37 pm Post subject: [asterisk-doc] Application Documentation
On Tue, 2 May 2006, Russell Bryant wrote:
Quote:
Hey guys,
After looking at the format used to document the Authenticate application, I
figured I would try to do something to help jumpstart the process for
documenting all of the applications.
I have written an Asterisk CLI command which will generate a basic file for
each application that contains the documentation we currently have inside of
the Asterisk source tree. Unfortunately, due to the limits of the way we
store this documentation internally, I am not able to break up the arguments
individually. However, I'm hoping this will help provide a starting point.
Excellent! Thank you Russell, this will definitely help speed things up a
bit. I appreciate it!
Beckman
---------------------------------------------------------------------------
Peter Beckman Internet Guy
beckman@purplecow.comhttp://www.purplecow.com/
---------------------------------------------------------------------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Tue May 02, 2006 9:40 pm Post subject: [asterisk-doc] Application Documentation
So much better than:
Asterisk -rx "show application blah" > /tmp/blah
Over and over again
Quote:
-----Original Message-----
From: asterisk-doc-bounces@lists.digium.com [mailto:asterisk-doc-
bounces@lists.digium.com] On Behalf Of Peter Beckman
Sent: Tuesday, May 02, 2006 5:41 PM
To: Discussions regarding The Asterisk Documentation Project
Subject: Re: [asterisk-doc] Application Documentation
On Tue, 2 May 2006, Russell Bryant wrote:
> Hey guys,
>
> After looking at the format used to document the Authenticate
application, I
> figured I would try to do something to help jumpstart the process
for
Quote:
> documenting all of the applications.
>
> I have written an Asterisk CLI command which will generate a basic
file
Quote:
for
> each application that contains the documentation we currently have
inside of
> the Asterisk source tree. Unfortunately, due to the limits of the
way
Quote:
we
> store this documentation internally, I am not able to break up the
arguments
> individually. However, I'm hoping this will help provide a starting
point.
Excellent! Thank you Russell, this will definitely help speed things
up a
Posted: Tue May 02, 2006 9:42 pm Post subject: [asterisk-doc] Application Documentation
On Tue, 2006-05-02 at 17:41 -0400, Peter Beckman wrote:
Quote:
Excellent! Thank you Russell, this will definitely help speed things up a
bit. I appreciate it!
While we're on the topic, can we change your doc infrastructure to stop
calling applications functions, and call them applications instead?
Dialplan functions are different than dialplan applications, and I'm
afraid we'll confuse people.
-Jared
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Tue May 02, 2006 9:57 pm Post subject: [asterisk-doc] Application Documentation
On Tue, 2006-05-02 at 17:45 -0400, Alexander Lopez wrote:
Quote:
So much better than:
Asterisk -rx "show application blah" > /tmp/blah
Over and over again
Yeah... having done that (when I wrote appendix B of the starfish book),
this is a much more elegant solution. We all owe Russell doughnuts for
doing this!
-Jared
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Tue May 02, 2006 11:44 pm Post subject: [asterisk-doc] Application Documentation
Jared Smith wrote:
Quote:
While we're on the topic, can we change your doc infrastructure to stop
calling applications functions, and call them applications instead?
Dialplan functions are different than dialplan applications, and I'm
afraid we'll confuse people.
Indeed. I meant to mention this when I sent the first email. If you look at
the files that the CLI command generates for you, it is using "applications"
instead of "functions". Speaking of functions, I can update this later to
support the dialplan functions as well.
Russell
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Wed May 03, 2006 3:27 am Post subject: [asterisk-doc] Application Documentation
On 5/2/06, Russell Bryant <russell@digium.com> wrote:
Quote:
Jared Smith wrote:
> While we're on the topic, can we change your doc infrastructure to stop
> calling applications functions, and call them applications instead?
> Dialplan functions are different than dialplan applications, and I'm
> afraid we'll confuse people.
Indeed. I meant to mention this when I sent the first email. If you look at
the files that the CLI command generates for you, it is using "applications"
instead of "functions". Speaking of functions, I can update this later to
support the dialplan functions as well.
Very cool! What might we do about being able to keep all of this
documentation synchronized between the documentation project, and
Asterisk itself? It might be pretty useful to have a website where
people can read about the various applications and functions, and for
that documentation to be in sync with what is show when you do a show
application <foo>. It logically seems to make the most sense to use
DocBook in Asterisk to keep all the documentation centralized
(end-user documentation of course -- coding documentation is in
doxygen).
Suggestions? I think this would be a good topic to put on the
conference call for next week.
Leif Madsen.
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Wed May 03, 2006 3:26 pm Post subject: [asterisk-doc] Application Documentation
Leif Madsen wrote:
Quote:
Very cool! What might we do about being able to keep all of this
documentation synchronized between the documentation project, and
Asterisk itself? It might be pretty useful to have a website where
people can read about the various applications and functions, and for
that documentation to be in sync with what is show when you do a show
application <foo>.
I'd like to reiterate the ideas that Mark presented on the conference
call when we were discussion this a couple weeks ago. The idea was to
track which SVN revision number the documentation is up to date with.
Of course, having the documentation crew look at every single commit to
see if it affects documentation doesn't sound all that appealing.
However, one thing we could probably do is make a policy to put some
kind of tag in the commit messages that indicates that the commit
affects documentation. Then, we could have a post-commit script that
looks for this tag, and sends the commit to the documentation mailing
list when appropriate.
Quote:
It logically seems to make the most sense to use
DocBook in Asterisk to keep all the documentation centralized
(end-user documentation of course -- coding documentation is in
doxygen).
I'm not sure if this is the direction we should take. However, the real
issue is that the information about the arguments to an application is
not stored in any way that code can automatically figure out what to do
with them.
Essentially, there is a big blob of text that describes all of the
options, which is what you see when you do "show application whatever".
Then, the code itself in every application manually parses the string
of arguments. These two things need to be somewhat unified so that the
arguments can be parsed before they make it to the application. When we
get this cleaned up, the ability to generate documentation at the level
of refinement that we need for this should be solved as a side benefit.
Quote:
Suggestions? I think this would be a good topic to put on the
conference call for next week.
We discussed some of these issues during the first conference call and
agreed that it was something we would revisit after 1.4 is released.
I'd rather reserve the time in the conference calls for things that need
to happen before 1.4 released for now.
Russell
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Thu May 04, 2006 3:40 pm Post subject: [asterisk-doc] Application Documentation
On 5/3/06, Russell Bryant <russell@digium.com> wrote:
Quote:
Leif Madsen wrote:
> Very cool! What might we do about being able to keep all of this
> documentation synchronized between the documentation project, and
> Asterisk itself? It might be pretty useful to have a website where
> people can read about the various applications and functions, and for
> that documentation to be in sync with what is show when you do a show
> application <foo>.
I'd like to reiterate the ideas that Mark presented on the conference
call when we were discussion this a couple weeks ago. The idea was to
track which SVN revision number the documentation is up to date with.
Of course, having the documentation crew look at every single commit to
see if it affects documentation doesn't sound all that appealing.
However, one thing we could probably do is make a policy to put some
kind of tag in the commit messages that indicates that the commit
affects documentation. Then, we could have a post-commit script that
looks for this tag, and sends the commit to the documentation mailing
list when appropriate.
Thanks Russell -- that happened to be the one conference call I was
unable to make.
I guess what I'm thinking is that we somehow centralize the
documentation so that if something gets modified in the main Asterisk
branch, it'll automatically update the documentation project, and
vice-versa. That way, when we "fix" or clarify some sort of
documentation in the project, it will automatically keep the Asterisk
branch updated with the new documentation. At the very least, I'd like
to see it somehow mark that documentation has been updated and needs
to be reviewed. That way, we're keeping things consistant and not
needing to backport documentation changes between the two projects
that essencially have the same goals.
Quote:
> It logically seems to make the most sense to use
> DocBook in Asterisk to keep all the documentation centralized
> (end-user documentation of course -- coding documentation is in
> doxygen).
I'm not sure if this is the direction we should take. However, the real
issue is that the information about the arguments to an application is
not stored in any way that code can automatically figure out what to do
with them.
Essentially, there is a big blob of text that describes all of the
options, which is what you see when you do "show application whatever".
Then, the code itself in every application manually parses the string
of arguments. These two things need to be somewhat unified so that the
arguments can be parsed before they make it to the application. When we
get this cleaned up, the ability to generate documentation at the level
of refinement that we need for this should be solved as a side benefit.
I'd agree with that. Whether its DocBook or some other method, it
would be nice to be able to keep the changes merged together so that
when one or the other project updates some text, both projects receive
the update. I realize there might need to be some sort of flag that
goes to the Asterisk project to say, "Hey, the docs project updated
something -- verify this is true!" -- but I'd assume anything that
goes into Asterisk documentation directly can safely flow down to the
docs project (maybe we want the flag thing to go the other way to so
there is more eyes looking at the docs and verifying?).
Quote:
> Suggestions? I think this would be a good topic to put on the
> conference call for next week.
We discussed some of these issues during the first conference call and
agreed that it was something we would revisit after 1.4 is released.
I'd rather reserve the time in the conference calls for things that need
to happen before 1.4 released for now.
Understood. I had forgotten there was discussion of documentation in
the conference call that I missed.
Leif Madsen.
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum