Updated Documentation — Work in Progress

I'm currently in the process of updating the documentation and wanted to share my current work in progress:

https://docs.mp3tag.de

The plan is to let this replace the old help files once it's complete.

It's based on the old help files, but rewritten in my current state of English and has the intention to be structurally more compelling and more complete than the previous incarnation.

If you have any wishes for additional topics, change in structure, or other feedback please let me know.

1 Like

The sections I checked out were not complete enough for me to give feedback but I really like that you are working on this!

1 Like

I'll ditto what @esumsea said. Great idea!

The section
https://docs.mp3tag.de/converters/rearrange-filenames/
talks only about the placeholder %1 ..%9, yet also text is allowed to define the pattern, e.g.

01-Hey jude.mp3
the leading number could be stripped with
Old filename pattern: %1-%2
New pattern: %2
which leaves just
Hey Jude.mp3

Also, I think that the filename could be defined also with folder names up to a fully-qualified filename (which includes the drive letter) and not just a folder name.
This could be a central topic "How to define patterns for a filename" - as this technique also applies to Converter>Filename-Tag.
As the current description emphasizes that a single file get moved to a new location and that the folder keeps its name, a link to Converter>Tag-Tag and its function to rename a _DIRECTORY would be nice or to a similar topic that describes this (special) use case.

On the topic
https://docs.mp3tag.de/converters/import-tags-from-text-files/

in the forum there are numerous threads that ask about how to import data from a text file in the CSV format.
So I would appreciate a description of how to import CSV files.
The current description should be expanded by the instructions from the current help that also describes how to align files with the records in the text file with the help of the _PATH data.

If the help should appear online, I think it would be worthwhile to support some of the interactions with the program with screen videos (like @LyricsLover has supplied them to illustrate some interactions).
For me, the handling of the converters would spring to mind in which it could be demonstrated how adding variables and fixed text defines the structure of a filename.

The same could the case for Converter>Filename-Filename.

Something like this AniGif?

Mp3tag - Format string

I also believe, that a few pictures or AniGifs can illustrate such interactions better then words alone.
Did you know that you can even stop such animations if you click on the lower right corner of the picture?

1 Like

That's what I meant.
(It would even be better if one could see the full filename including the path somewhere - otherwise the extra fields extracted from the folders come as a little suprise.
But such geegaws can be discussed once the basic decision has been made.

I've added the CSV example and the description on matching based on the file name/path.

Good points! I've mentioned standard text and absolute path names in the latest version.

On the section
https://docs.mp3tag.de/converters/rename-files/

the old help does not mention the square brackets to enclose optional parts.
So as the new help features an example with an absolute path, a further example with an absolute path plus an optional part (usually [CD$num(%discnumber%,1)\] could highlight this feature so that no complicated $if2() statements have to be composed to create a subfolder if there is a discnumber.

Appending edit:
I just remembered that the square brackets play this role not only in the Converters for filenames but actually any (as no learned) generating format string. So it may be not the right place to describe the brackets only with the converter but in a more referencial section where the properties of a format string are described.

On the topic of converters ...
I am not sure how to explain the stuff with text that is taken as is and the variables like %artist%
In fact, I think it has to be emphasized that ...

  • plain text is ignored when a string is read and the text is used as separator between field variables. Then only the data part form the source string that can be found between the explicitly entered text is read into the referenced fields or place holders. This is the case for Converter>Filename-Tag and the source pattern in Converter>Filename-Filename.
  • plain text is used "as entered" when MP3tag should write information. This is the case for Converter>Tag-Filename and Converter>Tag-Tag and the target pattern in Converter>Filename-Filename.

In this context there is also the pseudo variable %dummy% which is only used when data is read and in the pattern there is something that could be variable text between plain text or a mixture of plain and variable text.

Perhaps I see this far too complicated - and probably the preview in the converters will overcome most problems. Yet, I find it worthwhile to create a description that makes it clear that reading and writing are different cups of tea and that even though things may look similar they are not the same.

I also thought about this and came up with a (still internal) distinction between generating and matching format strings. Would that be a good distinction (accompanied by fitting documentation) of the "two cups of tea"?

Perfect. That's it.......

1 Like

I've added the distinction between generating and matching format strings to https://docs.mp3tag.de/format and also explained, that scripting functions can only be used with the former.

I've added the [CD$num(%discnumber%,1)\] example to the documentation of the conditional bracket notation.

In section "Scripting"
https://docs.mp3tag.de/scripting/
I found the internal navigation (advance organizer) that addressed the string, boolean, arithmatic, variable and metadata functions quite useful to jump straight to the functions I was looking for.

The description of the case conversion functions talks about a second parameter but shows this only for $caps(string,...). In this context it is not clear to me how a comma is escaped if that is used to trigger the case conversion.
The examples for string case conversion call themselves examples but do not show the source string and what that would look like after treatment by the function.
I think that the defintion of "string" as parameter for the string functions is not correct as, actually, you may use a generating format string.
Also, in general, I would like a homogenous description of all functions and not some in the format of those called "General" functions (although these are mainly string functions) and some as the kind of table for the other functions. Also, it is irritating (for me) that some functions are described in such an elevated way but they don't appear in the functions list later on.
So if a reader would use the advance organizer called "String functions" he or she would jump over the case conversion functions and never see them in the section for string functions.
So my suggestion would be: all functions are described alphabetically in their group topic in the same way.
For each function there should be a syntax example and a result example.
And, of course, the data types should be correct.

As the scripting functions also feature the $meta() functions it may be worthwhile to contemplate about the names for %fieldvariable contents% and FIELDVARIABLENAME - one enclosed in %, the other without.

Even though export scripts are something different, I am missing $loop() and $loopend() - as $puts(x) is referenced and, honestly, I have never seen a use of this function outside an export script.

Meta characters for scripting function descriptions

I would consider the scripting functions to be some kind of programming language.
For the description of programming commands, there is always the challenge to get it clear what is the command (and has to be typed in as shown), what is a literal parameter (that has to be typed in as shown), what is the reference to a data type (and has to be filled with something variable), and what are optional parameters (that can be left out).
A good way would be to use characters that do not get used otherwise in the commands.
I would consider it a step forward if such a meta syntax could be applied.

On export scripts:
https://docs.mp3tag.de/export/

The description does not explain the special effect of $loop(1) which does not sort the selected files. The current description looks as though a field reference would be mandatory.
As this ommited extra sorting is useful for e.g. playlists, I would mention that as an extra use case.

I've added the advanced organizers.

I've added the parameter also to the other functions.

I've added additional explanation to the general description on how to pass parameters as raw text.

I've added a clarification to the general description.

I've removed the special treatment of some functions.

I've moved those to a dedicated subsection of the export documentation.

I pass on this one. I'm probably biased as I'm so used to this language, but I think it's clearly described in the textual description of the parameters.