I clearly shouldn't review things when I'm tired. Sorry. :(

Seems like an excellent idea.

I don't really have time for this right now, so someone else can go ahead and commit it once it's been accepted.

In D30589#687207, @imp wrote:

I don't like the passive voice, due to forced conditioning in high school Freshman English.... however, I know that's the style here...

The documentation team prefers to avoid use of 'you' in the handbook (and any other documentation).

Have you tested with textproc/igor and mandoc -T lint?

In D30336#681311, @a.wolk_fudosecurity.com wrote:

Updated the raw diff using the git show -U999999 <commit-hash> > change.diff method. Hope that helps! :)

Address feedback by 0mp

The current diff you've uploaded lacks context for Phabricator to tell which part of the file it applies to (I don't know why Phabricator can't always figure out the context), which is why the "Context not available" message appears.

Yes, it would be good to have a documented method of checking the protected flag, so go ahead and add that.

Fix cross reference

Address feedback by ceri

In D30330#681159, @ceri wrote:

One last nit, sorry - could you sort these alphabetically, with _limits and _login_class above _nice and _oomprotect after it?

Address feedback by ceri and Adam Wolk

In D30330#681137, @a.wolk_fudosecurity.com wrote:

I found out the hard way, that an rc script overriding start_cmd ignores some mechanisms. This may be by design. Those ignored are at the least:

• _oomprotect
• _user
• _limits
• _fib
• _chdir
• _nice

Unfortunately, some ports like PostgreSQL redefine start_cmd which would make _oomprotect="ALL" silently not work for the database. I am not sure where it would be a good place, but I think it would be worthwhile to document that redefining ${name}_cmd has such a pitfall.

Looks good to me, let's get this commited.

I think it would be better to check for the individual component parts, as @ygy suggests, and if any of them aren't found, recommend installing ports/textproc/docproj - but only print the error message once, even if multiple dependencies aren't found.

[source,shell] would indicate that a particular section using monospaced blocked text is a shell script.

@dbaio Since it has been approved by a ports commiter (you), doceng (bcr), and a doc commiter (me), can I go ahead and commit this to the ports tree, or do you want to?

I will note that PDF is mentioned as an optional part in the FDP quickstart, but I don't think it's going worth holding up the review over this.

Yes please!

Adding a bunch of spaces doesn't need much approval, but have some anyway. :)

Only one tiny nit left, then you can go ahead and commit it with Approved by: debdrup

Looks good to me now, go ahead and commit with Approved by: debdrup

Looks good to me. :)

In D28609#658423, @driesm.michiels_gmail.com wrote:

I don't understand why the legacy docs are still there. They are not kept up to date as far as I can tell.

Looks good to me.

The patch doesn't apply cleanly for me, and it doesn't look like a trivial fix.

The only thing I'd note is that [source,bash] should be [source,shell].

I would also suggest adding a link to https://wiki.freebsd.org/IRC/Cloaks, as that explains the requirements, et cetera.

Once you've tested that it looks good, with make -C /usr/doc/documentation (run|build), you're welcome to go ahead and commit this. :)

In D29278#655642, @jhb wrote:

Honestly, I had written most of the next change using the old syntax and then saw this in some new changes when I rebased. I already had in my mind to ask for a shorter syntax as the old one is pretty verbose, especially compared to the old SGML entities we had for DocBook. The man: keyword is quite nice though and is as compact as the old style.

Can you find a commit hash for this changed behaviour?

Nevermind, just after I wrote that, I remembered something.
It's implemented using doc/shared/lib/ManPageMacro/extension.rb

In D29278#655590, @emaste wrote:

I'm not an asciidoc expert, do we have some local docs for these?

I'm unsure about inlining commit hashes or revisions, so I think @gjb will have to weigh in on whether commit hashes should be referenced at the end like it's done with other things mentioned in the release notes.
I'm more partial to this, as this is how release notes have always looked, but I'm not against the change, as long as it's uniform across the whole document.

The author of the feature has added D29275 which was being worked on before this review started?
So it seems like this has been overcome by events.

I would also highly recommend adding some commit hashes.
If my memory serves, several of the commits involved have information that's relevant in configuring these new features.

In D29244#654741, @gjb wrote:

Lack of help, in addition to my infamiliarity with asciidoc/hugo, ... well, I am only one person.

Looks good to me!

I'll happily give approval for this from docs if it helps this commited.
It's much easier to remember one port than a handful (or having to look them up in the FDP).

Looks good to me.

Looks good to me now, let's get this landed.

I've rephrased it a bit, to avoid multiple sentences which rendered as separate lines when built.

More to the point, adding a few lines is not going to waste peoples diskspace as much as you think, as manual pages are compressed when installed.

My point is that if that's what this change does, it's not evident that that's what it does.

After talking it over on IRC, I think this needs little more descriptive information as to what the options in the config files do.

I was only going to remark on the gitrepo thing, but that's already had multiple layers of paint, so I shan't belabor the point.

In D28882#647597, @lwhsu wrote:

I mean, we should do this: https://cgit.freebsd.org/src/commit/?id=655fa04406010e56822802e12bf52f42e333988b to fix in a better way.

Also, what stands for VTI? virtual interface? It's non-trivial to me and maybe we can have its full name?

In D28882#647493, @lwhsu wrote:

I somehow feel the better fix is creating if_wg MLINK.

Address feeeback by @yuripv and @brueffer

Rework review to address outstanding issues with examples

It's possible Phabricator mangled things.