Page MenuHomeFreeBSD

Mention -media autofs map in the handbook.
ClosedPublic

Authored by trasz on Oct 22 2015, 4:59 PM.
Tags
None
Referenced Files
Unknown Object (File)
Jan 25 2024, 1:44 AM
Unknown Object (File)
Jan 10 2024, 1:42 AM
Unknown Object (File)
Jan 1 2024, 10:09 PM
Unknown Object (File)
Nov 29 2023, 7:27 AM
Unknown Object (File)
Nov 23 2023, 7:37 PM
Unknown Object (File)
Nov 10 2023, 12:03 PM
Unknown Object (File)
Nov 10 2023, 9:39 AM
Unknown Object (File)
Nov 9 2023, 5:53 AM
Subscribers

Details

Summary

Mention -media autofs map in the handbook.

Diff Detail

Repository
rD FreeBSD doc repository - subversion
Lint
No Lint Coverage
Unit
No Test Coverage
Build Status
Buildable 960
Build 960: arc lint + arc unit

Event Timeline

trasz retitled this revision from to Mention -media autofs map in the handbook..
trasz updated this object.
trasz edited the test plan for this revision. (Show Details)
en_US.ISO8859-1/books/handbook/disks/chapter.xml
515–516

This is true, but /media didn't arrive until 10.2; maybe we need to mention both?

-media appeared in 10.2.

emaste edited edge metadata.
emaste added a subscriber: wblock.

overall looks good to me, would like to see what @wblock has to say though

en_US.ISO8859-1/books/handbook/disks/chapter.xml
523–525

This reads a bit awkwardly to me, although I'm not sure if we have a usual way to explain this. Perhaps @wblock has a suggestion.

533

Maybe s/one must //

558–559

SD cards?

This revision is now accepted and ready to land.Oct 23 2015, 5:44 PM
en_US.ISO8859-1/books/handbook/disks/chapter.xml
512

Please run igor to check for title capitalization and other errors.

515

-media must have <literal> tags.

However, having this note before any text is confusing. The reader does not know why they are being told about this.

519

Try to write to avoid if/then sentences with a pause (comma) in the middle:

<acronym>USB</acronym> devices can be automatically mounted by
uncommenting this line in <filename>/etc/auto_master</filename>:</para>
523

I don't understand why the previous section says to uncomment lines in devd.conf, but this one says to add them.

523–525

I don't understand what the comment means. What does "discard" mean in this context? Is the cache for device names or filesystem buffers or something else? This is useful for -media--why? How? Look at it from the reader's point of view.

533

Use &man entity markup on autofs and devd.

Better to make this imperative, and again, try to rearrange to avoid if/then sentences with a pause:

Reload the configuration if &man.autofs.5; and &man.devd.8; are already running:
538

This is another if/then sentence with a pause.

&man.autofs.5; and &man.devd.8; can be enabled at boot time by adding
these lines to <filename>/etc/rc.conf</filename>:
544
Start the services immediately with:
549

devd is already running by default. Shouldn't that be service devd restart?

551

Passive -> active: s/will appear/appears/
Other changes to split long, confusing sentences:

<para>Each file system that can be automatically mounted appears as a directory
in <filename>/media/</filename>.  The directory is named after the file system label.
If the label is missing, the directory is named after the device node.</para>

<para>The file system is transparently mounted on the first access, and unmounted
after a period of inactivity.  Automounted drives can also be unmounted manually:
558

Avoid emdashes.

This mechanism is typically used for memory cards and <acronym>USB</acronym>
memory sticks.  It can be used with any block device, including optical drives or <acronym>iSCSI</acronym>
<acronym>LUN</acronym>.</para>
560

Unnecessary whitespace.

trasz edited edge metadata.

Igor plus fixes from wblock@.

This revision now requires review to proceed.Oct 29 2015, 2:22 PM
en_US.ISO8859-1/books/handbook/disks/chapter.xml
515

Hm. Perhaps "removable handling support in autofs is supported starting with 10.2-RELEASE"?

523–525

Well, it's a bit complicated. I'm not sure if we want to explain it here in length; it's just that piece of configuration file needs to be moved up, outside the comments section. The comment is just what's there at this point.

en_US.ISO8859-1/books/handbook/disks/chapter.xml
515

Something like that sounds good, but you want to rearrange, perhaps autofs supports automatic mounting of removable media as of FreeBSD 10.2-RELEASE

523–525

Maybe mention instead that the default config file contains a commented example of this config?

en_US.ISO8859-1/books/handbook/disks/chapter.xml
522

Please add a blank line before the <screen> element.

524

This sentence needs an article. I also suggest not numbering steps because they often become outdated.
s/Second/The next/

527

Please add a blank line before the <screen> element.

537

Please add a blank line before the <screen> element.

538

devd does not have the reload keyword:

# service devd reload
/etc/rc.d/devd: unknown directive 'reload'.
Usage: /etc/rc.d/devd [fast|force|one|quiet](start|stop|restart|rcvar|enabled|status|poll)
541

"enabled at boot time" is a little ambiguous here. "set to start at boot" is somewhat clearer.

devd is enabled by default. Maybe remove that line and note that devd is required?

<para>&man.autofs.5; can be set to start at boot by adding this line to
<filename>/etc/rc.conf</filename>:</para>

<programlisting>autofs_enable="YES"</programlisting>

<para>&man.autofs.5; requires &man.devd.8; to be enabled, as it is by default.</para>
554

Only one blank line between elements.

en_US.ISO8859-1/books/handbook/disks/chapter.xml
524

Or just Then add the following lines...?
Or Move the following lines out of the commented section?

541

I think if we mention that it relies on devd we should also include that it's enabled by default -- otherwise I can imagine a new user looking for the missing instructions to enable devd.

en_US.ISO8859-1/books/handbook/disks/chapter.xml
524
Then add or uncomment these lines in <filename>/etc/devd.conf</filename>:

This also avoids the semicolon.

541

Um... isn't that what the last part of that sentence does?

<para>&man.autofs.5; requires &man.devd.8; to be enabled, as it is by default.</para>
en_US.ISO8859-1/books/handbook/disks/chapter.xml
524

I don't think "uncomment" works well in this situation, where there aren't single lines to uncomment.

Here it's

/*

... a huge amount of unrelated stuff ...

​notify 100 {
	​        match "system" "GEOM";
	​        match "subsystem" "DEV";
	​        action "/usr/sbin/automount -c";
	​};

... a huge amount of additional unrelated stuff ...

*/

To me "uncomment" implies that the user can either remove a few # characters, or delete /* and */ perhaps, not obtain a set of lines out of the middle of a large block.

en_US.ISO8859-1/books/handbook/disks/chapter.xml
524

I see what you mean. In other places, we generally ignore what might already be present in files. I'd suggest that here, also. Just show the lines to add, and ignore whatever might be present already in comments. The document can't count on the comment being there. Neither can the comment count on what might be documented. "Don't repeat yourself" should be applied here. It is too easy for multiple copies of things to get out of sync, and I'd say the comment should be removed.

trasz edited edge metadata.

More fixes.

en_US.ISO8859-1/books/handbook/disks/chapter.xml
511

Needs a blank line before the new section.

515

"The" is not needed.

525

"the following" is almost always redundant.
s/the following/these/

526

Please split the sentences instead of splicing them with a semicolon. The second sentence needs an article ("The default").

However, I repeat: it is a mistake to state what the default configuration file contains, because that file can change without the documentation being updated. Better to tell the user what is needed and ignore whatever might or might not be in the example config file. So that whole sentence becomes just:

Then add these lines to <filename>/etc/devd.conf</filename>:</para>
wblock added a reviewer: wblock.

Looks good to me.

This revision is now accepted and ready to land.Dec 7 2015, 7:20 PM
This revision was automatically updated to reflect the committed changes.