[asterisk-dev] doc/ -> wiki.asterisk.org

[Olle E. Johansson]

4 nov 2010 kl. 16.49 skrev Tilghman Lesher:

> On Thursday 04 November 2010 09:12:25 Russell Bryant wrote:
>> On Thu, 2010-11-04 at 14:13 +0100, Olle E. Johansson wrote:
>>> 4 nov 2010 kl. 12.55 skrev Russell Bryant:
>>>> ----- Original Message -----
>>>> 
>>>>> I guess you haven't spent hours in a datacenter bunker with no 3G
>>>>> access and no free IP for a laptop or policies that prevent
>>>>> attaching any laptops to the network.
>>>> 
>>>> Indeed, I have not, and I'm okay with that.  :-)
>>>> 
>>>> You could have the PDF export saved on a laptop that isn't attached
>>>> to the network, though, unless you're not allowed to have a laptop
>>>> at all.  In that case, it seems like a pretty terrible environment
>>>> for getting work done.
>>> 
>>> I agree with it being a terrible environment, but it happens
>>> regurlarly when you work with large sites or carriers... Hate it
>>> every time.
>>> 
>>> I still think that we should not move the existing docs away. We can
>>> add extra stuff that's not reference - examples and comments - to the
>>> wiki, but keep the files where they are. It was enough of an issue
>>> when some of it was moved to tex - still readable though. Removing
>>> information that exists is not a good solution.
>> 
>> Well, I'm suggesting that it is moved, but that we export it into a
>> plain text (and PDF) format to include it with releases.  Is that
>> sufficient?
> 
> Something just occurred to me.  We spent a good amount of effort 2 years ago
> to XML-ize all of our inline documentation, so that it could be rendered
> both in a plaintext format, as well as in graphical format, and in multiple
> languages.  Perhaps a good amount of the documentation in doc/ needs to be
> integrated as inline documentation, accessible from the Asterisk command
> line, but also available as an export format.

As Klaus said earlier, that's how we do it in Kamailio. In the source we have XML docs
that produce README in text file format as well as web pages on the web site.
I think that's an acceptable way format. Keep all the information within the source 
directory and have copies on web sites.

/O