Re: [Nbd] doc/proto.txt partial rewrite

[Wouter Verhelst <w@...112...>]

Hi Tuomas,

On Sat, Aug 01, 2015 at 10:11:29PM +0300, Tuomas Räsänen wrote:
> On Tue, Jul 14, 2015 at 04:03:33PM +0200, Wouter Verhelst wrote:
> > Hi folks,
> > 
> 
> Hi Wouter,
> 
> > proto.txt was getting a bit messy, with it repeating itself a few times
> > (sometimes even contradicting itself) and little structure in general.
> > 
> > I've tried to fix that. You can see the list of changes (20 of them) on
> > <https://github.com/yoe/nbd/compare/proto-markdown>.
> > 
> 
> <snip>
> 
> > 
> > As such, I would obviously love it if someone could make some time and
> > review the changes that I've done.
> > 
> 
> Sorry for taking so long.

No worries; such things happen (case in point: took me long enough ;)

> I've been busy contributing to another great piece of software lately, horst:
> http://br1.einfach.org/tech/horst/
> 
> But, I skimmed the patch set and it looked good, good job. I rendered it as HTML
> with pandoc and it was quite readable. I am not a big fan of markdown though: it
> is not expressive enough (tables for example?) and I don't even know *which*
> markdown I should be using, but yes, it's better than nothing.

I'm not a huge fan of markdown myself, but it has several things going for it:
- It's fairly popular (so many people know how it works, more than is the case
  for competing formats)
- github (and most other git hosters) can render it (so you get a useful
  preview without having to download the file)
- It's pretty readable in plain text (so rendering isn't strictly required).

> But in overall, the document looks much better than before, I didn't spot any
> big issues. I just pused few minor fixes/enhancements to
> https://github.com/tuomasjjrasanen/nbd on branch proto-markdown.
> 
> A pull request is available here: https://github.com/yoe/nbd/pull/28

Thanks, that looks great. Well, mostly.

> A short summary of those changes:
> 
> - call the first protocol phase consistently "the handshake phase"

Except you didn't, you only changed the titles. The text still refers to
"negotiation" in several of the paragraphs.

I'm a bit in doubt as to what to do about it. The phase is a handshake,
but yeah, there is a negotiation going on...

> - call the second protocol phase "the transmission phase" instead of "the data
>   push phase"

Yeah, that sounds much better, thanks.

> - just few typo and flow fixes

Merged as is (we can always improve later on), and pushed to master.
Thanks!

-- 
It is easy to love a country that is famous for chocolate and beer

  -- Barack Obama, speaking in Brussels, Belgium, 2014-03-26