Add command-line option to write output to a file

1 files changed, 50 insertions, 14 deletions

diff --git a/doc/man/serd-pipe.1 b/doc/man/serd-pipe.1
index ae3e6620..793737f9 100644
--- a/doc/man/serd-pipe.1
+++ b/doc/man/serd-pipe.1
@@ -18,21 +18,46 @@
 .Op Fl p Ar prefix
 .Op Fl r Ar root
 .Op Fl s Ar string
+.Op Fl w Ar filename
 .Op Ar input ...
 .Sh DESCRIPTION
 .Nm
-is a fast command-line utility for streaming and processing RDF data.
-It reads one or more RDF documents and writes the data to stdout,
-possibly transformed and/or in a different syntax.
+is a fast command-line utility for streaming RDF data.
+It reads one or more files and writes the data again,
+possibly in a different form.
+.Pp
+.Nm
+writes statements immediately as they are read,
+so it uses little memory and is suitable for use in pipelines and with huge files.
+Typical uses include checking syntax,
+converting to another syntax,
+pretty-printing,
+merging files,
+expanding URIs,
+and so on.
+.Pp
 By default,
-the input syntax is guessed from the file extension,
-and output is written in NTriples or NQuads.
+syntaxes are guessed from file extensions where possible,
+making use with filenames most convenient.
+For example,
+most common tasks can be accomplished with simple commands like:
+.Pp
+.Dl $ serd-pipe -o pretty.ttl input.nt
 .Pp
+The
+.Ar input
+operands are processed in command-line order.
+If
+.Ar input
+is
+.Ar -
+or absent,
 .Nm
-can be used to check for syntax errors,
-convert from one syntax to another,
-pretty-print documents,
-or transform URIs and blank node IDs.
+reads from standard input.
+Similarly, output defaults to standard output.
+If syntax isn't given and can't be determined from filenames,
+then input is read as TriG and output is written as NQuads
+(which will function properly with Turtle and NTriples, respectively).
 .Pp
 The options are as follows:
 .Bl -tag -width 3n
@@ -158,6 +183,10 @@ as input.
 Write terser output without newlines.
 .It Fl v
 Display version information and exit.
+.It Fl w Ar filename
+Write output to the given
+.Ar filename
+instead of stdout.
 .It Fl x
 Support parsing variable nodes.
 Variables can be written in SPARQL style, for example
@@ -182,16 +211,23 @@ If set to anything other than 0, color is forced on.
 exits with a status of 0, or non-zero if an error occurred.
 .Sh EXAMPLES
 .Bl -tag -width 3n
-.It Pretty-print a document:
-.Nm Fl o
+.It Format a Turtle file to stdout:
+.Nm Fl O
 .Ar turtle
-.Pa file.ttl
->
-.Pa out.ttl
+.Pa input.ttl
 .It Print only errors and discard the output:
 .Nm Fl O
 .Ar empty
 .Pa input.ttl
+.It Convert an NTriples file to Turtle:
+.Nm Fl o
+.Ar output.ttl
+.Pa input.nt
+.It Merge two files:
+.Nm Fl o
+.Pa merged.ttl
+.Pa header.ttl
+.Pa body.ttl
 .El
 .Sh SEE ALSO
 .Bl -item -compact