makeman: add a comment describing purpose and invocation

[emaste]

tools/build/options/makeman

12

s/it //

[ngie]

tools/build/options/makeman

4

Why remove this line?

9

"of the" sounds a bit strange. "with the" seems a tad more natural.

[emaste]

tools/build/options/makeman

4

Seemed like unnecessary whitespace with the longer comments below, and to group it into a header/copyright block.

9

I think "knob of the same name" is perfectly cromulent by itself, but "of the ... of the" does seem awkward. Will change.

[ngie]

tools/build/options/makeman

4

Ah, ok..

9

Thanks :)!

[jhb]

This is helpful, though I think it would also be useful if the comments at the top of src.conf.5 pointed back to makeman somehow (as otherwise if you are looking at src.conf.5 you wouldn't know to even look in tools/build/options). I still think having a 'make' shortcut in share/man/man5/Makefile ala 'make sysent' in sys/kern/Makefile would be most helpful. 'make src.conf.5' would be nice if you could trick make into only running it explicitly and never implicitly (e.g. never during buildworld)

[emaste]

add a reference to the tool that creates the doc

[jhb]

Thanks

[wblock]

head/tools/build/options/makeman

6 ↗

(On Diff #27555)

Passive -> active: s/is used to create/creates/
The comma is not needed.

11 ↗

(On Diff #27555)

This script invoices 'make showconfig' for each option on each supported architecture
to determine whether the default setting is always

[emaste]

head/tools/build/options/makeman

11 ↗

(On Diff #27555)

This is incorrect, since it does not invoke 'make showconfig' (options * architectures) times, it is invoked once per architecture. Maybe invokes 'make showconfig' to determine, for each option on each supported architecture, whether the default setting is always?

Or, "For each option on each supported architecture this script determines whether" (omitting mention of "make showconfig"). I think there's some value in referencing the use of make showconfig (to understand what information the script is actually using), but maybe folks can just look at the script to see how it works if they care.

[wblock]

head/tools/build/options/makeman

11 ↗

(On Diff #27555)

Agreed about the value of showing specifically what it does, since this script is... dense.

Oh, and I wrote "invoices". Sorry about that.

For each supported architecture, 'make showconfig' is invoked for each option to