On Tue, 28 Mar 2006, Leif Madsen wrote:
On 3/28/06, Peter Beckman <[EMAIL PROTECTED]> 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
[EMAIL PROTECTED] 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
