Sort sample Makefile to be more inline with chapter guidelines

[ultima]

Summary

The sample Makefile is a bit out of order. This patch will sort the sample Makefile to be more inline with the following sections of the chapter.

Reviewed by\: lifanov (mentor), matthew (mentor), docguru
Approved by\: lifanov (mentor), matthew (mentor), docguru
Differential Revision\: https://reviews.freebsd.org/DXXXXX

One other thing I would like to point out. The USES and USE_x
chapter doesn't mention anything about variables like
GNU_CONFIGURE and WRKSRC. It maybe a good idea to make it more
clear that this section block is for configuring not just
strictly for USES and USE_x. Another alternative is making a
new section block under the USES and USE_x for the other
configuration variables. The former is probably best.

[ultima]

Combind the two USES as the Makefile should never have two USES variables.

[matthew]

It's mat who does most of the work on the Porter's Handbook.

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

73

This has a different effect than the original code, since in:

USES= gmake
USES= imake

the 2nd line cancels out the first... However, I think your version is more like
what was intended.

[ultima]

• Add USE_GITHUB and GH_* Under USES
• Added OPTION section to the sample Makefile

[ultima]

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

80

Ah, sorry whitespace change isn't relevant

[ultima]

Removed whitespace change

[mat]

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

59

while you are changing this file, s/we no longer accept/we do not accept/

73

No, this, here, is not supposed to be a working Makefile, it is supposed to show what you might want. Using both at the same time, here, is a bad idea. It kinda tells you that you are going to need both, whereas there are only 6 ports using both, out of the 270+ using imake and 4k using gmake.

So I would rather this be kept as it was, two separate bits.

89

maybe add an OPTIONS_SUB=yes here.

[mat]

GNU_CONFIGURE implies USE_CONFIGURE, so it can be kept with the USE_* block. Maybe I'll change GNU_CONFIGURE to USE_CONFIGURE=gnu.

[ultima]

• Changed line 59 as suggested
• Reverted the gmake/imake merge
• Added OPTION_SUB with small comment

[ultima]

• Added new section, Standard bsd.port.mk Variables

[mat]

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

75

should probably add a comment above this to separate it from imake.

98

s/add/change/ or something less terse.

490–492

You should probably add some examples here, this is too vague.

[wblock]

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

52

Let's make these real DocBook callouts so they are not mixed with the actual Makefile contents.
See https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/docbook-markup-block-elements.html#docbook-markup-callouts

73

Maybe this is not a good example any more. If multiple options are to be shown, better to show a couple of complete, working sample Makefiles rather than one that does not work as shown.

490

s/are definable/can be defined/

491

Remove "the", and "belong to" is kind of confusing. "belong in" is a little better, but how is the reader supposed to know where things belong?

[ultima]

Added more details to new section, added callouts but will probably require revision.

[ultima]

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

52

Not sure I completely understand how the callouts work, can you check if this looks correct? If so, should this be done for the rest of the sample Makefile?

118

I think the callout list is supposed to be under the programlisting, but I'm not sure what this block should be, or is this correct?

490–492

I think this section is looking much better now!

[mat]

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

73

It never was a good example, it tells you what kind of stuff you can put in the Makefile, and where, but it never was a working example of what to do exactly.
I am not sure it makes sense to have multiple examples either, they would probably get outdated fast.

[ultima]

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

73

If this samples [ ]comments are all converted to callouts, combining the USES and adding a call out next to them will make it easily understood that they they are for a specific purpose. I think the callout suggestion is a good idea, I am worried though that in the end there will be so many callouts that this sample won't look so great.

[mat]

(please, pkg install docproj and run make in that directory to make sure it builds)

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

52

The ref is co-patch-dist-strip.

115

Either <literal>${WRKSRC}</literal> or <filename>${WRKSRC}</filename>

Also, at the end, it should be </para>

118

It won't build with the calloutlist inside the programlisting.

487

dupplicated id.

[mat]

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

52

Well, if all the [...] go into callouts, the page will be unreadable, there will be 20+ callouts, and people will keep scrolling up and down to figure out what means what.

[ultima]

Removed Removed calloutlist bits. While I like this idea, I would rather a docs committer make these changes. I also feel that the page maybe harder to read as a result, going to leave this out of the commit.

I also created a patch and added it to misc/freebsd-doc-en to build for QA. I'm not familiar with proper QA for docs, but after creating the patch and adding it in files/patch-file.diff, it builds correctly.

[mat]

en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml

496–497

Move the replaceable bits inside varname.

498

Please remove the evil PORTDATA, we want to remove it.

[ultima]

• Corrected varname open/close
• Slayed a spawn of Evil

[mat]

Looks ok to me.

Do make sure it builds. (pkg install docproj, and run make in the porters-handbook directory)

[matthew]

Approved, subject to running the build test mat specified.

[ultima]

The build Doesn't have any errors, a single warning, but it is irrelevant to this patch, built in poudriere.

Warning: Object directory not changed from original /root/doc/en_US.ISO8859-1/books/porters-handbook