[Asterisk-doc] I'd like to "Get Involved" :-)

[Leif Madsen]

On 3/28/06, Peter Beckman <beckman at purplecow.com> wrote:
> > First -- what does PHP.net use for their backend to control all of this?
>
>   http://www.php.net/manual/howto/chapter-framework.html
>
>    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.

>    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.

>    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!

>   So effectively exactly the same as the Asterisk Doc Project, as I
>   understand it.

Agreed -- very similar at least.

> > 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.

> > 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.

> > 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.

>   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.

>   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.

>   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?

Peter: This is sounding great -- I'm excited :)

Leif Madsen.
http://www.leifmadsen.com
http://www.oreilly.com/catalog/asterisk