update the man page to reflect the new expectations

doc/opustags.1

@@ -1,4 +1,4 @@
-.TH opustags 1 "January 2013"
+.TH opustags 1 "2016"
 .SH NAME
 opustags \- Opus comment editor
 .SH SYNOPSIS
@@ -15,7 +15,7 @@ opustags \- Opus comment editor
 .SH DESCRIPTION
 .PP
 \fBopustags\fP can read and edit the comment header of an Opus file.
-It basically has two modes: read-only and read-write (for tag edition).
+It has two modes: read-only for tag listing, and read-write for tag edition.
 .PP
 In read-only mode, only the beginning of \fIINPUT\fP is read, and the tags are
 printed on \fBstdout\fP.
@@ -25,28 +25,31 @@ This could be useful to preview some changes before writing them.
 .PP
 As for the edition mode, you need to specify an output file (or \fB-\fP for
 \fBstdout\fP). It must be different from the input file.
-You may want to use \fB--overwrite\fP if you know what you’re doing.
+You may want to use \fB--overwrite\fP if you know what you're doing.
 To overwrite the input file, use \fB--in-place\fP.
 .PP
 Tag edition can be made with the \fB--add\fP, \fB--delete\fP and \fB--set\fP
-options. They can be written in any order and don’t conflict with each other.
-However, they aren’t executed in any order: first the specified tags are
-deleted, then the new tags are added. “Set” operations are mere convenience
-for delete/add.
+options. These don't conflict with each other, and you can use these options as
+many times as you wish.
+.PP
+In case an Ogg file contains multiple streams, the \fB--stream\fP option lets
+you specify the particular stream to modify. You can modify several streams at
+once by using this option more than once. Only operations specified after this
+option and relevant, and until another \fB--stream\fP option is found.
 .PP
 You can delete all the tags with \fB--delete-all\fP. This operation can be
 combined with \fB--add\fP to set new tags without being bothered by the old
-ones. Another way to do this is to use \fB--set-all\fP as explained below.
+ones.
 .PP
-If you want to process tags yourself, you can use the \fB--set-all\fP option
+If you want to process tags yourself, you can use the \fB--import\fP option
 which will cause \fBopustags\fP to read tags from \fBstdin\fP.
 The format is the same as the one used for output; that is to say,
 newline-separated \fIFIELD=Value\fP assignment. Note that this implies
 \fB--delete-all\fP.
 .PP
-\fBWarning:\fP the Opus format specifications requires tags to be encoded in
-\fBUTF-8\fP. This tool ignores the system locale, assuming the encoding is
-set to UTF-8, and assume that tags are already encoded in UTF-8.
+You can use \fB--edit\fP to spawn your \fBEDITOR\fP and edit the tags
+interactively. In read-write mode, if no other options is specified, this one
+is implied.
 .SH OPTIONS
 .TP
 .B \-h, \-\-help
@@ -56,53 +59,83 @@ Display a brief description of the options.
 Edition mode. The input file will be read, its tags edited, then written to the
 specified output file. If \fIFILE\fP is \fB-\fP then the resulting Opus file
 will be written to \fBstdout\fP. As the input file is read incrementally, the
-output file can’t be the same as the input file.
+output file can't be the same as the input file.
 .TP
 .B \-i, \-\-in-place \fR[\fP\fISUFFIX\fP\fR]\fP
 Use this when you want to modify the input file in-place. This creates a
-temporary file with the specified suffix (.otmp by default). This implies
+temporary file with the specified suffix (\fI.otmp\fP by default). This implies
 \fB--overwrite\fP in that if a file with the same temporary name already
 exists, it will be overwritten without warning. Of course, this overwrites
-the input file too. You cannot use this option when the input file is actually
-\fBstdin\fP.
+the input file too. You cannot use this option when the input file is \fBstdin\fP.
 .TP
 .B \-y, \-\-overwrite
 By default, \fBopustags\fP refuses to overwrite an already existent file. Use
-this option to allow that. Note that this doesn’t allow in-place edition, the
+this option to allow that. Note that this doesn't allow in-place edition, the
 output file needs to be different from the input file.
 .TP
+.B \-\-stream \fIID\fP
+Specify the stream that will be affected by the following options.
+Streams are numbered from 1, by their order of apparition in the file.
+The special id \fBall\fP selects all the Opus streams found, and is the default
+value.
+This option should be set if the input file contains more than one Opus stream,
+otherwise a warning is generated. If in-place modification is selected, this
+warning becomes a fatal error.
+.TP
 .B \-d, \-\-delete \fIFIELD\fP
-Delete all the tags whose field name is \fIFIELD\fP (they may be several, though
-usually there is only one of each type). You can use this option as many times
-as you want.
+Delete all the tags whose field name is \fIFIELD\fP. Note that one tag key,
+like \fIARTIST\fP, may appear more than once.
 .TP
 .B \-a, \-\-add \fIFIELD=VALUE\fP
-Add a tag. It doesn’t matter if a tag of the same type already exist (think
+Add a tag. It doesn't matter if a tag of the same type already exist (think
 the case where there are several artists). You can use this option as many
 times as needed, with the same field names or not. When the \fB--delete\fP
 is used with the same \fIFIELD\fP, only the older tags are deleted.
 .TP
 .B \-s, \-\-set \fIFIELD=VALUE\fP
-This option is provided for convenience. It delete all the fields of the same
+This option is provided for convenience. It deletes all the fields of the same
 type that may already exist, then adds it with the wanted value.
 This is strictly equivalent to \fB--delete\fP \fIFIELD\fP \fB--add\fP
 \fIFIELD=VALUE\fP. You can combine it with \fB--add\fP to add tags of the same
-type. As deletion occurs before adding, \fB--set\fP won’t erase the tags
+type. As deletion occurs before adding, \fB--set\fP won't erase the tags
 added with \fB--add\fP.
 .TP
 .B \-D, \-\-delete-all
 Delete all the tags before adding any. When this option is specified, the
 \fB--delete\fP options are ignored. Tags then can be added using \fB--add\fP
-or \fB--set\fP, which, in that case, are equivalent.
+or \fB--set\fP, which, in this case, are equivalent.
 .TP
-.B \-S, \-\-set-all
-Sets the tags from scratch. All the original tags are deleted and new ones are
+.B \-\-import
+Set the tags from scratch. All the original tags are deleted and new ones are
 read from \fBstdin\fP. Each line must specify a \fIFIELD=VALUE\fP pair and be
 LF-terminated (except for the last line). Invalid lines are skipped and cause
 a warning to be issued. Blank lines are ignored. This mode could be useful for
 batch processing tags through an utility like \fBsed\fP.
+.TP
+.B \-e, \-\-edit
+Spawn the program specified in the environment variable \fBEDITOR\fP to edit
+tags interactively. If this variable can't be read or is empty, an error
+message is displayed.
+.SH EXAMPLES
+Here's how you would list all tags in a stream:
+.PP
+	opustags in.ogg
+.PP
+Here's how you would edit two streams at once, setting the title and artist of
+the first, and only the title of the second:
+.PP
+	opustags --stream 1 --set TITLE=X --set ARTIST=Y --stream 2 --set TITLE=Y in.ogg -o out.ogg
+.PP
+Here's how you would set two artists:
+.PP
+	opustags --delete ARTIST --add ARTIST=A --add ARTIST=B in.ogg -o out.ogg
+.PP
+Hoping that helped.
 .SH SEE ALSO
 .BR vorbiscomment (1),
 .BR sed (1)
-.SH AUTHOR
-Frédéric Mangano <fmang@mg0.fr>
+.SH AUTHORS
+Frédéric Mangano <fmang+opustags@mg0.fr>,
+rr- <https://github.com/rr->.
+.PP
+Please report issues on GitHub at <https://github.com/fmang/opustags/issues>.