DOC: Minor improvements

docs/dev/deprecations.md

@@ -4,7 +4,7 @@ pypdf strives to be an excellent library for its current users and for new
 ones. We are careful with introducing potentially breaking changes, but we
 will do them if they provide value for the community on the long run.
 
-We hope and think that deprecations will not happen soon again. If they do,
+We hope and think that deprecations will not happen frequently. If they do,
 users can rely on the following procedure.
 
 ## Semantic Versioning

docs/dev/intro.md

@@ -35,7 +35,7 @@ Git is a command line application for version control. If you don't know it,
 you can [play ohmygit](https://ohmygit.org/) to learn it.
 
 GitHub is the service where the pypdf project is hosted. While git is free and
-open source, GitHub is a paid service by Microsoft - but for free in lot of
+open source, GitHub is a paid service by Microsoft, but free in a lot of
 cases.
 
 [pre-commit](https://pypi.org/project/pre-commit/) is a command line application
@@ -47,7 +47,7 @@ you `git commit`.
 ## Commit Messages
 
 Having a clean commit message helps people to quickly understand what the commit
-was about, without actually looking at the changes. The first line of the
+is about, without actually looking at the changes. The first line of the
 commit message is used to [auto-generate the CHANGELOG](https://github.com/py-pdf/pypdf/blob/main/make_release.py).
 For this reason, the format should be:
 
@@ -67,14 +67,14 @@ The `PREFIX` can be:
    A bug is always an issue for pypdf users - test code or CI that was fixed is
    not considered a bug here.
 * `ENH`: A new feature! Describe in the body what it can be used for.
-* `DEP`: A deprecation - either marking something as "this is going to be removed"
+* `DEP`: A deprecation. Either marking something as "this is going to be removed"
    or actually removing it.
 * `PI`: A performance improvement. This could also be a reduction in the
         file size of PDF files generated by pypdf.
 * `ROB`: A robustness change. Dealing better with broken PDF files.
 * `DOC`: A documentation change.
-* `TST`: Adding / adjusting tests.
-* `DEV`: Developer experience improvements - e.g. pre-commit or setting up CI
+* `TST`: Adding or adjusting tests.
+* `DEV`: Developer experience improvements, e.g. pre-commit or setting up CI.
 * `MAINT`: Quite a lot of different stuff. Performance improvements are for sure
            the most interesting changes in here. Refactorings as well.
 * `STY`: A style change. Something that makes pypdf code more consistent.

docs/dev/releasing.md

@@ -13,18 +13,18 @@ A `pypdf` release contains the following artifacts:
 `pypdf` should typically only be released by one of the core maintainers / the
 core maintainer. At the moment, this is Martin Thoma.
 
-Any owner of the py-pdf organization has also the technical permissions to
+Any owner of the py-pdf organization also has the technical permissions to
 release.
 
 ## How is it done?
 
 The release contains the following steps:
 
 1. Update the CHANGELOG.md and the _version.py via `python make_release.py`.
-   This also prepares the release commit message
+   This also prepares the release commit message.
 2. Create a release commit: `git commit -eF RELEASE_COMMIT_MSG.md`.
 3. Tag that commit: `git tag -s {{version}} -eF RELEASE_TAG_MSG.md`.
-4. Push both: `git push && git push --tags`
+4. Push both: `git push && git push --tags`.
 5. CI now builds a source and a wheels package which it pushes to PyPI. It also
    creates a GitHub release.
 
@@ -33,7 +33,7 @@ The release contains the following steps:
 ### The Release Tag
 
 * Use the release version as the tag name. No need for a leading "v".
-* Use the changelog entry as the body
+* Use the changelog entry as the body.
 
 
 ## When are releases done?

docs/dev/testing.md

@@ -5,11 +5,11 @@ pypdf uses [`pytest`](https://docs.pytest.org/en/7.1.x/) for testing.
 To run the tests you need to install the CI (Continuous Integration) requirements by running `pip install -r requirements/ci.txt` or
 `pip install -r requirements/ci-3.11.txt` if running Python ≥ 3.11.
 
-## De-selecting groups of tests
+## Deselecting groups of tests
 
 pypdf makes use of the following pytest markers:
 
-* `slow`: Tests that require more than 5 seconds
+* `slow`: Tests that require more than 5 seconds.
 * `samples`: Tests that require the [the `sample-files` git submodule](https://github.com/py-pdf/sample-files) to be initialized. As of October 2022, this is about 25 MB.
 * `enable_socket`: Tests that download PDF documents. They are stored locally and thus only need to be downloaded once. As of October 2022, this is about 200 MB.
   * To successfully run the tests, please download most of the documents beforehand: `python -c "from tests import download_test_pdfs; download_test_pdfs()"`
@@ -73,5 +73,5 @@ b) you can then install the version using pip from git:
 
 Example:
 ```
-pip install git+https://github.com/pubpub-zz/pypdf.git@iss2200
+pip3 install git+https://github.com/pubpub-zz/pypdf.git@iss2200
 ```

docs/user/add-watermark.md

@@ -1,4 +1,4 @@
-# Adding a Stamp/Watermark to a PDF
+# Adding a Stamp or Watermark to a PDF
 
 Adding stamps or watermarks are two common ways to manipulate PDF files.
 A stamp is adding something on top of the document, a watermark is in the
@@ -21,7 +21,7 @@ for page in writer.pages:
 writer.write("out.pdf")
 ```
 
-Else use `merge_transformed_page()` with `Transformation()` if you need to translate, rotate, scale, etc. the stamp before merging it to the content page.
+Otherwise use `merge_transformed_page()` with `Transformation()` if you need to translate, rotate, scale, etc. the stamp before merging it to the content page.
 
 ```python
 from pathlib import Path

docs/user/adding-pdf-annotations.md

@@ -304,7 +304,7 @@ with open("annotated-pdf.pdf", "wb") as fp:
 Text markup annotations refer to a specific piece of text within the document.
 
 Those are a bit more complicated as you need to know exactly where the text
-is. Those are the "Quad points".
+is, the so-called the "Quad points".
 
 ### Highlighting
 

docs/user/installation.md

@@ -6,18 +6,18 @@ There are several ways to install pypdf. The most common option is to use pip.
 
 pypdf requires Python 3.7+ to run.
 
-Typically Python comes with `pip`, a package installer. Using it you can
+Typically Python comes with `pip3`, a package installer. Using it you can
 install pypdf:
 
 ```bash
-pip install pypdf
+pip3 install pypdf
 ```
 
 If you are not a super-user (a system administrator / root), you can also just
 install pypdf for your current user:
 
 ```bash
-pip install --user pypdf
+pip3 install --user pypdf
 ```
 
 ### Optional dependencies
@@ -29,7 +29,7 @@ case for cryptography and image formats.
 If you simply want to install all optional dependencies, run:
 
 ```
-pip install pypdf[full]
+pip3 install pypdf[full]
 ```
 
 Alternatively, you can install just some:
@@ -39,13 +39,13 @@ will need to install some extra dependencies. Encryption using RC4 is supported
 using the regular installation.
 
 ```
-pip install pypdf[crypto]
+pip3 install pypdf[crypto]
 ```
 
 If you plan to use image extraction, you need Pillow:
 
 ```
-pip install pypdf[image]
+pip3 install pypdf[image]
 ```
 
 ## Python Version Support
@@ -69,5 +69,5 @@ Anaconda users can [install pypdf via conda-forge](https://anaconda.org/conda-fo
 In case you want to use the current version under development:
 
 ```bash
-pip install git+https://github.com/py-pdf/pypdf.git
+pip3 install git+https://github.com/py-pdf/pypdf.git
 ```

docs/user/merging-pdfs.md

@@ -63,7 +63,7 @@ writer.append(reader, "page 1 and 10", [0, 9])
 
 During merging, the relevant named destination will also imported.
 
-If you want to insert pages in the middle of the destination, use `merge` (which provides (insertion) position).
+If you want to insert pages in the middle of the destination, use `merge` (which provides an insertion position).
 You can insert the same page multiple times, if necessary even using a list-based syntax:
 
 ```python
@@ -126,7 +126,7 @@ Please note that if you clone an object, you will clone all the objects below as
 including the objects pointed by *IndirectObject*. Due to this, if you clone a page that
 includes some articles (`"/B"`), not only the first article, but also all the chained articles
 and the pages where those articles can be read will be copied.
-It means that you may copy lots of objects which will be saved in the output PDF as well.
+This means that you may copy lots of objects which will be saved in the output PDF as well.
 
 In order to prevent this, you can provide the list of fields in the dictionaries to be ignored:
 

docs/user/reading-pdf-annotations.md

@@ -31,7 +31,7 @@ for page in reader.pages:
             print(annotation)
 ```
 
-Reading the most common ones is described here.
+Examples of reading three of the most common annotations:
 
 ## Text
 

docs/user/streaming-data.md

@@ -3,7 +3,7 @@
 In some cases you might want to avoid saving things explicitly as a file
 to disk, e.g. when you want to store the PDF in a database or AWS S3.
 
-pypdf supports streaming data to a file-like object and here is how.
+pypdf supports streaming data to a file-like object:
 
 ```python
 from io import BytesIO

docs/user/viewer-preferences.md

@@ -1,14 +1,14 @@
 # Adding Viewer Preferences
 
-It is possible to set viewer preferences of the PDF file.
+It is possible to set viewer preferences of a PDF file.
 These properties are described in Section 12.2 of the [PDF 1.7 specification](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf).
 
 Note that the `/ViewerPreferences` dictionary does not exist by default.
 If it's not already present, it must be created by calling the `create_viewer_preferences` method
 of the `PdfWriter` object.
 
 If viewer preferences exist in a PDF file being read with `PdfReader`,
-you can access them as properties of the `viewer_preferences` properties.
+you can access them as properties of `viewer_preferences`.
 Otherwise, the `viewer_preferences` property will be set to `None`.
 
 ## Example
@@ -78,6 +78,6 @@ with open("output.pdf", "wb") as output_stream:
     writer.write(output_stream)
 ```
 
-(The names beginning with a slash character are part of the PDF file format. They are
+The names beginning with a slash character are part of the PDF file format. They are
 included here to aid to anyone searching pypdf documentation
-for these names from the PDF specification.)
+for these names from the PDF specification.