Should we use filtered and unfiltered, or some other descriptive title? Using legacy as a name instead of an adjective gets a bit confusing, and doesn't age well if it's still around when a third idea comes out.

Should we use RFC style language to improve semantic density?

Does it make sense to put numbered examples in an EXAMPLES section?

Putting macros in titles is discouraged per mdoc(7)

i'm open to other names for the "legacy" bridge configuration, but i'm not sure "unfiltered" really works: an "unfiltered bridge" is not a thing anyone knows about, so it's not very descriptive. "legacy" at least implies "this is the old way of doing it".

i would be open to something like "basic bridge" and "VLAN filtering bridge", except i don't really like "basic bridge", but perhaps there's another word we could use here?

unless we use that language in other manual pages (which i don't think we do?) i don't think that is more clear.

i thought about this and i really prefer having examples inline here, rather than referring to the EXAMPLES section, because it makes it easier for the reader to understand what's going on. trying to explain the configuration without being able to show actual ifconfig commands is quite difficult and ends up being more verbose and less explanatory, at least in my experience. but i'm open to other ways of doing this if you have a better suggestion.

noted, but then what is the preferred formatting here?

note to self: typo, "a separate STP instances"

I do not have any alternative names to propose but I think almost anything is better than legacy almost all the time.

Consider using an appositive instead of nested parentheticals. I think appositives always read more clearly than parentheticals, and especially nested parentheticals.

Titles shouldn't have cross-references. I'm not sure I understand this clearly, maybe not because of your writing but just because I'm not a network engineer, but maybe something like "Configuring VLAN-aware bridges" or
"Understanding bridge VLAN capture"?

Also consider using an appositive.

Almost all of this is well over my head except DMZ. Afaik DMZ is the first thing they teach you about networking.

since we never use the acronym again i've just removed it, and we can also remove "sometimes called" since this term comes from 802.1Q, so it's always called that.

this section is about a specific interaction between bridge(4) and vlan(4) in FreeBSD, not about VLANs in general, so i think that should be reflected in the title. i've changed it to use "if_bridge and if_vlan" to make that a bit more clear without using Xr.

the wording here was redundant, so i've changed it to simply say what it meant.

i think anyone reading this will know what a DMZ is, but that's a detail that isn't actually relevant to the example, so i've reworded it to talk about "isolated networks" instead.

I believe this is supposed to defuntagged 100 to match the vlan ID below? I hope I understand correctly.

correct, i will fix this prior to landing

I don't like "previous" here without a reference first (previous to what?). Maybe "releases prior to 15.0" or maybe describe filtering first and legacy second?

Will it become the default in the future?

i was thinking "previous to this release", but i suppose that won't be true when someone is reading this manual page in FreeBSD 20.0.

the reason i wrote it this way around is because (at least technically) the vlan filtering bridge is just the same bridge with some extra features, so it felt reasonable to describe the shared features first then describe the extra features. however maybe this isn't the best way to present it to users... if we want users to use the vlan filtering bridge, we could describe that first, then have a short section on the legacy bridge that describes what you can't do and what you might want to do instead (e.g., vlan(4) in a bridge).

hard to say. i would like to make "vlanfilter defuntagged 1" the default at some point, but this means people would have to configure IP addresses on bridge0.1 instead of bridge0 and i expect a large amount of push-back on that (as we saw with member_ifaddrs) so it may end up being easier to leave things as they are but recommend people use the new setup.

Yeah, that's exactly what I was thinking of. We have lots of "new" and "ng" and such which stop being new but don't lose the name - things like newbus. Maybe it's fine here though because it does go on to explain where the new mode arrived.

what gives me pause is that it feels strange to describe an optional feature, then describe the default behaviour in a footnote... if we had consensus that vlanfilter will become the default, that would be fine, but otherwise it feels backwards.

i can't land this anyway until some other changes have gone in (particularly D51600) so i'll have a think in the mean time and maybe do another pass of the manpage before landing it.

We have lots of "new" and "ng" and such which stop being new but don't lose the name - things like newbus.

Yes this is very bad and renaming things after the fact is harder than finding a decent name for them. New/ng/legacy as names really makes me sad, because it is broken and we will never fix it.

the difference is that "newbus" is no longer the new bus, it's just the bus, whereas the legacy bridge will always be the legacy bridge (at least until we remove it... but i have no plans for that). a better comparison would be if i'd named these "bridge" and "new bridge", but, anticipating, this problem, i did not :-)

How about using active voice here:
"..., it is recommended to assign all traffice to a VLAN ..."