Fixing the documentation

Gerald Carter gcarter at
Tue Aug 28 06:12:21 GMT 2001

On Sun, 19 Aug 2001, Joe Rhett wrote:

> 1. Why isn't there a document for upgrading from 2.0.x to 2.2.x ?
> 	Changes like ${DOMAIN}.SID to MACHINE.SID aren't documented anywhere.
> 	Several little changes to smb.conf are worth noting.
> 	..had this document existed, I could have saved 4 hours of time.

Cause the DOMAIN.SID was never released in a production version
of Samba.  Sounds like you were using an old cvs version.

> 2. Why is the documentation so disjointed and incomplete?
> I am willing to take on the task of unifying the existing documentation.
> How should I go about doing this? How would I submit updates?

Submit them to me <jerry at> against the SGML/DocBook source
(docs/docbook/*).  Don't diff against the HTML files for sure.

> If I took this on, I would probably want to:
> 1. Do the complete documentation set in HTML. PDF is nice, but PDF readers
> aren't always available and there is A LOT of documentation that isn't always
> relevant ( WfWG, cluster.. )

The DocBook source is used to generate HTML and the the PDF file from the
HTML source.  So I'm not sure what you mean here.

> 2. Create a quick upgrade document for existing sites that don't need to
> enable new functionality, just update the code.

Would love to see this.

> 3. Make the PDF be a good starting document easy to print, but contain
> references to the HTML as a complete documentation source. The PDF is
> a bit disjointed at the moment, trying to cover many topics and still
> missing some basic essentials.

It is designed as a collection of HOWTO's.  Not as a book.  The idea is to
allow individuals to create a single chapter and havce it included in the
collection.  If someone would like to take on the role of editor and make
it more continuous that would be appreicated.

> 4. Move all references to Windows for WorkGroups to a separate section.
> This isn't relevant to any installation I've seen in over 6 years. This
> would prevent confusion and many FAQs on the mailing list, while providing
> a single clear document of the changes necessary for Windows for Workgroups
> support.

Actually, i spoke with someone last week who still had WfWg on the
network.  We cannot release a version of Samba that doesn't support DOS
clients without hearing screams.

cheers, jerry
 ---------------------------------------------------------------------         VA Linux Systems              SAMBA Team                          
 --"I never saved anything for the swim back." Ethan Hawk in Gattaca--

More information about the samba-technical mailing list