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

[Andrew Bartlett]

On Tue, 2013-05-21 at 10:22 +0200, 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.

Until we remove it, if we can at least refresh this from master, that
would be great, as I did a pile of work on that in September to remove
the really, really incorrect info from some of the pages (like
security=share references). 

Andrew Bartlett

-- 
Andrew Bartlett                                http://samba.org/~abartlet/
Authentication Developer, Samba Team           http://samba.org