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.
Tags
None
Referenced Files
Unknown Object (File)
Jan 6 2024, 5:23 AM
Unknown Object (File)
Jan 3 2024, 5:11 PM
Unknown Object (File)
Dec 20 2023, 1:45 AM
Unknown Object (File)
Dec 13 2023, 10:59 PM
Unknown Object (File)
Dec 8 2023, 1:55 PM
Unknown Object (File)
Nov 18 2023, 9:10 AM
Unknown Object (File)
Nov 18 2023, 5:45 AM
Unknown Object (File)
Nov 18 2023, 3:28 AM
Subscribers

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 - subversion
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

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 - subversion.

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.

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.

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.

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.

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 :-)

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 set the repository for this revision to rD FreeBSD doc repository - subversion.

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 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".

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.

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.
  • 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
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

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.