Create GNOME porters handbook chapter.

[kwm]

Summary

Create USE_GNOME chapter for the porters handbook. This has 2 chapters, one basic chapter explaining the macro's and one chapter with all the components.

Loosely based on the old porting guide (http://freebsd.org/gnome) and the Qt chapter.

Live version of the patch (with updates as the patch get reviewed fixes) http://rainbow-runner.nl/freebsd-doc/en_US.ISO8859-1/books/porters-handbook/using-gnome.html

[wblock]

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

1407 ↗

(On Diff #8514)

Passive->active:
s/will explain/explains/

1416 ↗

(On Diff #8514)

Passive->active:
s/will cause/causes/

1432 ↗

(On Diff #8514)

s/the following/these/

1433 ↗

(On Diff #8514)

Looks like a tab hiding in there before "If".

1438 ↗

(On Diff #8514)

"above" seems unnecessary.

1440 ↗

(On Diff #8514)

If the destination is in the same document, just use <xref linkend="gnome-components"/>.
If that really is a link to another document, it needs more of a URL.

1446 ↗

(On Diff #8514)

"tricks" implies these are not standard methods. How about "techniques"?

1447 ↗

(On Diff #8514)

s/your own/new/

1473 ↗

(On Diff #8514)

s/dependacies/dependencies/

1501 ↗

(On Diff #8514)

Add a comma after "applications".

1501 ↗

(On Diff #8514)

Isn't it Qt (lowercase "T"), and an application name? That would be <application>Qt</application>.

1504 ↗

(On Diff #8514)

Address comment, or remove. Ideally, add a link to the place that describes how Qt applications are handled.

1618 ↗

(On Diff #8514)

<para>The <quote>Implies</quote> column

1620 ↗

(On Diff #8514)

s/components/component/
s/arguments/arguments,/
s/it listed/they are listed/

1621 ↗

(On Diff #8514)

<literal> around the parentheses.

For the second sentence, just

The first is the default.

1622 ↗

(On Diff #8514)

s/used/shown/
s/adding to/adding to both/

1623 ↗

(On Diff #8514)

s/dependency/dependencies/

1637 ↗

(On Diff #8514)

Need a blank line between thead and tbody elements.

1644 ↗

(On Diff #8514)

Need a blank line between row elements. Also below.

1666 ↗

(On Diff #8514)

Probably easier to read with spaces after the commas. (Also in later entries.)

(both, build, run)

1897 ↗

(On Diff #8514)

Capitalize:

<title>GNOME Macro Components</title>

1909 ↗

(On Diff #8514)

There can be more than one thing meant by "configure", but I think this the individual port's configure target. So use <buildtarget> tags on it.

2222 ↗

(On Diff #8514)

I would change the tense of all of these sentences to say that it was used for that, but not have any in the present tense.

<entry>Deprecated, do not use.  Was used to check if a
component was installed.  This was used for ports that did not have
<literal>--enable</literal>/<literal>--disable</literal>
switches for their configure script.  But the building of
parts of a port without an implicit request is
discouraged.</entry>

It would be good to mention why this is no longer needed (like the next entry) or what to use in its place.

[kwm]

Process wblock suggestions, except the last one.

[kwm]

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

2222 ↗

(On Diff #8523)

I think I get what you mean, but I think I need some time before I can get my head around how to do this.

[wblock]

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

1620 ↗

(On Diff #8523)

Missing an "is":
s/first the/first is the/

2222 ↗

(On Diff #8523)

It might be that there is just no need for it any more. But when you tell the reader "don't do this any more", the natural question they will have is "what should I do instead?"

[mat]

Also, note that this currently does not build, because of the xref with content.

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

1427 ↗

(On Diff #8523)

maybe:

<literal>BUILD</literal>/<literal>LIB</literal>/<literal>RUN</literal>

or:

build-time, run-time, or libraries dependencies

1436 ↗

(On Diff #8523)

add a tabulation between = and gtk30

1438–1439 ↗

(On Diff #8523)

The <varname>USE_GNOME</varname> components will automatically add the dependencies they need.

(note that components is plural here)

1440 ↗

(On Diff #8523)

An xref must be empty, so, remove "the" and the content of the tag, it'll end up looking like: "Please see section x.y.z, <it's title>".
Also, it's linkend not linked.

1441 ↗

(On Diff #8523)

for an exhaustive list of (full already implies all, and exhaustive is more correct than full)

1442–1443 ↗

(On Diff #8523)

and their dependencies

1474–1477 ↗

(On Diff #8523)

You should drop the part about bsd.port.options.mk, everything is supposed to be doable after bsd.port.options.mk, just say cannot be set after including bsd.port.pre.mk.

1484 ↗

(On Diff #8523)

missing something like is at the end.

1485 ↗

(On Diff #8523)

You should use an <xref linkend="blah"/> to reference the next section, if they get moved around, it'll still be correct.

1494 ↗

(On Diff #8523)

<application>GTK+</application>, <application>Freedesktop</application>

1501 ↗

(On Diff #8523)

Same here, an xref must be empty, you should remove the xref, and replace acronym with application, I think.

1619 ↗

(On Diff #8523)

they are listed between parenthesis in the

1632 ↗

(On Diff #8523)

I'm wondering if the Implies column is a good idea. A port must always list all the components it needs, it must not assume some component will be brought in by some other component, as this can change, and break stuff.

2249 ↗

(On Diff #8523)

Any reason that is not in the deprecated section below ?

[wblock]

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

1427 ↗

(On Diff #8523)

The second is somewhat more readable. That should be

build-time, run-time, or library dependencies

1438–1439 ↗

(On Diff #8523)

Can eliminate "The" and "will":

<varname>USE_GNOME</varname> components automatically add the dependencies they need.

1441 ↗

(On Diff #8523)

We can make it simpler and shorter:

Please see <xref linkend="gnome-components"/> for the list of

1442–1443 ↗

(On Diff #8523)

Nice!

1484 ↗

(On Diff #8523)

This section explains the macros that are available and how they are used.

[kwm]

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

1632 ↗

(On Diff #8523)

I see your point, I still think it is a good idea. For the reason that you don't have to set glib20 if you have gtk30 already on the list. The users don't know this unless they dive into bsd.gnome.mk. If changes happen, like the recent librsvg2 change, then user needs to be tested anyway. And most of this stuff will not change.

[mat]

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

1632 ↗

(On Diff #8523)

• if the software you're porting only needs gtk30, then it doesn't need to know that gtk30 will bring glib20.
• if the software you're porting needs glib20 and gtk30, then you put both, and the fact that gtk30 also needs glib20 is of no matter, as your software needs it anyway.

[kwm]

Drop Implied colom from the tables. Some more small fixes.

[mat]

Looks good, have a look at what igor thinks about it (igor -R en_US.ISO8859-1/books/porters-handbook/special/chapter.xml) and when igor's happy about the changes you made, test build and commit :-)

[kwm]

Igor fixes, two issues left:

chapter.xml:1477:bad phrase: <varname>USE_GNOME</varname> can not be set after
chapter.xml:1920:bad tag indent: </row>

I don't see whats wrong with line 1477, and I have no idea what igor sees
wrong with line 1920.

Also the intro text of the gnome components page, I merged the para's
together because igor was yapping about that too :)

[mat]

In D3577#75937, @kwm wrote:

Igor fixes, two issues left:

chapter.xml:1477:bad phrase: <varname>USE_GNOME</varname> can not be set after
chapter.xml:1920:bad tag indent: </row>

I don't see whats wrong with line 1477, and I have no idea what igor sees
wrong with line 1920.

Huhu, for 1477, tricky, running igor -R (outputs colors telling you where what is wrong is) helps, s/can not/cannot/, and as for 1920, well, the dev version of igor I have doesn't say anything about it, @wblock may have fixed a bug in igor :-)

Also the intro text of the gnome components page, I merged the para's
together because igor was yapping about that too :)

If you mean you splitted it, yes :-)