Page MenuHomeFreeBSD

Bring Porters Handbook up to date and fix small errors. CH 5
ClosedPublic

Authored by ak on Oct 27 2014, 8:48 PM.

Details

Summary
  • Fix indentation for some programlisting blocks
  • Specify that PORTREVISION should be removed after PORTVERSION bump (ignore master port case as specific)
  • Replace 'gzipped' with compressed
  • Remove phrase about 'automatically determining of closet master site...', it was in planing phase for more than 15 years
  • Remove reference to DATA option
  • Mention @(owner,group,mode) operator in '5.15.1. INSTALL_* Macros' paragraph

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

ak updated this revision to Diff 2129.Oct 27 2014, 8:48 PM
ak retitled this revision from to Bring Porters Handbook up to date and fix small errors. CH 5.
ak updated this object.
ak edited the test plan for this revision. (Show Details)
ak added reviewers: portmgr, doceng.
ak set the repository for this revision to rD FreeBSD doc repository.
mat added a subscriber: mat.Oct 27 2014, 11:14 PM

Am I the one who has fucked up all those <programlisting> indentations ?

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
28 ↗(On Diff #2129)

the example is a gzip'ed tarball.

291 ↗(On Diff #2129)

or removed was *right* you can reset it to 0.

1393–1394 ↗(On Diff #2129)

I see no real reason to remove this.

2682 ↗(On Diff #2129)

filename is not the right tag.

4655 ↗(On Diff #2129)

maybe by the <literal>EXAMPLES</literal> option.

gjb added a subscriber: gjb.Oct 28 2014, 3:52 AM

Is there a reason doceng@ is added, instead of a more wider audience?

I see no reason for doceng@ to be involved in review of such a trivial change.

gjb removed a subscriber: gjb.Oct 28 2014, 3:53 AM
ak added a comment.Oct 28 2014, 5:48 AM

Is there a reason doceng@ is added, instead of a more wider audience?
I see no reason for doceng@ to be involved in review of such a trivial change.

I apologize, someone recommended me to add doceng@ as reviewer for handbook.

ak added a comment.Oct 28 2014, 6:11 AM

28 the example is a gzip'ed tarball.

Yes, but I think that equate 'standard compressed tarball' to the tar.gz is too narrow.
Sure, it's still most popular format in the ports tree, but tar.bz2 and tar.xz represent a significant percentage of distfiles too. I think they also can be called an 'standard compressed tarball'.

291 or removed was *right* you can reset it to 0.

Usually PORTREVISION removed after PORTVERSION bump, unless its slave/masterport case.
Perhaps this phrase should be reworded:
"PORTREVISION is removed from the Makefile (which implicitly reset it to 0)."

1393–1394 I see no real reason to remove this.

Why keep remark about future plans, especially if they're 15+ years old future plans?

2682 filename is not the right tag.

Right, I've wondered about that too, but decided that there was some reason for this. So, change it to <link> then?

4655 maybe by the <literal>EXAMPLES</literal> option.

Ok.

mat added a comment.Oct 28 2014, 8:08 AM
In D1017#9, @ak wrote:

Is there a reason doceng@ is added, instead of a more wider audience?
I see no reason for doceng@ to be involved in review of such a trivial change.

I apologize, someone recommended me to add doceng@ as reviewer for handbook.

I think someone ment doc and not doceng :-)

mat added a comment.Oct 28 2014, 8:15 AM
In D1017#10, @ak wrote:

28 the example is a gzip'ed tarball.

Yes, but I think that equate 'standard compressed tarball' to the tar.gz is too narrow.
Sure, it's still most popular format in the ports tree, but tar.bz2 and tar.xz represent a significant percentage of distfiles too. I think they also can be called an 'standard compressed tarball'.

Well, compress(1) is also the old compressor, so, nothing is perfect :-)

291 or removed was *right* you can reset it to 0.

Usually PORTREVISION removed after PORTVERSION bump, unless its slave/masterport case.
Perhaps this phrase should be reworded:
"PORTREVISION is removed from the Makefile (which implicitly reset it to 0)."

Usually, yes, but people prefer to keep it with a 0 value, there are currently 343 ports with PORTREVISION=0, it's non negligeable, so I don't see the point of this change.

1393–1394 I see no real reason to remove this.

Why keep remark about future plans, especially if they're 15+ years old future plans?

Nothing in what I quoted talks about future plans.

2682 filename is not the right tag.

Right, I've wondered about that too, but decided that there was some reason for this. So, change it to <link> then?

I don't know what would be better, <link xlink:href="....">...</link> or something else.

ak removed a reviewer: doceng.Oct 28 2014, 8:26 AM
ak set the repository for this revision to rD FreeBSD doc repository.
ak added a comment.Oct 28 2014, 8:52 AM

I think someone ment doc and not doceng :-)

Doh. Fixed, sorry for the inconvenience.

28 the example is a gzip'ed tarball.

Yes, but I think that equate 'standard compressed tarball' to the tar.gz is too narrow.
Sure, it's still most popular format in the ports tree, but tar.bz2 and tar.xz represent a significant percentage of distfiles too. I think they also can be called an 'standard compressed tarball'.

Well, compress(1) is also the old compressor, so, nothing is perfect :-)

Ironically, it's quite rare nowadays, only ~100 distfiles in the ports.
I would like to keep this change if you don't mind.

Usually PORTREVISION removed after PORTVERSION bump, unless its slave/masterport case.
Perhaps this phrase should be reworded:
"PORTREVISION is removed from the Makefile (which implicitly reset it to 0)."

Usually, yes, but people prefer to keep it with a 0 value, there are currently 343 ports with PORTREVISION=0, it's non negligeable, so I don't see the point of this change.

Perhaps "PORTREVISION is usually removed from..."
But, I don't have strong opinion about this, so I'll remove this change.

Nothing in what I quoted talks about future plans.

Ah. Took me a minute to understand.
Good catch! It seems that I forgot to document this change.
I think that there is no need to justify that putting port in a wrong category is the bad thing. Especially with a silly argument like 'bloat in the master source repository'. I think this phrase is a leftover from cvs times.

2682 filename is not the right tag.

Right, I've wondered about that too, but decided that there was some reason for this. So, change it to <link> then?

I don't know what would be better, <link xlink:href="....">...</link> or something else.

Hmm, I'm not a docbook expert, what other options are there?

wblock added a subscriber: wblock.Oct 28 2014, 10:40 PM
wblock added inline comments.
en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
28 ↗(On Diff #2129)

Yes, but not all distfiles are compressed the same way. The more general "compressed" covers lots of variations.

(Sorry, I can't see ak's comments inline. Phabricator strikes again.)

291 ↗(On Diff #2129)

This can be expanded, and the aside removed:

Since it is a new vendor release of the code, <varname>PORTREVISION</varname> is reset to <literal>0</literal>. When this happens, <varname>PORTREVISION</varname> should usually be removed from the <filename>Makefile</filename> entirely.

1393–1394 ↗(On Diff #2129)

I agree that it's probably a leftover from CVS. More importantly, it's a distraction from the main point, which is to get a port in the right category the first time.

2682 ↗(On Diff #2129)
3421 ↗(On Diff #2129)

Use <replaceable>...other code...</replaceable> or something like it. The square brackets look like they are supposed to be typed.

4655 ↗(On Diff #2129)

Yes, add "the".

mat added inline comments.Oct 30 2014, 12:57 PM
en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
28 ↗(On Diff #2129)

he did not comment inline, using some trick I don't know about, which does not help in our case.

ak added a comment.Nov 1 2014, 3:32 PM

So, what is the consensus about:

  • gzip to compressed(term, not compress(1)) change
  • clarification of PORTREVISION reset. I'm agree with wblock's suggestion.
  • Removal 'repo churn' phrase.
ak updated this revision to Diff 33886.Oct 11 2017, 1:34 PM
  • Remove phrase 'bloat in the master source repository' as a leftover from the cvs times
  • Remove phrase about 'automatically determining of closet master site...', it was in planing phase for more than 15 years
  • Replace 'gzipped' with compressed when appropriate
  • Update url for backup master site
  • Fix typo: s/otn/from/
  • Remove reference to DATA option
mat added inline comments.Oct 13 2017, 11:49 AM
head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
3675

https

ak marked an inline comment as done.Oct 13 2017, 12:38 PM
ak added inline comments.
head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
3675

I left http because right now https is broken:

$fetch https://distcache.freebsd.org/FreeBSD:12:amd64/latest/digests.txz
SSL certificate subject doesn't match host distcache.freebsd.org
fetch: https://distcache.freebsd.org/FreeBSD:12:amd64/latest/digests.txz: Authentication error

mat accepted this revision.Oct 13 2017, 1:48 PM

In the future, could you use devel/arcanist, or at least generate a diff with full context like it does, with svn diff -x -U9999 or git diff -U9999.

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

Oh, yes, distcache is http only, sorry about that, I thought it was https.

This revision is now accepted and ready to land.Oct 13 2017, 1:48 PM
This revision was automatically updated to reflect the committed changes.
ak marked an inline comment as done.