Update porter's handbook for USES=xorg

[zeising]

Summary

Update porters handbook for USES=xorg and USES=xorg-cat, currently WIP in https://reviews.freebsd.org/D20724 .

[mat]

Could you also add documentation for USES=xorg-cat?

[zeising]

In D20732#448815, @mat wrote:

Could you also add documentation for USES=xorg-cat?

I purposefully omitted it, since it is supposed to be internal to xorg ports, not used by other ports, similar to qt-dist.mk.

[mat]

In D20732#448816, @zeising wrote:

In D20732#448815, @mat wrote:

Could you also add documentation for USES=xorg-cat?

I purposefully omitted it, since it is supposed to be internal to xorg ports, not used by other ports, similar to qt-dist.mk.

Mmmm, I do not understand, you mean I'll have to document it myself when the other review hits the tree? All USES have to be documented, otherwise, the only one who knows how it works is you, so, the bus factor is 1, and it is very bad.

[zeising]

In D20732#448839, @mat wrote:

In D20732#448816, @zeising wrote:

In D20732#448815, @mat wrote:

Could you also add documentation for USES=xorg-cat?

I purposefully omitted it, since it is supposed to be internal to xorg ports, not used by other ports, similar to qt-dist.mk.

Mmmm, I do not understand, you mean I'll have to document it myself when the other review hits the tree? All USES have to be documented, otherwise, the only one who knows how it works is you, so, the bus factor is 1, and it is very bad.

I thought the porter's handbook was for external facing things, so to speak. xorg-cat is meant to be only for xorg ports (ports coming from freedesktop.org), and not for general consumption. I have no problem adding it to the handbook, but since other similar things, such as qt-dist.mk, wasn't documented, I thought this was the way to do it. the previous XORG_CAT isn't documented anywhere, as far as I can tell.

[mat]

In D20732#448849, @zeising wrote:

I thought the porter's handbook was for external facing things, so to speak. xorg-cat is meant to be only for xorg ports (ports coming from freedesktop.org), and not for general consumption. I have no problem adding it to the handbook, but since other similar things, such as qt-dist.mk, wasn't documented, I thought this was the way to do it. the previous XORG_CAT isn't documented anywhere, as far as I can tell.

The Porter's Handbook is for porters. The xorg ports are ports written and updated by porters, so it needs to be documented. The only things that are not in the Porter's Handbook and that are in the Committer's Guide's Ports section are procedures that only committers needs. qt-dist being undocumented is most probably an oversight.

[zeising]

Update patch, add documentation for USES=xorg-cat as well.

[mat]

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

6554 ↗

(On Diff #59500)

That line should happen before USE_MYSQL.

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

1559 ↗

(On Diff #59500)

Probably needs to reword the title here.

1561 ↗

(On Diff #59500)

missing xorg here.

1590 ↗

(On Diff #59500)

Probably needs USES=xorg here.

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

3450 ↗

(On Diff #59500)

Put x.org in an <application> tag.

3762 ↗

(On Diff #59500)

Extra > at the end of the sentence.

3767–3768 ↗

(On Diff #59500)

Remove but.

[zeising]

Updates based on comments from @mat