Porter Handbook: Update documentation on porting Haskell programs.

[fernape]

Thanks!
Very good job and update for the PHB!

documentation/content/en/books/porters-handbook/special/_index.adoc

985

This minimal Makefile fetches... (remove _allows us_).
...with _the_ cabal-extract helper target...

998

Either full stop after ${WRKSRC} or link the two sentences with:

Now _that_ we have...., we can use...

1024–1025

Revisions can affect [.filename]#.cabal# files _only (only at the end). Then full stop instead of _,_

...files only_._ Note additional...

1047

under _the_ share/${PORTNAME} directory...

1048

...define _the_ CABAL_WRAPPER_SCRIPTS knob...

1055

Avoid contractions. Also simplify sentence. How about this?

devel/hs-profiteur is a Haskell application that...

1103

Now the port _will_ install

1107

remove ","
...knob apart from...

1117

Either

The net-p2p/cardano-node _port_...

or

net-p2p/cardano-node is a extremely...

I prefer the latter :-)

Also, try to avoid the use of "we", "you" , etc. How about:

Reading its cabal.project we will find... ---> In its cabal.project there are a lot of blocks like this:

1129

Either

...by cabal during...
or
...by the cabal tool...

I prefer the former.

1130

Rephrasing:

Unfortunately this makes use of the network after the fetch stage. This is disallow by the ports framework.

1131

We have to arrange these sources in the ports Makefile ourselves ---> These sources need to be listed in the port's Makefile.

1132

... after _the_ usual... not only _the_ USE_CABAL knob...

1147

Remove ","

It might be useful to separate _the_ GH_TUPLE items coming from make-use-cabal _from_ the other ones to make it easy...

documentation/content/en/books/porters-handbook/uses/_index.adoc

197

... the framework _will_ not try...

198

... _are_ present.

218

...value _corresponds_ to...

247

s/Ports/ports.

248

Unclosed _`_ quote at the end.

[arrowd]

Address comments.

[pauamma_gundo.com]

documentation/content/en/books/porters-handbook/special/_index.adoc

967–968

documentation/content/en/books/porters-handbook/uses/_index.adoc

198

I disagree. "if foo and bar are present" but "if foo or bar is present".

218

[pauamma_gundo.com]

A bunch of small nits. I'd also like someone who understands haskell porting to review for accuracy.

documentation/content/en/books/porters-handbook/special/_index.adoc

968–969

Missed it earlier.

1024–1025

One sentence per line.

1047

https://docs.freebsd.org/en/books/fdp-primer/writing-style/#writing-style-guidelines

1116

"a very complex" or "an extremely complex"

documentation/content/en/books/porters-handbook/uses/_index.adoc

195

Or maybe "If hpack is given"

197

As above.

198

I still disagree with fernape.

244

248

249

250

[arrowd]

Address comments.

[fernape]

LGTM.

Gleb please, would you hold a couple of days until @pauamma reviews this again or we call a timeout?

Thanks!

documentation/content/en/books/porters-handbook/uses/_index.adoc

198

I disagree. "if foo and bar are present" but "if foo or bar is present".

Yes, I think you're right. Thanks!

[pauamma_gundo.com]

In D36090#820630, @fernape wrote:

LGTM.

Gleb please, would you hold a couple of days until @pauamma reviews this again or we call a timeout?

Thanks!

There you go!