Re: [Nbd] doc/proto.txt partial rewrite
- To: Tuomas Räsänen <tuomasjjrasanen@...1261...>
- Cc: firstname.lastname@example.org
- Subject: Re: [Nbd] doc/proto.txt partial rewrite
- From: Wouter Verhelst <w@...112...>
- Date: Wed, 5 Aug 2015 17:05:21 +0200
- Message-id: <20150805150521.GB23441@...3...>
- In-reply-to: <20150801191129.GA17826@...2011...>
- References: <20150714140333.GA12422@...3...> <20150801191129.GA17826@...2011...>
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>.
> > 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:
> 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.
It is easy to love a country that is famous for chocolate and beer
-- Barack Obama, speaking in Brussels, Belgium, 2014-03-26