Improve English language, and internal and external linking

[adamretter]

I have gone through the HTTP Client 1.0 spec from top to bottom.

1. I have tried to make minor improvements to the English language to make the intention clearer.
2. I have simplified some of the html code, reSpec does a lot of automation for you, that you don't need to duplicate e.g. you don't need to specify the id on an <a> when linking to a definition.
3. I have improved the internal linking between terms and their definitions.
4. I have added further external links and references where appropriate.

I think the spec still has a rather conversational style and uses too much wordy text to define things, where bullet points, or a more succinct style could be used.

I have not made any major sweeping changes to the text, as unfortunately I don't have the time to spend on that.

There are some technical issues which could be improved. However I don't think it is worth the effort, as it has been 8 years since the last draft of the spec; It seems unlikely that anyone would implement them (especially in light of the HTTP 2.0 module draft being available).

[joewiz]

Wow, this is such a major improvement! I just have a couple of small edits.

[adamretter]

@joewiz thanks for the pointers, I am happy to incorporate those.

@fgeorges @ChristianGruen any comments?

[ChristianGruen]

Great edits! And I’m always learning something when scanning thorough revisions like this.

I was wondering if it’s correct to say that “it/a function parses” something? In German, it’s actually pretty common to let objects do something, but sometime told me that it’s better to use a passive construction in English (“…is parsed by the function”), or something completely different.

Well, that’s just nitpicking (and won’t improve the spec itself). I’d be happy to see the PR merged.

[joewiz]

I agree, "the function parses" sounds unusual here; perhaps we should say the client (as in the HTTP client) parses, and then the function returns a representation?

[fgeorges]

Thank you @adamretter! Not sure how I can make changes before merging. Do I merge then edit afterwards? (even for changes I do not want?) Or I simply ask you? Or anything else?

[adamretter]

@joewiz @ChristianGruen thanks, I have incorporated the feedback and rebased.

[adamretter]

@fgeorges Good question!

So if there are problems with changes in the PR, then I would suggest to do a review. I can then fix those changes.

Otherwise, I generally view PRs like this:

• Does the PR improve the overall situation, even if it doesn't fix everything?

If so, then I usually merge. You can then send a follow-up PR with changes, which is good as it gives others like @joewiz @ChristianGruen an opportunity to help you can any new language issues. The PR approach also keeps everyone up-to-date on what is happening. i.e. changes don't appear that no one apart from the originator knew about that.

That is to say PR's represent a community method of development.
All other Open Source projects which I contribute to, pretty much have the role that no-one, not even the project owner, directly commits to the repository. Everyone must contribute through PR's so that there is a many eyes approach.

[adamretter]

@fgeorges any progress on this please?

[fgeorges]

@adamretter I guess reviews is the way to go here then, as some changes must be discarded (so it would be weird to accept them then create another PR to reverse them...)

[fgeorges]

@adamretter BTW, I can't see @joewiz 's own comments. Is it because you integrated them?

[fgeorges]

@adamretter I added some reviews (mostly details actually.) Great PR, thanks!

[adamretter]

@fgeorges I incorporated your review. Thanks :-) Should be good to go now.

[adamretter]

@fgeorges Have you seen the changes I made?

I believe that was incorporated in Adam's changes.

[fgeorges]

@adamretter Sorry, I didn't received a notif for your responses. Merged now. Thanks!

[ChristianGruen]

Great!