Andrew, Thanks for the valuable feedback that is very important for us to continuously improve the protocol documentation. We will definitely consider your suggestion and we can also have further discussion during IO Lab next week.
Thanks! -------------------------------------------------------------------- Hongwei Sun - Sr. Support Escalation Engineer DSC Protocol Team, Microsoft hongw...@microsoft.com Tel: 469-7757027 x 57027 --------------------------------------------------------------------- -----Original Message----- From: cifs-protocol-boun...@cifs.org [mailto:cifs-protocol-boun...@cifs.org] On Behalf Of Andrew Bartlett Sent: Sunday, September 13, 2009 11:59 PM To: Interoperability Documentation Help Cc: cifs-proto...@samba.org; docfeedb...@thetc.org Subject: [cifs-protocol] Bitfields in the WSPP docs 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. _______________________________________________ cifs-protocol mailing list cifs-protocol@cifs.org https://lists.samba.org/mailman/listinfo/cifs-protocol
