Add EXAMPLES section to the manual1.1.2

1 files changed, 63 insertions, 0 deletions

diff --git a/bosun.1 b/bosun.1
index b4925cf..0c3dde4 100644
--- a/bosun.1
+++ b/bosun.1
@@ -76,6 +76,69 @@ will list active roles.
 .It Pa /etc/portage/stow
 The base directory containing all portage roles.
 .El
+.Sh EXAMPLES
+The following directory structure under
+.Pa /etc/portage/stow
+describes a simple setup of bosun with three roles,
+.Em service-mail ,
+.Em app-tex ,
+and
+.Em group-musl .
+.Bd -literal -offset indent
+service-mail/package.accept_keywords/20-service-mail
+service-mail/package.use/20-service-mail
+app-tex/sets/tex
+group-musl/package.accept_keywords/02-group-musl
+group-musl/repos.conf/musl.conf
+group-musl/patches/net-misc/openssh/disable-utmp-in-musl.patch
+.Ed
+.Pp
+After activating
+.Em group-musl
+and
+.Em service-mail ,
+.Pa /etc/portage
+will look something like this:
+.Bd -literal -offset indent
+package.accept_keywords/02-group-musl@
+package.accept_keywords/20-service-mail@
+package.use/20-service-mail@
+patches/net-misc/openssh/disable-utmp-in-musl.patch@
+repos.conf/musl.conf@
+.Ed
+.Pp
+Here, each symbolic link points to the corresponding file in
+.Pa /etc/portage/stow .
+.Nm
+transparently merged the given roles into one structure.
+After removing
+.Em group-musl
+and activating
+.Em app-tex ,
+the directory will look like this:
+.Bd -literal -offset indent
+package.accept_keywords/20-service-mail@
+package.use/20-service-mail@
+sets/tex@
+.Ed
+.Pp
+As roles are activated or removed, the role directory stays untouched; it is
+merely the symbolic links that are added or removed.
+This makes it suitable to manage
+.Pa /etc/portage/stow
+in
+.Xr git 1 .
+.Pp
+Suppose we add another file to the
+.Em service-mail
+role in a new directory
+.Pa package.use .
+The role is already active, but since
+.Nm
+cannot know that it has been changed, we need to rebuild the symbolic links:
+.Bd -literal -offset indent
+bosun rebuild service-mail
+.Ed
 .Sh SEE ALSO
 .Xr portage 5 ,
 .Xr stow 8