web-based docs, and what to do with Samba3-HOWTO

[Simo]

On 05/21/2013 04:22 AM, Karolin Seeger wrote:
> On Tue, May 21, 2013 at 06:09:46PM +1000, Andrew Bartlett wrote:
>> On Tue, 2013-05-21 at 08:44 +0200, Karolin Seeger wrote:
>>> Hi,
>>>
>>> On Sat, May 18, 2013 at 10:58:16AM +0200, Luk Claes wrote:
>>>> On 05/18/2013 10:41 AM, Andrew Bartlett wrote:
>>>>> On Sat, 2013-05-18 at 10:30 +0200, Luk Claes wrote:
>>>>>> On 05/17/2013 11:56 PM, Andrew Bartlett wrote:
>>>>>>> On Fri, 2013-05-17 at 15:19 +0200, Luk Claes wrote:
>>>>>> If one changes the documentation it's easier to test them when one is
>>>>>> able to regenerate just the documentation than to start a build of
>>>>>> everything.
>>>>> Sure, but after you build everything once, it won't rebuild anything
>>>>> that hasn't changed after that.
>>>> make clean in the docs-xml directory can take care of this.
>>>>
>>>>>> Is there a reason the html is still in the release in that case?
>>>>> I can't find any html files (other than SWAT) in our release, or
>>>>> generated and installed by our build process.  Can you clarify what you
>>>>> refer to here?
>>>> Oh, I did not have a look at what was specifically included. If it's
>>>> only SWAT documentation then it's fine as it is.
>>> I think that I mentioned that the html man pages need to be created by the
>>> waf build, because I need them for the web site. When the docs-xml build
>>> will be removed, I need to be able to build them with waf or we don't put
>>> them on the web site any longer (but many people use it).
>> I agree the web-based manpages are useful, particularly for smb.conf,
>> and doubly because we have ditched SWAT.  What other docs do you
>> currently push?
> Curently, I am updating the html man pages only.
>
>> Is the Samba3-HOWTO on the web also updated, and given
>> the outdated content therein, should we still be publishing it?  Is out
>> of date documentation better or worse than nothing?
> No, I don't update this the Samba3-HOWTO. From my point of view, it's better to
> remove outdated documentation at some point, but I think John should comment on
> this one.
>

I think the Samba3-HOWTO should be marked historical and get to mention 
up to which version it really applies to, and left on it's own web page.
In general we should not carry docs in tree if they are not up to date.

Simo.