Improve serdi man page

2 files changed, 39 insertions, 3 deletions

diff --git a/NEWS b/NEWS
index 06790a11..ebc97088 100644
--- a/NEWS
+++ b/NEWS
@@ -5,10 +5,11 @@ serd (0.30.17) unstable; urgency=medium
   * Fix hang when skipping an error at EOF when lax parsing
   * Gracefully handle bad characters in Turtle blank node syntax
   * Gracefully handle bad characters in Turtle datatype syntax
+  * Improve serdi man page
   * Override pkg-config dependency within meson
   * Test header for warnings more strictly
 
- -- David Robillard <d@drobilla.net>  Thu, 24 Nov 2022 21:05:52 +0000
+ -- David Robillard <d@drobilla.net>  Mon, 28 Nov 2022 18:45:50 +0000
 
 serd (0.30.16) stable; urgency=medium
 
diff --git a/doc/serdi.1 b/doc/serdi.1
index 88546884..48b1a5d4 100644
--- a/doc/serdi.1
+++ b/doc/serdi.1
@@ -47,8 +47,15 @@ If this is enabled, output will be written a page at a time, rather than a byte
 Chop
 .Ar prefix
 from matching blank node IDs.
-This is the inverse of
+This is typically used to revert the effects of
 .Fl p .
+For example, with
+.Ar prefix
+.Dq doc01 ,
+the blank node
+.Li _:doc01b42
+will be emitted as
+.Li _:b42 .
 .Pp
 .It Fl e
 Eat input one character at a time, rather than a page at a time which is the default.
@@ -89,6 +96,15 @@ Add
 .Ar prefix
 to blank node IDs.
 This can be used to avoid clashes between blank node IDs in input documents.
+The effects can be reversed in a later run with
+.Fl c .
+For example, with
+.Ar prefix
+.Dq doc01 ,
+the blank node
+.Li _:b42
+will be emitted as
+.Li _:doc01b42 .
 .Pp
 .It Fl q
 Suppress all output except data.
@@ -98,10 +114,29 @@ Keep relative URIs within a
 .Ar root
 URI.
 This will avoid creating any relative URI references with leading path segments like
-.Dq ../
+.Pa ../
 that enter a parent of
 .Ar root .
 .Pp
+For example,
+if
+.Pa /home/you/file.ttl
+is written to the file
+.Pa /home/me/output.ttl
+using the destination's base URI,
+then it could be written as
+.Li <../you/file.ttl> .
+Setting
+.Fl r Li file:///home/me/
+would prevent references from
+.Dq escaping
+like this,
+so the above would instead be written as
+.Li <file:///home/you/file.ttl> ,
+since it can't be expressed relative to the root URI.
+.Pp
+This is useful for keeping relative references within some directory.
+.Pp
 .It Fl s Ar string
 Parse
 .Ar string