14

So, I stumbled across a document that began with,

\DocumentMetadata{pdfversion=1.2}
\nonstopmode\synctex=1
\documentclass{article}

I have seen line 2 and 3 in the wild but I have never seen line 1 anywhere before. I am curious what is it, what does it do and what values does it accept?

2 Answers 2

17

\DocumentMetadata is a rather new command, it has been announced one year ago in the LaTeX news . It is the trigger to tell LaTeX that the current document is a new/modern document that should use concepts not available in traditional LaTeX2e documents, for example, everything developed for the PDF tagging project which has the goal to enable LaTeX to easily and automatically produce tagged PDF's. (https://www.latex-project.org/publications/indexbytopic/pdf/)

This new command has to come first in a LaTeX document, before \documentclass. It is used, as the name suggests, to set metadata about the entire document, but while the PDF tagging project is being worked on, it is also used to enable new code from this project.

If you use it without any option if will load the new PDF management code (currently in the pdfmanagement-testphase package) which is used for various PDF related tasks like transparency, spotcolors, XMP-metadata, changing the pdfversion and support for PDF standards. A visible effect is that it will change the default link colors of hyperref.

\DocumentMetadata has a number of keys which are described in documentmetadata-support-doc.pdf (and also in ltdocinit.pdf of the pdfmanagement-testphase package):

  • pdfversion: to set the pdfversion, e.g. pdfversion=2.0 (setting it to 1.2 as in your example is not something that I would recommend).
  • pdfstandard: to set a standard, e.g. pdfstandard=A-2b
  • lang: to set the /Lang key in the pdf catalog, e.g. lang=de
  • xmp: a boolean to suppress the XMP-metadata
  • colorprofiles: to add and configure color profiles (more info in l3pdfmeta.pdf)
  • uncompress: to produce an uncompressed PDF (it is a short hand for debug={uncompress}, but I need it so often ...).
  • backend: to set a backend/engine that can not be detected automatically, e.g. dvipdfmx.
  • debug: to set debug options

There are a few packages and classes which are not compatible with the PDF management, but for most documents it should be unproblematic to use \DocumentMetadata with the keys mentioned above.

This is not the case for last key testphase. It enables automation for tagging and all of this automation is currently in a prototype state and restricted to the use of standard classes (article, report, and book) and supports only a limited number of add-on packages (feedback about problems with other packages are welcome).

The testphase key accepts a comma list of values. Currently the main values are phase-I (a bit tagging), phase-II (more tagging), phase-III (needs LaTeX 2023-06-01 or newer and perhaps a latex-dev). But there are some more, e.g. with \DocumentMetadata{testphase={phase-III,math}} you can additionally load a prototype for math tagging. It is recommended to follow the LaTeX news and to check the latex-lab bundle if you want to test that.

2
  • Does testphase affect the memoir document class? If not, will it?
    – murray
    Commented Jul 11, 2023 at 19:37
  • @murray depending on the phase various latex internals are redefined and naturally this affects memoir. Currently memoir is not compatible as it redefines things back and then tagging breaks but we will try to help the maintainer to adapt memoir. Commented Jul 11, 2023 at 20:07
4

If everything else fails there's read-the-source-code in texdoc source2e.

screenshot of texdoc source2e

As suggested, proceed to texdoc documentmetadata-support.

screenshot of texdoc documentmetadata-support

So in this case the command will "set the PDF version explicitly" to 1.2.


Internally, you can guess that LaTeX simply forward it to the corresponding engine primitive:

texdoc pdftex screenshot

Technically, you can set whatever value you want and it seem to work anyway:

\DocumentMetadata{pdfversion=9.9}
\documentclass{article}
\begin{document}
hello world
\end{document}

gives a PDF file that starts with

%PDF-9.9
%¿÷¢þ

Realistically, according to Wikipedia the latest version is 2.0, and viewer compatibility varies.

See Why is 1.5 the default pdf version? - TeX - LaTeX Stack Exchange for the difference between PDF format versions and which version to pick.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .