===================
Document versioning
===================


.. note::

   Previous to version 4.0, there was no distinction between a document file
   and a document version. In addition, each document version had a 1 to 1
   relationship to a document file. That relationship extended to the pages
   and their layout.


Every time a :doc:`document file <files>` is upload, a corresponding
document version object is created. Document versions act like a "view" that
presents the pages of document files to the end user in a specific layout.


Page composition
================

.. versionadded:: 4.0

Since document versions and their pages are nothing more than pointers,
they can be modified without affecting their underlying source.

Document version pages can disabled, enabled, appended, removed, or even
reordered. All of this is achieved in a non destructive way (the original
uploaded file is never changed in any way), all of the changes happen only
at the application level for the document version.

There is no limit to the number of versions a document can have. Document
versions can also be deleted in any order and at any time.

Although many versions for a single document, only one version can be marked
as the active version.


Transformations
===============

Transformations can be applied to document version
pages as they can be applied to document file pages. However, since
document file pages are the source for the document version pages,
transformations applied to a document file page will be reflected on any
document version page, transformations applied a document version page
will not be reflected on the source document version file.


Downloads
=========

Since document versions are virtual objects, they cannot be downloaded.
Instead document versions are exported as a PDF and this PDF representation
of the document version is then downloaded.
