Bug 197528 handbook/network-samba doesn't contain information how to generate conf file for samba4*

[sd_beastie.io]

Summary

This patch updates the samba server documentation for the handbook. Samba 3.x has been EOL'ed. Changes include:

1. Update all info from version 3.x to 4.x
2. Remove SWAT config section
3. Update global settings to add wins support info (makes it easy for sharing)
4. Default to tdbsam for password backed, and suggest ldapsam for network based auth.
5. Add section for quick and dirty smb4.conf (add reference to samba-tool for more complex provisioning)
6. Remove alternative for samba start, simple is better

Known issues:

1. Was unable to create link to samba-tool man page as it doesn't exist.

Test Plan

Ran igor and full doc build.

[sd_beastie.io]

Igor cleanup, note on smbpassword being obsoleted, and note on pdbedit tool requiring unix accounts to exist.

[wblock]

network-servers/chapter.xml

5077 ↗

(On Diff #15596)

The last two sentences in this paragraph are redundant and don't really add much. Condense down to one. "on &os;" is not needed. Context is not included with this diff, but that part about installing net/samba43 can go in the earlier sentence in this paragraph, and these redundant ones removed.

5082 ↗

(On Diff #15596)

"Runtime" doesn't really mean anything here. Why not switch this around to make the sentences simpler and shorter? (without markup)

"Samba is configured in /usr/local/etc/smb4.conf. This file must be created before Samba can be used."

5089 ↗

(On Diff #15596)

s/can be edited manually/is shown here/

5090 ↗

(On Diff #15596)

"it is recommended" is kind of clunky. Are we recommending it, or just suggesting an easier way to create the file?

5091 ↗

(On Diff #15596)

Should be <command> tags here, I think. Or &man.samba-tool.8; if we create an entity for it.

5117 ↗

(On Diff #15596)

As above, <command>.

But this sentence is complex and probably difficult for non-native English speakers. Who or how smb4.conf is created probably does not matter, this is really trying to say the most important entries the reader will need to know.

5127 ↗

(On Diff #15596)

"The workgroup name for the computers" is kind of complex. How about just "The name of the workgroup to be served."?

5158 ↗

(On Diff #15596)

"should" is usually for recommendations. Here, "will" is better.

5159 ↗

(On Diff #15596)

Avoid "you": https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style.html#writing-style-be-clear

But this might be better being more imperative:
"Do not enable <literal>wins support</literal> on more than one machine in the network."

5173 ↗

(On Diff #15596)

Not yours, but "for client users" seems to be either redundant or unnecessary.
Also, "the following" is almost always used incorrectly and should often be just "these". Here, it would be
"These directives control the options:"

5210 ↗

(On Diff #15596)

Needs commas:

authentication method, <literal>tdbsam</literal>,

5211 ↗

(On Diff #15596)

Break sentence into simpler ones:

is covered here.  It is ideal for simple setups.

But consider a more specific word than "setups". Is it simple networks, simple configurations, simple users?

5212 ↗

(On Diff #15596)

From context here, "setup" probably means "networks".

5215 ↗

(On Diff #15596)

"used to be" seems pretty informal. How about

smbpasswd was the former default but is now considered obsolete.

5226 ↗

(On Diff #15596)

Please don't say "assuming".

5229 ↗

(On Diff #15596)

This sentence seems to be saying at least two and possibly three different things.

1. These examples show the use of tdbsam.
2. Users (not really users, but FreeBSD usernames) are mapped to Samba accounts.
3. (before the shares can be accessed... does not seem necessary. Sort of restating that it does not work until it is set up.)

5230 ↗

(On Diff #15596)

Probably better to say &os; to avoid confusing the reader.

5236 ↗

(On Diff #15596)

<command> tags or &man entities are needed on these names.

5238 ↗

(On Diff #15596)

s/accounts/account/ (I think)

5240 ↗

(On Diff #15596)

Sorry, it is hard to tell what this sentence is saying. "This only works for accounts that already exist. It does not create user accounts."?

5241 ↗

(On Diff #15596)

Long if/then sentence with a pause. Rewrite to eliminate the pause:
"Make certain that &os; accounts have been created before running <command>pbedit</command>."

Anticipate the reader question: what is a "system" account?

[sd_beastie.io]

Updated review comments - diff to follow.

network-servers/chapter.xml

5077 ↗

(On Diff #15596)

Removed the last two lines, no need to specify that we are dealing with server configuration below if we just switch the title of the next section.

5241 ↗

(On Diff #15596)

I am getting rid of this whole paragraph as I think, now, it's irrelevant. User is going about setting up a samba share and we are providing them with instructions on how to do so. I don't think there is a need to go in an explain why things need to be mapped and which accounts need to exists vs created. More likely to confuse the user than help.

[sd_beastie.io]

Updated diff based on review feedback

[sd_beastie.io]

Missed removing an unnecessary section, note about user accounts must exist removed as its covered in the text prior to the example.

[wblock]

en_US.ISO8859-1/books/handbook/network-servers/chapter.xml

5087 ↗

(On Diff #15777)

Remove "the":
s/the &man.samba-tool.8;/&man.samba-tool.8;/

5101 ↗

(On Diff #15777)

Below... where? Better to use a callout for things that are not actually part of the file.

5113 ↗

(On Diff #15777)

"A list of" is not needed. "Need to be" is kind of clunky. How about just "are"?

Settings that describe the network are added in

5132 ↗

(On Diff #15777)

Needs a comma after "default":
s/default/default,/

5154 ↗

(On Diff #15777)

"machine" is really vague. I suspect this is really saying "more than one *server* on the network", but am not sure.

5164 ↗

(On Diff #15777)

Don't count options, because that inevitably gets out of sync. How about just:

The most important settings in

5174 ↗

(On Diff #15777)

Should probably be "settings" instead of "options".

5204 ↗

(On Diff #15777)

"covered here" is out of place. Better to relocate it (or remove it):

is ideal for simple networks and is covered here.

5257 ↗

(On Diff #15777)

To the reader, that sentence is a bit vague and sounds like winbindd is enabled and started automatically. Is it, or does the user need to enable it?

5259 ↗

(On Diff #15777)

s/may/can/

[sd_beastie.io]

Updated - patch to follow soon.

en_US.ISO8859-1/books/handbook/network-servers/chapter.xml

5101 ↗

(On Diff #15777)

Simplied to just the &unix; user. This will avoid the user to have to jump and text below explains it.

[sd_beastie.io]

Updated diff based on review comments

[wblock]

en_US.ISO8859-1/books/handbook/network-servers/chapter.xml

5070 ↗

(On Diff #16745)

This is really two acronyms, so should be marked up as:

<acronym>SMB</acronym>/<acronym>CIFS</acronym>

5113 ↗

(On Diff #16745)

Remove "are".

5153 ↗

(On Diff #16745)

Wait, is "WINS" upper or lower case? It is shown both ways here. If the setting is lowercase, it should only be shown that way here.

5208 ↗

(On Diff #16745)

Maybe clearer to remove "considered" and just say "...is now obsolete."

5101 ↗

(On Diff #15777)

Better, but the trailing comment is still confusing. I think it can just be removed, the comment above explains it.

5257 ↗

(On Diff #15777)

I don't understand what the sentence is saying now. There is a plural/singular confusion (services are/it can be).

Also the method of how it is started is not really shown. So overall:

If winbind name resolution is also required, set:</para>

<programlisting>winbindd_enable="YES"</programlisting>

[sd_beastie.io]

en_US.ISO8859-1/books/handbook/network-servers/chapter.xml

5070 ↗

(On Diff #16745)

Done. Breaking the line length rule to avoid whitespace only change.

5153 ↗

(On Diff #16745)

Should be an acronym for both instances in this sentence. Re-worded it to clarify.

[wblock]

It looks good. The added entities are not shown in this diff. It looks like &samba-tool.8; is needed, but I did not try to build it. Thank you for your patience!

[sd_beastie.io]

My bad - forgot to specify the man ref entities file to my macro :-/ Will switch to arc after this review :)