Posted: Tue Mar 28, 2006 6:59 pm Post subject: [Asterisk-doc] I'd like to "Get Involved" :-)
Hey --
I love asterisk and I love php.net's online documentation and I hate that
Asterisk is so horribly documented.
I was going to start my own DocBook for Asterisk, but it looks like the
documentation project has already started that.
So, I'm in. My personal goal is to make Asterisk DocBook documentation as
easy, succinct and clear as PHP's documentation; hopefully that falls in
line with some of the goals of the project's leaders as well!
I looked at a few of the docs online under the Get Involved link, but I
didn't see anything as clear as the above link. Did I miss it?
Anyway, I hope to help as I myself learn Asterisk. Mmmmm, XML. :-)
Beckman
---------------------------------------------------------------------------
Peter Beckman Internet Guy
beckman@purplecow.comhttp://www.purplecow.com/
---------------------------------------------------------------------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
-----Original Message-----
From: Peter Beckman [mailto:beckman@purplecow.com]
Sent: March 28, 2006 2:01 PM
To: asterisk-doc@lists.digium.com
Subject: [Asterisk-doc] I'd like to "Get Involved" :-)
Hey --
I love asterisk and I love php.net's online documentation and
I hate that Asterisk is so horribly documented.
I was going to start my own DocBook for Asterisk, but it
looks like the documentation project has already started that.
So, I'm in. My personal goal is to make Asterisk DocBook
documentation as easy, succinct and clear as PHP's
documentation; hopefully that falls in line with some of the
goals of the project's leaders as well!
I looked at a few of the docs online under the Get Involved
link, but I didn't see anything as clear as the above link.
Did I miss it?
Anyway, I hope to help as I myself learn Asterisk. Mmmmm, XML. :-)
Beckman
--------------------------------------------------------------
-------------
Peter Beckman
Internet Guy
beckman@purplecow.com http://www.purplecow.com/
--------------------------------------------------------------
-------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Though not very useful for those of us who just want very fast, HTML-based access
to functions, config files, etc. Have you ever seen the PHP.net
documentation?
Go to php.net/substr and it takes you directly to a page all about the
substr function. Examples, notices about versions this function is
supported in, caveats, comments, etc.
That's why I want to help write DocBook-based documentation for Asterisk,
so Asterisk can have the same, easy to read, online documentation.
Beckman
Quote:
> -----Original Message-----
> From: Peter Beckman [mailto:beckman@purplecow.com]
> Sent: March 28, 2006 2:01 PM
> To: asterisk-doc@lists.digium.com
> Subject: [Asterisk-doc] I'd like to "Get Involved" :-)
>
> Hey --
>
> I love asterisk and I love php.net's online documentation and
> I hate that Asterisk is so horribly documented.
>
> I was going to start my own DocBook for Asterisk, but it
> looks like the documentation project has already started that.
>
> So, I'm in. My personal goal is to make Asterisk DocBook
> documentation as easy, succinct and clear as PHP's
> documentation; hopefully that falls in line with some of the
> goals of the project's leaders as well!
>
> http://www.php.net/manual/howto/
>
> I looked at a few of the docs online under the Get Involved
> link, but I didn't see anything as clear as the above link.
> Did I miss it?
>
> Anyway, I hope to help as I myself learn Asterisk. Mmmmm, XML. :-)
>
> Beckman
> --------------------------------------------------------------
> -------------
> Peter Beckman
> Internet Guy
> beckman@purplecow.com
> http://www.purplecow.com/
> --------------------------------------------------------------
> -------------
> _______________________________________________
> --Bandwidth and Colocation provided by Easynews.com --
>
> Asterisk-Doc mailing list
> To UNSUBSCRIBE or update options visit:
> http://lists.digium.com/mailman/listinfo/asterisk-doc
>
>
> --
> No virus found in this incoming message.
> Checked by AVG Free Edition.
> Version: 7.1.385 / Virus Database: 268.3.2/294 - Release
> Date: 27/03/2006
>
>
--
No virus found in this outgoing message.
Checked by AVG Free Edition.
Version: 7.1.385 / Virus Database: 268.3.2/294 - Release Date: 27/03/2006
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
---------------------------------------------------------------------------
Peter Beckman Internet Guy
beckman@purplecow.comhttp://www.purplecow.com/
---------------------------------------------------------------------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Tue Mar 28, 2006 11:21 pm Post subject: [Asterisk-doc] I'd like to "Get Involved" :-)
On 3/28/06, Peter Beckman <beckman@purplecow.com> wrote:
Quote:
Though not very useful for those of us who just want very fast, HTML-based access
to functions, config files, etc. Have you ever seen the PHP.net
documentation?
Go to php.net/substr and it takes you directly to a page all about the
substr function. Examples, notices about versions this function is
supported in, caveats, comments, etc.
That's why I want to help write DocBook-based documentation for Asterisk,
so Asterisk can have the same, easy to read, online documentation.
Fantastic idea!!!
I have a few issues with the idea though.
First -- what does PHP.net use for their backend to control all of this?
Second -- how do they keep PHP documentation current / in-sync with
that which is distributed with PHP itself?
Third -- Does PHP use DocBook to control all this documentation
content? If not, what do they use, and how easy will it be to allow
certain people access to changing things directly -- what about
community submitted documentation? Would be nice to allow people to
submit corrections, but allow the administrators the ability to
approve / review submissions before they get "published"
I really like the idea, especially since php.net has the nice feature
of allowing people to post to the various functions with comments that
usually includes useful examples of how to use the function. I can
envision the same thing for the dialplan functions and applications.
How might we approach the configuration files and the options
associated with them in this manner as well -- the php.net style seems
like it'd work well with the dialplan applications and functions, but
not sure about the configuration files themselves.
I like the idea -- lets see if there is a relatively easy way to
implement it without requiring much in terms of overhead work with
most time spent actually writing the documentation (and not dealing
with DocBook syntax etc.. which I think turns off a lot of people).
I'm not opposed to changing the backend if it would help.
Posted: Wed Mar 29, 2006 4:03 am Post subject: [Asterisk-doc] I'd like to "Get Involved" :-)
On Tue, 28 Mar 2006, Leif Madsen wrote:
Quote:
On 3/28/06, Peter Beckman <beckman@purplecow.com> wrote:
> Though not very useful for those of us who just want very fast, HTML-based access
> to functions, config files, etc. Have you ever seen the PHP.net
> documentation?
>
> Go to php.net/substr and it takes you directly to a page all about the
> substr function. Examples, notices about versions this function is
> supported in, caveats, comments, etc.
>
> That's why I want to help write DocBook-based documentation for Asterisk,
> so Asterisk can have the same, easy to read, online documentation.
Fantastic idea!!!
I have a few issues with the idea though.
First -- what does PHP.net use for their backend to control all of this?
The PHP documentation is written in XML using the DocBook DTD. If you
would like to contribute to the PHP documentation project, you need to at
least know the very basics of XML and DocBook.
The XML files are stored on a central server, and can be reached with a
CVS client. There are many CVS clients you can use, although we recommend
one command line tool or a proven WYSIWYG tool.
You will need more programs and tools to manipulate the XML files and
test their content for errors. What tools you need depends on the
operating system you use. Linux or some sort of Unix is recommended,
although many things in phpdoc work on Windows. You will find more
information about the tools you need in the tools section.
So effectively exactly the same as the Asterisk Doc Project, as I
understand it.
Quote:
Second -- how do they keep PHP documentation current / in-sync with
that which is distributed with PHP itself?
I don't believe that PHP actually distributes documentation with the PHP
source/binaries. All of the Help/Documentation is online, though is
available for download in the following formats:
* Single HTML, gzipped
* Multi HTML, tar gzipped
* Windows HTML Help (.chm)
* Extended HTML Help
They may include the single HTML.gz in the distribution, ~2MB compressed
with gzip.
Quote:
Third -- Does PHP use DocBook to control all this documentation
content?
Yes. Control is via CVS -- you have to email to get a CVS account, then
you have to have Karma in order to write. I don't know how they implement
it, but that's what they state.
Quote:
I really like the idea, especially since php.net has the nice feature
of allowing people to post to the various functions with comments that
usually includes useful examples of how to use the function. I can
envision the same thing for the dialplan functions and applications.
How might we approach the configuration files and the options
associated with them in this manner as well -- the php.net style seems
like it'd work well with the dialplan applications and functions, but
not sure about the configuration files themselves.
I like the idea -- lets see if there is a relatively easy way to
implement it without requiring much in terms of overhead work with
most time spent actually writing the documentation (and not dealing
with DocBook syntax etc.. which I think turns off a lot of people).
I'm not opposed to changing the backend if it would help.
Hey, if PHP is using DocBook, and so are you, we can "borrow" a lot of
knowledge and pre-written XSLTs and such from the PHP project.
Now, this may be a separate project from the "book" Jim pointed me to
earlier. The book seems to be more of a read-in-bed and learn Asterisk
from a 10,000 foot level, with specific helpful examples.
I'm suggesting a reference for people who are in the midst of a dialplan,
or banging their head about CDRs (the exten => h with no ResetCDR(w)
banged my head for 2 hours today). Both projects may have overlap, but
instead of a conversational tone, just the facts.
I'll check out the PHP.net documentation tonight from CVS and take a look,
then try in the next few days to put together a start of the Asterisk
Reference.
Sound good?
Beckman
---------------------------------------------------------------------------
Peter Beckman Internet Guy
beckman@purplecow.comhttp://www.purplecow.com/
---------------------------------------------------------------------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
The PHP documentation is written in XML using the DocBook DTD. If you
would like to contribute to the PHP documentation project, you need to at
least know the very basics of XML and DocBook.
Cool -- not a problem since we originally started the AstDocs project
in DocBook format -- I'd like to take a look at the PHP XML files
though to see how their templating system is setup -- our's works, but
is a bit out of date.
Quote:
The XML files are stored on a central server, and can be reached with a
CVS client. There are many CVS clients you can use, although we recommend
one command line tool or a proven WYSIWYG tool.
Cool -- we have this setup already as well -- have yet to find a good
WYSISWYG editor though -- do you have any suggestions? So far I've
been using vim, but I wouldn't mind some sort of GUI editor -- and I'm
sure others would as well.
Quote:
You will need more programs and tools to manipulate the XML files and
test their content for errors. What tools you need depends on the
operating system you use. Linux or some sort of Unix is recommended,
although many things in phpdoc work on Windows. You will find more
information about the tools you need in the tools section.
Great, I'll check it out this weekend!
Quote:
So effectively exactly the same as the Asterisk Doc Project, as I
understand it.
Agreed -- very similar at least.
Quote:
> Second -- how do they keep PHP documentation current / in-sync with
> that which is distributed with PHP itself?
I don't believe that PHP actually distributes documentation with the PHP
source/binaries. All of the Help/Documentation is online, though is
available for download in the following formats:
* Single HTML, gzipped
* Multi HTML, tar gzipped
* Windows HTML Help (.chm)
* Extended HTML Help
They may include the single HTML.gz in the distribution, ~2MB compressed
with gzip.
Cool -- I was just thinking about how we might be able to distribute
the documentation with Asterisk at some point, but that might not be
necessary as we could probably get some sort of README file in the
doc/ dir of the distribution which points to the AstDocs project once
we get something like the PHP.net site as setup.
Quote:
> Third -- Does PHP use DocBook to control all this documentation
> content?
Yes. Control is via CVS -- you have to email to get a CVS account, then
you have to have Karma in order to write. I don't know how they implement
it, but that's what they state.
OK cool, we already have something like this setup.
Quote:
> I really like the idea, especially since php.net has the nice feature
> of allowing people to post to the various functions with comments that
> usually includes useful examples of how to use the function. I can
> envision the same thing for the dialplan functions and applications.
>
> How might we approach the configuration files and the options
> associated with them in this manner as well -- the php.net style seems
> like it'd work well with the dialplan applications and functions, but
> not sure about the configuration files themselves.
>
> I like the idea -- lets see if there is a relatively easy way to
> implement it without requiring much in terms of overhead work with
> most time spent actually writing the documentation (and not dealing
> with DocBook syntax etc.. which I think turns off a lot of people).
>
> I'm not opposed to changing the backend if it would help.
Hey, if PHP is using DocBook, and so are you, we can "borrow" a lot of
knowledge and pre-written XSLTs and such from the PHP project.
Agreed! Sounds like we already have most of the infrastructure setup,
just need look at the PHP.net XSLT framework and see if its better
than what we have now, and adjust it as needed.
Quote:
Now, this may be a separate project from the "book" Jim pointed me to
earlier. The book seems to be more of a read-in-bed and learn Asterisk
from a 10,000 foot level, with specific helpful examples.
Yes, this is the book that Jared, Jim, and myself worked on last year
and made freely available to the world.
Quote:
I'm suggesting a reference for people who are in the midst of a dialplan,
or banging their head about CDRs (the exten => h with no ResetCDR(w)
banged my head for 2 hours today). Both projects may have overlap, but
instead of a conversational tone, just the facts.
I really, really like this idea -- this is something that I can see
the AstDocs project turning more into than the "book" style that we
had originally started on. We can continue working on a book style
separate of the "reference" style you are proposing, but I think a
reference style like PHP.net will actually allow more contributions
since people won't need to be so dedicated to writing such a large
section of knowledge. If they have recently discovered something
useful (such as yourself with exten => h and ResetCDR(w)) then we can
accept those little tidbits of information that will be extremely
useful to the Asterisk community.
Quote:
I'll check out the PHP.net documentation tonight from CVS and take a look,
then try in the next few days to put together a start of the Asterisk
Reference.
Sound good?
Thats awesome! I look very much forward to seeing what you propose for
moving this forward! I'm in training all this week, but will be at VON
Canada next week for a few days, so hopefully we'll have Internet
access and I'll be able to spend some time helping you get some of
this stuff implemented.
Jared: Is there a way we can maybe get SVN implemented so that we can
create a separate "branch" for this endevour?
Posted: Wed Mar 29, 2006 1:38 pm Post subject: [Asterisk-doc] I'd like to "Get Involved" :-)
Quote:
I'll check out the PHP.net documentation tonight from CVS and take a look,
then try in the next few days to put together a start of the Asterisk
Reference.
Sound good?
Also, don't be afraid to check us out at #asterisk-doc on the FreeNode
IRC network. Jared is jsmith, and I'm blitzrage in the channel. If we
don't reply right away, its probably because we're either working, or
in training or something, but if you idle for a while, we'll be in to
find you.
Posted: Wed Mar 29, 2006 4:09 pm Post subject: [Asterisk-doc] I'd like to "Get Involved" :-)
Leif Madsen wrote:
Quote:
Cool -- we have this setup already as well -- have yet to find a good
WYSISWYG editor though -- do you have any suggestions? So far I've
been using vim, but I wouldn't mind some sort of GUI editor -- and I'm
sure others would as well.
I've been trying to learn Docbook for another project, too, recently and
found Vex:
http://vex.sf.net
It looks like it'll be a pretty good Docbook editor, though to me it
seemed like it wasn't quite there yet. It could be partly my novice
Docbook skills were part of the problem.
A more mature product is LyX:
http://lyx.org
It's primarily for LaTeX, but it supposedly has Docbook support too.
I've just started playing with it, and I haven't figured out the Docbook
features yet.
The other one I want to evaluate (but haven't yet) is the free version
of XMLmind's XML Editor:
http://www.xmlmind.com/xmleditor/
It's the little brother to a commercial product. From the little I've
played with it, it seems to be well well written.
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Thu Mar 30, 2006 7:35 pm Post subject: [Asterisk-doc] I'd like to "Get Involved" :-)
That would be awesome. I really love PHP's docs too, and I think that
the documentation on voip-info is sort of fucked up, same goes for
asteriskdocs.org. Im willing to help too.
Peter Beckman wrote:
Quote:
Hey --
I love asterisk and I love php.net's online documentation and I hate that
Asterisk is so horribly documented.
I was going to start my own DocBook for Asterisk, but it looks like the
documentation project has already started that.
So, I'm in. My personal goal is to make Asterisk DocBook
documentation as
easy, succinct and clear as PHP's documentation; hopefully that falls in
line with some of the goals of the project's leaders as well!
Posted: Sat Apr 01, 2006 5:31 pm Post subject: [Asterisk-doc] I'd like to "Get Involved" :-)
On 3/30/06, Jonas Laursen <decko@mail.dk> wrote:
Quote:
That would be awesome. I really love PHP's docs too, and I think that
the documentation on voip-info is sort of fucked up, same goes for
asteriskdocs.org. Im willing to help too.
The problem with asteriskdocs.org is that it hasn't been updated in
quite some time -- we had been spending the last year working on the
starfish book.
I'm really interested in adding a PHP.net style section to the
asteriskdocs.org site -- it'd make it a lot easier to add new
documentation I imagine. Would really like to keep it all in SVN as
well. None of this sounds impossible to do, just some time is needed
to build the backend and infrastructure to handle it.
I was looking at the php.net site, and apparently the code they are
using is open-source (available). I'll have to spend a bit more time
looking around, but I wonder if we should just implement the same
backend that the php.net folks are using -- it seems to be exactly
what we are trying to do :)
ljam.
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Sat Apr 01, 2006 9:51 pm Post subject: [Asterisk-doc] I'd like to "Get Involved" :-)
Leif Madsen wrote:
Quote:
I was looking at the php.net site, and apparently the code they are
using is open-source (available). I'll have to spend a bit more time
looking around, but I wonder if we should just implement the same
backend that the php.net folks are using -- it seems to be exactly
what we are trying to do :)
As long as this doesn't end up duplicating the Doxygen API docs we
already maintain, I think this is a fine idea.
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Tue Apr 11, 2006 7:10 pm Post subject: [Asterisk-doc] I'd like to "Get Involved" :-)
On 4/1/06, Kevin P. Fleming <kpfleming@digium.com> wrote:
Quote:
> I was looking at the php.net site, and apparently the code they are
> using is open-source (available). I'll have to spend a bit more time
> looking around, but I wonder if we should just implement the same
> backend that the php.net folks are using -- it seems to be exactly
> what we are trying to do :)
As long as this doesn't end up duplicating the Doxygen API docs we
already maintain, I think this is a fine idea.
I think this would mostly be a user-level kind of thing, and wouldn't
touch on the API documentation which is more the core coding of
Asterisk -- seems to me this would be higher level stuff, and would
compliment, and not duplicate, the work in the doxygen API docs.
Leif Madsen.
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Tue Apr 11, 2006 11:34 pm Post subject: [Asterisk-doc] I'd like to "Get Involved" :-)
What is the status on this, I am looking at having some free time and
would like to help.
On 4/11/06, Leif Madsen <asterisk.leif.madsen@gmail.com> wrote:
Quote:
On 4/1/06, Kevin P. Fleming <kpfleming@digium.com> wrote:
> > I was looking at the php.net site, and apparently the code they are
> > using is open-source (available). I'll have to spend a bit more time
> > looking around, but I wonder if we should just implement the same
> > backend that the php.net folks are using -- it seems to be exactly
> > what we are trying to do :)
>
> As long as this doesn't end up duplicating the Doxygen API docs we
> already maintain, I think this is a fine idea.
I think this would mostly be a user-level kind of thing, and wouldn't
touch on the API documentation which is more the core coding of
Asterisk -- seems to me this would be higher level stuff, and would
compliment, and not duplicate, the work in the doxygen API docs.
Leif Madsen.
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
--
---
Andrew Latham - AKA: LATHAMA (lay-th-ham-eh)
lathama@lathama.com - lathama@yahoo.com - lathama@gmail.com
If any of the above are down we have bigger problems than my email!
Hind sight is most always 20/20 or better.
---
_______________________________________________
--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