Fix handbook instructions for manuallying installing a jail

[allanjude]

Summary

Requested as https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=194993

Remove the unneeded subshell
Remove the GAMES set as it no longer exists in newer versions
Remove the DOCS set as it may be removed in the future, and contains little of value

Fix all of the csh examples, which were invalid (foreach terminates with "end", not "done" like in sh)

[wblock]

en_US.ISO8859-1/books/handbook/jails/chapter.xml

246

Why are we even showing csh versions? Too many examples are needed for the different versions of FreeBSD, and showing csh versions doubles that.

Given that they did not (could not) work, and nobody complained, I suggest they can be safely removed.

[allanjude]

In D2116#3, @wblock wrote:

Why are we even showing csh versions? Too many examples are needed for the different versions of FreeBSD, and showing csh versions doubles that.

Given that they did not (could not) work, and nobody complained, I suggest they can be safely removed.

csh is the default root shell. So if someone is logged in as root and trying to do something, it will be in csh

I would say we might want to change the order, to put csh first

Also, maybe we want to do like we did for the installation chapter, and do separate sections for 8.x and 9.x+, so they are completely separate, instead of interspersed

[bcr]

Can't we just wait until the EoL of the 8.x branch (June 30, 2015) leaving everything as it is? Then we just remove the 8.x stuff and use the 9.x descriptions, which are valid for 10 also. I would only do minor updates to that section until then.

[wblock]

I agree with bcr, the 8.x versions can age out. They could probably be removed now.

The instructions are explicit about which shell is used. I suggest we just remove that and show a sh version that explicitly invokes sh. There is no question which is used, and it works regardless of which shell is used interactively.

[allanjude]

Remove csh examples

Convert remaining examples to explicitly use sh

[allanjude]

Clean up some more, remove remnants of references to using different shells, and fix up the stopping a jail section

[wblock]

en_US.ISO8859-1/books/handbook/jails/chapter.xml

375

Needs a "the" before "jail". It would be better to rearrange this sentence to avoid the pause in the middle, and it does not really explain why the jail ID is needed. <replaceable> is supposed to be replaced by the user, so it does not seem like the right usage in the text (correct in the command, though). Maybe <varname> as shown in the output?

Jails can be shut down with &man.jexec.8;. Use &man.jls.8; to identify the jail's <varname>JID</varname>s, then use &man.jexec.8; to run the shutdown script in that jail.

[allanjude]

Update with feedback from wblock

[allanjude]

is this ready to land now?

[bcr]

en_US.ISO8859-1/books/handbook/jails/chapter.xml

210

Is it really an sh shell or rather a sh shell? I'd connect the two words like this: sh-shell

[allanjude]

en_US.ISO8859-1/books/handbook/jails/chapter.xml

210

that is actually kind of a tough question. It depends of you pronounce is as 'ess ehch' or 'shh'

A quick googling suggests no one else uses the form 'sh-shell'

[wblock]

With the one comment above, this seems okay to me. Benedict, any additional notes?

en_US.ISO8859-1/books/handbook/jails/chapter.xml

210

We can avoid the issue with just "start a shell". sh is shown in the example anyway.

[allanjude]

en_US.ISO8859-1/books/handbook/jails/chapter.xml

210

It was explicit because the page used to contain a bunch of examples in other shells, and the code doesn't work in other shells. But I suppose since we are specific in the instructions, we can just say: start a shell.

[bcr]

Make it happen!

en_US.ISO8859-1/books/handbook/jails/chapter.xml

210

Yes, that's a good solution.

[allanjude]

Updated opening sentence

[bcr]

Now it's perfect. Thanks for working on this. Can't wait to put these new instructions to the test. ;-)

[allanjude]

Committed as rD46732