patches to Handbook ports section: part 3

[linimon]

Summary

This patch adds a section on ports-mgmt/synth, as taken from its pkg-descr. It also adds a table comparing and contrasting poudriere, portupgrade, portmaster, and synth.

[wblock]

chapter.xml

1373

Terms like "newest" quickly become outdated in the Handbook. Maybe just "newer"?

1374

Typo: s/packge/package/

1385

Be consistent in capitalization here. Elsewhere, these are capitalized with <application> tags.

1386

Try to avoid asides, they interrupt the train of thought.

"It is simple to learn and user-friendly, with a limited number of powerful options. It is extremely fast..."

1388

'"drop-in" on' sounds like a visit. Also kind of unusual for non-native speakers. How about just "work on"? (Although I'm not sure that's accurate.)

1390

"Clean" is unclear here. Can be taken to mean different things. Also, "finally safe" kind of disregards poudriere.

1391

"Profile" has not been defined, and "system" is fuzzy, too. I think this is trying to say that the host system is used as a default template for the building of ports.

1392

The way this is laid out kind of suggests that a new jail is the valuable feature. Rearrange, maybe, or maybe just not even mention a jail.

1400

Passive->active: s/will show/shows/

1403

We should be consistent with <application> tags for these names.

1405

Please avoid semicolons, they are usually just sentence splices:
"Synth requires no preparation. It works"

1406

"upon installation" makes it sound like it takes off running as soon as installed, but pretty sure that was not meant.

1410

Shouldn't capitalize "to" here. igor would know for sure.

1418

These are not literal strings, so those tags are not needed. They don't need to be capitalized, either.

1419

Come to that, I'm not certain this paragraph is helping. When someone else edits this, is it still subjective? Or rather, isn't the whole book somewhat subjective?

1427

I think align="left" is the default, but not sure.

1438

Capitalize "Individual".

1440

Probably should add "No dependencies".

1447

This should probably be "Ruby required", same "required" for the later ones.

1457

bapt said there was a way to do config dialogs, but I forget what it was.

1465

Does x86 imply i386 and amd64? I'm not sure.

1469

No blank line here.

1471

No blank line here.

1473

No blank line here, either.

[marino]

first batch, the system isn't letting me comment more than this.

chapter.xml

1373

I agree. Maybe the sentence could be something like "The ports-mgmt/synth utility for upgrading ports was introduced in January, 2016". Maybe dates could be added to the other tools and the reader can calculate relative newness and that won't get obsolete.

1390

poudriere doesn't build on a live system, it has a dedicated jail.
portmaster, portupgrade always use the host system and synth uses the host system by default, but it can also use a dedicated environment like poudriere does. So the "finally safe" comment is correct even with regard to poudriere because it doesn't apply to poudriere.

That being said, maybe there's a better way to say it.

1406

It means it's available for use immediately after installation. I don't think anybody would assume it's launched upon installation because nothing else does that.

1465

yes x86 is understood to mean both i386 and x86_64.

[marino]

remaining comments-to-comments

chapter.xml

1391

Almost. It's saying the default configuration will use the host system to build ports as opposed to a dedicated jail. A profile is a configuration set, and there are unlimited number of profiles possible. This is how one would use synth to build packages for different releases of FreeBSD or even different architectures or even test out new configurations for -CURRENT (e.g. privatize libraries like ncurses or openssl and see the fallout on ports).

1392

What it's trying to say, badly, is that for some people, poudriere's unconditional use of a dedicated jail is a bad thing. They need the packages built on the host environment which is apparently custom. Synth by default uses the host system which is a "pro" for some people, a "con" for others, and a wash for the remaining majority.

[marino]

As a standalone comment, maybe one that doesn't affect documentation:

It's true that Ada is currently available on x86 only.
With a bit of work, and access to an appropriate machine, gcc6-aux could be expanded to ARM platform.
In theory it could be expanded to any of the tier 2 platforms with the possible exception of aarch64.
It's a matter of interest and resources. Bootstrapping a compiler is not trivial so I need some expressed interest and hardware.

It's unclear to mean which T2 are rising and which are falling. (I assume aarch64 is rising but unclear about the rest)

chapter.xml

if (m_head->m_flags & M_VLANTAG) {
                 ndis_8021q_info *rppi_vlan_info;
 
                 rndis_msg_size += RNDIS_VLAN_PPI_SIZE;
                 rppi = hv_set_rppi_data(rndis_mesg, RNDIS_VLAN_PPI_SIZE,
                     ieee_8021q_info);
 
                 rppi_vlan_info = (ndis_8021q_info *)((uint8_t *)rppi +
                     rppi->per_packet_info_offset);
-                rppi_vlan_info->u1.s1.vlan_id =
-                    m_head->m_pkthdr.ether_vtag & 0xfff;
+                rppi_vlan_info->u1.value = NDIS_VLAN_INFO_MAKE(
+                    EVL_VLANOFTAG(m_head->m_pkthdr.ether_vtag),
+                    EVL_PRIOFTAG(m_head->m_pkthdr.ether_vtag),
+                    EVL_CFIOFTAG(m_head->m_pkthdr.ether_vtag));
         }
 
         if (m_head->m_pkthdr.csum_flags & CSUM_TSO) {
                 rndis_tcp_tso_info *tso_info;   
                 struct ether_vlan_header *eh;
                 int ether_len;
 
                 /*