review the user doc

CHANGELOG.md

@@ -4,11 +4,13 @@ opustags changelog
 1.2.0 - TBA
 -----------
 
-This is the biggest release for opustags. The whole code base was reviewed for robustness and
-clarity. It doesn't offer new features, but fixes a few bugs and improves error reporting.
+- Preserve extra data in OpusTags past the comments.
+- Improve error reporting.
+- Fix various bugs.
 
-The program is now built as C++14, and the code refactored without sacrificing the original
-simplicity. It is shipped with a new test suite for preventing regressions.
+This is the biggest release for opustags. The whole code base was reviewed for robustness and
+clarity. The program is now built as C++14, and the code refactored without sacrificing the
+original simplicity. It is shipped with a new test suite for preventing regressions.
 
 1.1.1 - 2018-10-24
 ------------------

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to opustags
 
-opustags is not quite active nor mature, but contributions are welcome.
+opustags is slowing getting more mature, and contributions are welcome.
 
 Before you open a pull request, you might want to talk about the change you'd
 like to make to make sure it's relevant. In that case, feel free to open an
@@ -41,12 +41,19 @@ questioned, and it was thus abandoned for a few years. Judging by the
 inquiries and contributions, albeit few, on GitHub, it looks like it remains
 relevant, so let's dust it off a bit.
 
-The current low-expectation plan to improve this project comprises the
-following directions, in whatever order:
+Today, opustags is written in C++14 and features a unit test suite in C++, and
+an integration test suite in Perl. The code was refactored, organized into
+modules, and reviewed for safety.
 
-- Write a complete test suite in Perl, calling opustags as a subprocess.
-- Build opustags in C++14. The code will remain mostly C.
-- Build the project with CMake, or maybe autotools.
-- Refactor the code to improve the readability.
-- Integrate code from the `next` branch.
-- Fuzz it. Memcheck it.
+The next release will focus on correctness, with the following technical
+objectives:
+
+1. Validate the comments: field name in ASCII and value in UTF-8.
+2. Allow selecting the stream to edit, instead of assuming the Ogg contains only
+   one Opus stream.
+3. Provide an --escape option for escaping the newlines inside comment strings.
+4. Take into account the system's encoding: the tags must always be stored as
+   UTF-8, and converted from and to the console encoding when reading input or
+   printing.
+5. Maybe provide a --binary option to dump the raw OpusTags packet, that can be
+   combined to --set-all to read it back.

README.md

@@ -3,10 +3,8 @@ opustags
 
 View and edit Opus comments.
 
-The current code quality of this project is in a sorry state, but that might
-change in the near future. It is expected to work well though, so please do
-open an issue if something doesn't work. New contributions are welcome but make
-sure you read CONTRIBUTING.md first.
+The current code quality of this project is getting better, and is suitable for reliably editing any
+Opus file provided it does not contain other multiplexed streams. Only UTF-8 is currently supported.
 
 Until opustags becomes top-quality software, if it ever does, you might want to
 check out these more mature tag editors:

opustags.1

@@ -1,4 +1,4 @@
-.TH opustags 1 "January 2013"
+.TH opustags 1 "November 2018" "@PROJECT_NAME@ @PROJECT_VERSION"
 .SH NAME
 opustags \- Opus comment editor
 .SH SYNOPSIS
@@ -15,34 +15,28 @@ 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 basically has two modes: read-only, 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.
-\fIINPUT\fP can either be the name of a file or \fB-\fP to read from \fBstdin\fP.
+printed on standard output.
+\fIINPUT\fP can either be the name of a file or \fB-\fP to read from standard input.
 You can use the options below to edit the tags before printing them.
 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.
-To overwrite the input file, use \fB--in-place\fP.
+In edition mode, you need to specify an output file (or \fB-\fP for standard output). It must be
+different from the input file. 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.
+Tag edition can be performed with the \fB--add\fP, \fB--delete\fP and \fB--set\fP
+options. Options can be specified in any order and don’t conflict with each other.
+First the specified tags are deleted, then the new tags are added.
 .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.
+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.
 .PP
-If you want to process tags yourself, you can use the \fB--set-all\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.
+If you want to replace all the tags, you can use the \fB--set-all\fP option which will cause
+\fBopustags\fP to read tags from standard input.
+The format is the same as the one used for output: newline-separated \fIFIELD=Value\fP assignment.
+All the previously existing tags as deleted.
 .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
@@ -53,34 +47,30 @@ set to UTF-8, and assume that tags are already encoded in UTF-8.
 Display a brief description of the options.
 .TP
 .B \-o, \-\-output \fIFILE\fI
-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.
+Specify the output file.
+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 standard output.
+The 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
-\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.
+Use this when you want to modify the input file in-place. opustags will create a temporary output
+file with the specified suffix (.otmp by default), and move it to the location of the input file on
+success. If a file with the same name as the temporary file already exists, it will be overwritten
+without warning.
+This option conflicts with \fB--output\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
-output file needs to be different from the input file.
+this option to allow that.
 .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. They may be several one of them, though usually
+there is only one of each type.
 .TP
 .B \-a, \-\-add \fIFIELD=VALUE\fP
-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.
+Add a tag. Note that multiple tags with the same field name are perfectly acceptable, so you can add
+multiple fields with the same name, and previously existing tags will also be preserved.
+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
@@ -91,18 +81,16 @@ 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.
+Delete all the previously existing tags.
 .TP
 .B \-S, \-\-set-all
-Sets 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.
+Sets the tags from scratch.
+All the original tags are deleted and new ones are read from standard input.
+Each line must specify a \fIFIELD=VALUE\fP pair and be separated with line feeds.
+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.
 .SH SEE ALSO
 .BR vorbiscomment (1),
 .BR sed (1)
 .SH AUTHOR
-Frédéric Mangano <fmang@mg0.fr>
+Frédéric Mangano-Tarumi <fmang@mg0.fr>