Page MenuHomeFreeBSD

Update porter's handbook for USES=xorg
ClosedPublic

Authored by zeising on Jun 23 2019, 9:15 PM.

Details

Summary

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

Diff Detail

Repository
rD FreeBSD doc repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

zeising created this revision.Jun 23 2019, 9:15 PM
mat added a comment.Jun 25 2019, 2:34 PM

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

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 added a comment.Jun 25 2019, 2:56 PM
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.

In D20732#448839, @mat 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 added a comment.Jun 26 2019, 11:40 AM

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 updated this revision to Diff 59500.Jul 7 2019, 10:33 AM
zeising edited the summary of this revision. (Show Details)
zeising added a reviewer: bcr.

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

mat added inline comments.Jul 8 2019, 2:57 PM
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 updated this revision to Diff 59547.Jul 8 2019, 7:54 PM
zeising marked 7 inline comments as done.

Updates based on comments from @mat

mat accepted this revision.Aug 13 2019, 12:49 PM
This revision is now accepted and ready to land.Aug 13 2019, 12:49 PM
This revision was automatically updated to reflect the committed changes.