FPDF: Document pdf.page, warn against modifying manually (#1325)

docs/DocumentOutlineAndTableOfContents.md

@@ -112,3 +112,8 @@ For example, the [`test_simple_outline`](https://github.com/py-pdf/fpdf2/blob/ma
 
 Similarly, [`test_html_toc`](https://github.com/py-pdf/fpdf2/blob/master/test/outline/test_outline_html.py)
 generates [test_html_toc.pdf](https://github.com/py-pdf/fpdf2/blob/5453422bf560a909229c82e53eb516e44fea1817/test/outline/test_html_toc.pdf).
+
+---
+
+## Manually Adjusting `pdf.page`
+Setting `pdf.page` manually may result in unexpected behavior. `pdf.add_page()` takes special care to ensure the page's content stream matches fpdf's instance attributes. Manually setting the page does not.

fpdf/fpdf.py

@@ -268,6 +268,11 @@ def __init__(
         but is less compatible with the PDF spec.
         """
         self.page = 0  # current page number
+        """
+        Note: Setting the page manually may result in unexpected behavior.
+        `pdf.add_page()` takes special care to ensure the page's content stream
+        matches fpdf's instance attributes. Manually setting the page does not.
+        """
         # array of PDFPage objects starting at index 1:
         self.pages: Dict[int, PDFPage] = {}
         self.fonts = {}  # map font string keys to an instance of CoreFont or TTFFont