Updated Documentation — Work in Progress

Alas! Finally, a typo!

please aks their -> please ask their
and in

an "iff" with a double "f".

On another note: in older times there were questions about the Lyrics V1 tag. The advice there was to remove ID3V1 tags
(e.g. [X] Anzeige von !!! Lyrics TAG !!! in Spalte APE-Tag)
So, would it be helpful to mention that if you select "Remove ID3V1 tags" the Lyrics V1 tag also gets removed?

I don't know if this something to be mentioned in the section about export or in the messages section
If you select the message

at exporting tags

If enabled, shows a confirmation message that allows for opening the exported file after exporting.

MP3tag tries to open the resulting export file with the associated application.
So the reaction there depends on the extension of the filename specified in $filename() or the filename in the export dialogue.
So if a cmd file is created, a word of caution might be of value.
What I would like to see is a link from the export description to the message that deals with the export and also from the export message to the export description to make clear why sometimes another program gets opened after the export.

Fixed the typos and mentioned Lyrics3. Also made clear that Mp3tag uses the default program associated with the file extension of the exported file when confirming to open.

Still on the topic of exports

I would like to see a description of how the export filename is found.
The default is taken from the export configuration.
If there nothing has been defined, then the last used export filename is taken.
Both can be overwritten at the time of calling the export and prior to clicking OK.

The description for $filename(name,[enc]) (oooh, I see some kind of metasyntax creeping in!) should be appended to that the name is also an optional parameter but then a filename has to be defined at runtime.

On the topic of Format Strings and Placeholders:

There is an example list of assumingly frequently used field variables - but these are by far not all.
The complete list for these (supported) tag fields can be found in

but in the Format strings and Placeholders section there is no link to the mapping section - just like there is no link from the mapping section to the Format strings.
In the Export section there is a link to Scripting functions and Format string but none to the Mapping section.
IMHO either the sections should be linked so that the user gets an idea what he/she can really use in format strings or the sections about placeholders should be combined - just like they are in the button menus in e.g. the filter or the converters.
Then you would have a complete list together and also learn that the variables are grouped for special purposes.

On the topic of filters

"It is not possible to filter by strings containing double quotations marks. This is a limitation of the feature." - I think that there was the workaround with $char(34)
e.g.

I am not sure if the filter syntax is really described correctly.
Most syntax examples start with
<field> ...
(fascinatingly with some kind of metasyntax...)
but I think that this not really just a <field> as there are filter examples like

where the scripting part at the front is not really a <field>
I would think that this is a "generating format string" enclosed in double quotation marks.

I've extended the documentation in that regard.

Added, also mentioned file extension which is also possible.

Added links in both directions.

I've added this although I'm not sure if it should be part of the documentation.

There is already a clarifying statement under "Notes"

I've just made a silent release by redirecting the URLs of the old help files to the new documentation. I think it's in very good shape now and already much better than what we had before.

Thanks @ohrenkino for your helpful feedback and all the suggestions for improvement! :pray: :pray:

1 Like

Sorry to reply so late in this process. I had a couple of things stand out as I read through the these updates help notes.

In the Getting Started>Overview section there is mention of several audio formats that mp3tag supports. This is not a complete list, but also it does not mention that mp3tag also supports several video formats as well. I think this should be relevant. Plus you can link from this paragraph to the full list of supported file formats referenced later.

The other thing that I think would be helpful would be to include the menu bar icons used in mp3tag in all of the applicable sections. This would help provide a visual link from the help documents to those functions within the mp3tag window. I’m not sure how easy it is to insert these,

The fixed mapping link is broken in the section Mapping> User-defined field mappings

There are several references to “field“ values, enclosed in the less-than and greater-than characters that the forum won’t show. Perhaps these can be an active link to a page with a list of the common ones that are pre-defined in mp3tag. The list should match those in the filter, broken into the standard, extended, and information fields. Of course this can be further enhanced by custom user-defined fields but are behind the scope of those defined here.

Just a few amendments:
The List of Menus does not mention the Help menu.
As this menu features some functions that may help (!) if something does not work like
"Check for updates" where the failure to produce a message indicates that MP3tag has no internet access
or
the "About" dialogue which now tells you what kind of installation you have (Standard or portable),
it would be nice to see these functions mentioned.
(I do see the problem that if you have no internet access and you want to see the information about how to check the connection that this is could turn into a cul-de-sac.)
In the section "Download and Installation" a link to the function File>Open Configuration folder and Help>About would add more insight.

I'm not sure, but maybe you're referring to an older version of that site. It mentions some tag formats and links to Supported File Formats – Mp3tag Documentation

I've made a note regarding this.

Fixed, thanks!

I'm afraid, I don't understand this suggestion. Can you give an example?

Added, Menu Help – Mp3tag Documentation

I've added some details on Backup and Restore of configuration settings and mentioned the menu entry in this context.

I suggest to release an additional overview in table format for the tag mapping like this:

https://wiki.hydrogenaud.io/index.php?title=Tag_Mapping#Mapping_Tables

or your own "old" Tag Field Mappings – Mp3tag Documentation

This could be done as separate PDF or Picture (it's size could be increased by clicking on it) if a table doesn't fit in the current layout.

I must have missed the highlight for the link when I was reading through it last night, as it is there now. But it calls out specifically "audio formats" and I was suggesting that mp3tag is now much more diverse and also allows tag editing for several video formats as well. Perhaps a small change to the link to indicate "a variety of audio and video formats" would be more accurate.

I'm afraid, I don't understand this suggestion. Can you give an example?
[/quote]

On the filter page...

...their are many examples of the use of <field> but none are linked to any references like almost all others are.

Here there is mention that * will address all fields.

Other examples provide some scope with an example, but nowhere is there a list in the help of what all of the valid existing predefined <field> values are. A reference page to list these for these may clarify better where a user may begin.


I would like to support your point of view.

This is something I tried to address in my post here:

You can see that I had my problems with this notation and metasyntax.
I still think that it is not a field but a "generating format string" - which is used in many other contexts.
I would still consider it a nice move to use the same jargon for all these contexts.

It can be both, an actual tag field, e.g., artist or a format string like %artist%. I've tried to clarify that in the note

  • If <field> in HAS/IS/GREATER/LESS/EQUAL/MATCHES contains $ or % it should be enclosed in double quotation marks and will be treated as a format string instead of a tag field name. This will decrease search speed on large libraries since the format strings need to be evaluated before filtering.

A generating format string can be all of this:

  • a text constant,
  • a field or property reference,
  • a scripting function
  • and a combination of all the above.

And the same applies to that what is currently named <field> for filter.

Yes, but it's a little more tricky with the filter. What would be a text constant without spaces in a generating format string is a field reference in the Filter.

artist HAS test matches if any of the values in field ARTIST contains test, so it's not really treated as a text constant as in the context of format strings.

You can see the filter working with field names (not enclosed in %), which then uses value-lookup for the referenced field and uses the resulting string for matching. The extended functionality of the filter is allowing format strings instead of field names (anything with % or $ and enclosed in ") where the string is matched against the evaluated format string.

Admittedly, I did not consider this special function of the filter.
Yet, I think that the overlap between "generating format string" and the functions of the filter is larger than that of a field - as "field" is also used for the mappings and other references to fields and fields contents.
I agree that this behaviour has to be described but I disagree to call it a <field>.
I would not introduce a new meaning for "field" but use the note instead to decribe that additionally to the otherwise used reference to fields here, in this case, the % may be omitted (but even this is not mandatory).

I didn't realize this was possible even after all these years. My "learned something new" for today! :+1: