On 5/3/06, Russell Bryant <[EMAIL PROTECTED]> wrote:
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.
> 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?).
> 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 --
asterisk-doc mailing list
To UNSUBSCRIBE or update options visit:
http://lists.digium.com/mailman/listinfo/asterisk-doc
