svn commit: samba r1052 - branches/SAMBA_4_0/source/lib/ldb/man/man3

[tridge at samba.org]

Jelmer,

 > I'd like to be consistent about where we keep manpages and their
 > sources and in what format we write them. I can understand why you'd
 > like to keep them lib/ldb/docs. 

I think there is a big difference between programmer docs and user
docs. A user of Samba doesn't care about the internal C interface to
ldb, just like they don't care about the krb5 API, or the libc API. So
having the ldb programming docs as part of the Samba user docs tree
doesn't really make a lot of sense.

 > - Keep the HOWTO and other large stuff in docs/
 > - Put manpages for various subsystems, their utilities, etc in 
 >   source/*/man (DocBook/XML source in SVN, real manpage pre-generated
 >   in the tarball). E.g.
 >   source/lib/ldb/man/{ldb.7,ldbsearch.1,ldbmodify.1,...}

I don't really mind where the user docs for Samba are put. I'm happy
to leave that up to your discretion as the Samba docs maintainer. I do
care about where the programmer docs are kept, and I think they should
be part of the main source tree. For the separable libraries (libtdb,
libldb, libdcerpc, libsmb etc) I think keeping the docs for those
libraries in the subdirectories where the sources are makes
sense. This makes more minimal pain in separating these libraries from
Samba for other projects.

I also think that we don't need to tie the source format of the
programmer docs to the source format of the user docs. You've done a
great job developing a documentation framework for the Samba user
docs, but that framework is a bit heavy-weight for libraries like tdb
or ldb. For those something light-weight (like yodl or plain text) is
good. This is especially the case as there are no internationalisation
issues with programmer docs.

Cheers, Tridge