[cifs-protocol] Bitfields in the WSPP docs

[Andrew Bartlett]

Over a year ago, I wrote to this list about the incredible frustration I
suffer on a regular basis attempting to read and use the Microsoft
documentation.  

The problem was regarding the layout and incomprehensible system used to
describe the bitfields that occur in so many of the protocol documents I
use, and a year on, I was wondering if I had to reinforce my concerns.  

But there is hope - I've just seen a copy of the MS-CIFS document that
Chris Hertel has helped author (contracting to Microsoft), and I'm truly
amazed by the progress that has been made.   If this document survives
intact to final form, it will show that programmer-compatible
documentation can be produced within this framework.

To pick a random example, I see 2.2.4.43 'SMB_COM_WRITEX_ANDX'.  It
shows the format of the packet in a clear, text based format, replacing
the block diagrams, and the error codes are clearly given both textual
names and hexidecimal values.  (While it is incredibly disappointing to
no longer need to do 2^(n-31) in my head, I do find it a little
easier ;-)

It also puts to rest the incredibly insane 'bytes in little endian, bits
in big endian' that I have to say was so truly 'special'.

What I'm trying to say is that I really, really appreciate the
improvement. 

These make the documents the single best example of network interface
documentation formatting that I have seen from this protocol program, I
strongly hope that whatever challenges have prevented the use of such
clear language in other documents might finally have been overcome, so
that other critical documents, the RPC documents in particular, can also
benefit from this treatment. 

Thanks, 

Andrew Bartlett

-- 
Andrew Bartlett                                http://samba.org/~abartlet/
Authentication Developer, Samba Team           http://samba.org
Samba Developer, Cisco Inc.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://lists.samba.org/pipermail/cifs-protocol/attachments/20090913/893545cf/attachment.pgp>