Translate annotations in the region into text properties.
This sets text properties between FROM to TO as directed by the
TRANSLATIONS and NEXT-FN arguments.
NEXT-FN is a function that searches forward from point for an annotation.
It should return a list of 4 elements: (BEGIN END NAME POSITIVE). BEGIN and
END are buffer positions bounding the annotation, NAME is the name searched
for in TRANSLATIONS, and POSITIVE should be non-nil if this annotation marks
the beginning of a region with some property, or nil if it ends the region.
NEXT-FN should return nil if there are no annotations after point.
The basic format of the TRANSLATIONS argument is described in the
documentation for the `format-annotate-region' function. There are some
additional things to keep in mind for decoding, though:
When an annotation is found, the TRANSLATIONS list is searched for a
text-property name and value that corresponds to that annotation. If the
text-property has several annotations associated with it, it will be used only
if the other annotations are also in effect at that point. The first match
found whose annotations are all present is used.
The text property thus determined is set to the value over the region between
the opening and closing annotations. However, if the text-property name has a
non-nil `format-list-valued' property, then the value will be consed onto the
surrounding value of the property, rather than replacing that value.
There are some special symbols that can be used in the "property" slot of
the TRANSLATIONS list: PARAMETER and FUNCTION (spelled in uppercase).
Annotations listed under the pseudo-property PARAMETER are considered to be
arguments of the immediately surrounding annotation; the text between the
opening and closing parameter annotations is deleted from the buffer but saved
as a string.
The surrounding annotation should be listed under the pseudo-property
FUNCTION. Instead of inserting a text-property for this annotation,
the function listed in the VALUE slot is called to make whatever
changes are appropriate. It can also return a list of the form
(START LOC PROP VALUE) which specifies a property to put on. The
function's first two arguments are the START and END locations, and
the rest of the arguments are any PARAMETERs found in that region.
Any annotations that are found by NEXT-FN but not defined by TRANSLATIONS
are saved as values of the `unknown' text-property (which is list-valued). The TRANSLATIONS list should usually contain an entry of the form (unknown (nil format-annotate-value)) to write these unknown annotations back into the file.