[asterisk-dev] XML documentation of apps/functions/the_rest_of_the_world

[Tilghman Lesher]

On Wednesday 16 July 2008 14:52:33 bkruse wrote:
> This message is geared towards coming up with a way to access and store
> the documentation,
> and not so much the functionality of using the XML to do cool stuff like
> language support, dialplan
> validiation, dialplan generation (based on schema), etc.
>
> The proposition:
>
> Have the documentation of the CORE generated xml file (eg all the
> documentation from everything included in build time) be stored in
> /var/lib/asterisk/docs/core.xml.
>
> When a third party module, or any other kind of module is installed
> OTHER than the main checkout, it will be their responsibility to provide
> documentation in the new format, in the right place.
>
> For example, say Cepstral wanted to do a release of their third-party
> module for Asterisk.
>
> They install app_cepstral into /usr/lib/asterisk/modules, then install
> documentation into
> the docs directory under extra/ ; The filename does not matter (all will
> be checked), so say:
> cepstral.xml. The program checks cepstral.xml, things just work, easy.
>
> Now, what happens if we download a new and awesome improved app_stack,
> that has GosubIf, which
> the older app_stack had, but now can have more arguments and functionality?
>
> Easy, the new and improved app_stack installs to
> /usr/lib/asterisk/modules; then puts it's documentation in doc/extra/
> called app_stack.xml (of whatever the developer wants to call it)
>
> The beauty of this is that app_stack ONLY has to update the GosubIf
> application documentation, because if the documentation is not found in
> the special file (in this case app_stack.xml) then it searches for it in
> core.xml.
>
> Tell me what you think!

If two competing developers created app_speak, each with different features,
and someone tried each in turn, how would the system distinguish which
documentation (neither core) to display?

-- 
Tilghman