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

[Peter Beckman]

On Tue, 28 Mar 2006, Leif Madsen wrote:

> On 3/28/06, Peter Beckman <beckman at 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?

  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.

   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.

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

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

> 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 at purplecow.com                             http://www.purplecow.com/
---------------------------------------------------------------------------