What's the purpose of the --profile option and how does it work?

For my understanding, there's two meanings.
1) specifying a color profile for the pdf output (e.g. an ICC file)

2) specifying a pdf profile like "X1-a"

But how does it work?

None of the following options work and the user guide isn't helping at all...

prince --profile=ISOcoated_v2_300_eci.icc demo.xhtml -o demo.pdf
prince --profile=X1-a demo.xhtml -o demo.pdf
prince --profile="X3" demo.xhtml -o demo.pdf
prince --profile="PDF/X1-a" demo.xhtml -o demo.pdf

Each cmd results in

prince: error: invalid value for option `--profile'

Could you please answer this and update your documentation?

Currently the only profile fully supported is PDF/A-1b. We are going to add tagged PDF to support PDF/A-1a in a future release of Prince, and the remaining metadata needed for PDF/X.

Okay, so the syntax for the --profile option is:

prince --profile="PDF/A-1b" demo.xhtml -o demo.pdf

Could you probably add this to the users guide together with a list of valid values (which at the moment would only contain "PDF/A-1b")?! This would help a lot!

Right, quick page on PDF profiles stating that we currently support PDF/A-1b, with others on the way. There's a link from the command-line documentation; hopefully this will help.

The latest Prince alpha now supports PDF/X-3 and PDF/X-4, so you can do this:

prince --pdf-profile="PDF/X-4" --pdf-output-intent=ISOcoated_v2_300_eci.icc demo.html -o demo.pdf

Note that we have renamed --profile to --pdf-profile for clarity, although the old option is still available for convenience.