:bath: doc cleanup

docs/Appendix/Contribute.md

@@ -0,0 +1,66 @@
+# How to contribute
+
+## Questions and issues
+
+If you have a question about or a general issue while using this library,
+head over to the [discussions section](https://github.com/chillerlan/php-qrcode/discussions),
+create a new post and describe your issue as precise as possible, ideally add a code example (if applicable).
+Please don't just write "headline says all" because the reply will likely be similarly concise - help me (and others) help you!
+(just to clarify: the "general" does not mean general PHP support, in which case you're better off on
+[StackOverflow](https://stackoverflow.com/questions/tagged/php) or [/r/PHPhelp](https://www.reddit.com/r/PHPhelp/))
+
+
+## Bug reports
+
+So you found a bug or the library code is somehow misbehaving? That's great (well, not that great tho). In that case,
+please [open a bug report and FILL OUT THE ISSUE TEMPLATE](https://github.com/chillerlan/php-qrcode/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D)
+(i have to write that in all caps because nobody actually does it which usually leads to several avoidable follow-up questions that cost both of us precious time).
+Below an example of the bug report template (it's not that hard):
+
+**Describe the bug**
+
+A clear and concise description of what the bug is.
+
+**Steps to reproduce the behavior**
+- When i do ...
+- The code below ...
+- Error message: ...
+
+**Code sample**
+```php
+// your code here
+```
+
+**Expected behavior**
+
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+
+If applicable, add screenshots to help explain your problem.
+
+**Environment (please complete the following information):**
+- PHP version/OS: [e.g. 7.4.12, Ubuntu 20.04]
+- Library version: [e.g. 4.3.4]
+
+**Additional context**
+
+Add any other useful context about the problem.
+
+
+## Pull requests and bug fixes
+
+You want to contribute code to fix something or add a feature? Hey that's cool! However, there's a few things to keep in mind:
+
+- Please add a description of what the PR does or fixes and why it should be merged. If you're unsure, [open an issue](https://github.com/chillerlan/php-qrcode/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%5BENHANCEMENT%5D) before to gather feedback.
+- Make sure your branch is up-to-date/even with the upstream branch you're submitting your PR to.
+- Please try to adhere to the [*loosely outlined* coding standards](https://github.com/chillerlan/php-qrcode/discussions/60), or, in case you're using [PHPStorm](https://www.jetbrains.com/phpstorm/), make sure you're using [the supplied IDE profile](https://github.com/chillerlan/php-qrcode/tree/main/.idea).
+
+
+## Documentation
+
+The documentation is a work in progress - any suggestion and contribution is very welcome!
+
+
+The API documentation is auto generated with [phpDocumentor](https://www.phpdoc.org/) from the docblocks [in the PHP sources](https://github.com/chillerlan/php-qrcode/tree/main/src).
+The markdown sources for the [Read the Docs online manual](https://php-qrcode.readthedocs.io) are located in the [/docs directory](https://github.com/chillerlan/php-qrcode/tree/main/docs)

docs/Built-In-Output-QRMarkupHTML.md → docs/Built-In-Output/QRMarkupHTML.md

@@ -3,7 +3,7 @@
 [Class `QRMarkupHTML`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRMarkupHTML.php): HTML output
 
 This class is a cheap markup substitute for when SVG is not available or not an option (which was an issue before ca 2012).
-As a general rule: if you plan to display the QR Code in a web browser, you should be using the [SVG output](./Built-In-Output-QRMarkupSVG.md).
+As a general rule: if you plan to display the QR Code in a web browser, you should be using the [SVG output](../Built-In-Output/QRMarkupSVG.md).
 
 
 ## Example

docs/Readme.md

@@ -34,7 +34,8 @@ Follow these steps to create the user manual:
 [![pages-build-deployment](https://github.com/chillerlan/php-qrcode/actions/workflows/pages/pages-build-deployment/badge.svg?branch=gh-pages)](https://github.com/chillerlan/php-qrcode/actions/workflows/pages/pages-build-deployment)
 
 The API documentation can be auto generated with [phpDocumentor](https://www.phpdoc.org/).
-There is an [online version available](https://chillerlan.github.io/php-qrcode/) via the [`gh-pages` branch](https://github.com/chillerlan/php-qrcode/tree/gh-pages) that is [automatically deployed](https://github.com/chillerlan/php-qrcode/deployments) on each push to main.
+There is an [online version available](https://chillerlan.github.io/php-qrcode/) via the [`gh-pages` branch](https://github.com/chillerlan/php-qrcode/tree/gh-pages)
+that is [automatically deployed](https://github.com/chillerlan/php-qrcode/deployments) on each push to main.
 
 
 #### Run phpDocumentor locally
@@ -55,44 +56,31 @@ The markdown sources for the [Read the Docs online manual](https://php-qrcode.re
 
 
 ### Usage
-- [Overview](./Usage-Overview.md)
-- [Installation](./Usage-Installation.md)
-- [Quickstart](./Usage-Quickstart.md)
-- [Advanced usage](./Usage-Advanced-usage.md)
 
-### Built-In Output Modules
-
-- [QREps](./Built-In-Output-QREps.md)
-- [QRFpdf](./Built-In-Output-QRFpdf.md)
-- [QRGdImage](./Built-In-Output-QRGdImage.md)
-- [QRImagick](./Built-In-Output-QRImagick.md)
-- [QRMarkupHTML](./Built-In-Output-QRMarkupHTML.md)
-- [QRMarkupSVG](./Built-In-Output-QRMarkupSVG.md)
-- [QRString](./Built-In-Output-QRString.md)
-
-<!--
-### Customizing output
-- [Module values](./Customizing-Module-Values.md)
-- [Custom output interface](./Customizing-Custom-output-interface.md)
-- [QROutputAbstract](./Customizing-QROutputAbstract.md)
+- [Overview](./Usage/Overview.md)
+- [Installation](./Usage/Installation.md)
+- [Quickstart](./Usage/Quickstart.md)
+- [Advanced usage](./Usage/Advanced-usage.md)
+- [Configuration settings](./Usage/Configuration-settings.md)
 
 
-### Examples
-- [Built-in Output Interfaces](./Examples-Built-in.md)
-  -->
+### Built-In Output Modules
 
-### Public API
-- [`QRCode`](./API-QRCode.md)
-- [`QROptions`](./API-QROptions.md)
-- [`QROutputInterface`](./API-QROutputInterface.md)
-- [`QRMatrix`](./API-QRMatrix.md)
-- [`DecoderResult`](./API-DecoderResult.md)
+- [QREps](./Built-In-Output/QREps.md)
+- [QRFpdf](./Built-In-Output/QRFpdf.md)
+- [QRGdImage](./Built-In-Output/QRGdImage.md)
+- [QRImagick](./Built-In-Output/QRImagick.md)
+- [QRMarkupHTML](./Built-In-Output/QRMarkupHTML.md)
+- [QRMarkupSVG](./Built-In-Output/QRMarkupSVG.md)
+- [QRString](./Built-In-Output/QRString.md)
 
 
 ### Appendix
-- [Glossary](./Appendix-Appendix-URI-Content.md)
-- [Glossary](./Appendix-Terminology.md)
-- [License](./Appendix-License.rst)
+
+- [How to contribute](./Appendix/Contribute.md)
+- [Terminology](./Appendix/Terminology.md)
+- [Popular content and URI schemes](./Appendix/URI-Content.md)
+- [License](./Appendix/License.rst)
 
 
 ## License

docs/Usage-Advanced-usage.md → docs/Usage/Advanced-usage.md

@@ -3,6 +3,7 @@
 ## Configuration via `QROptions`
 
 The [`QROptions`](https://github.com/chillerlan/php-qrcode/blob/main/src/QROptions.php) class is a container based on [chillerlan/php-settings-container](https://github.com/chillerlan/php-settings-container) that behaves similar to a [`\stdClass`](https://www.php.net/manual/class.stdclass) object, but with fixed properties.
+A list with all available `QROptions` can be found under [cnfiguration settings](../Usage/Configuration-settings.md).
 
 ```php
 $options = new QROptions;
@@ -123,21 +124,13 @@ $qrcode->setOptions($options);
 
 ### Save to file
 
-Save the QR Code output to `/path/to/qrcode.svg`:
+You can specify an output file path in which the QR Code content is stored (this will override the `QROptions::$cachefile`
+setting, see [common output options](../Customizing/Common.md#save-to-file)):
 
 ```php
-$options->outputBase64 = false;
-$options->cachefile    = '/path/to/qrcode.svg';
+$qrcode->render($data, '/path/to/qrcode.svg');
 
-$qrcode->render($data);
-```
-
-Alternatively, you can specify an output path, which will override the `QROptions::$cachefile` setting:
-
-```php
-$qrcode->render($data, '/other/path/to/qrcode.svg');
-
-printf('<img src="%s" alt="QR Code" />', '/other/path/to/qrcode.svg');
+printf('<img src="%s" alt="QR Code" />', '/path/to/qrcode.svg');
 ```
 
 
@@ -158,21 +151,6 @@ $output = $qrcode->renderMatrix($matrix);
 $qrcode->renderMatrix($matrix, '/path/to/qrcode.svg');
 ```
 
-Manual invocation of a `QROutputInterface` to render a `QRMatrix` instance:
-
-```php
-class MyCustomOutput extends QRMarkupSVG{
-	// ...
-}
-
-$qrOutputInterface = new MyCustomOutput($options, $matrix);
-
-$output = $qrOutputInterface->dump()
-// render to file
-$qrOutputInterface->dump('/path/to/qrcode.svg');
-```
-
-
 ### Mixed mode
 
 Mixed mode QR Codes can be generated by adding several data segments:

docs/Usage/Configuration-settings.md

@@ -0,0 +1,432 @@
+# Configuration settings
+<!-- This file is auto generated from the source of QROptionsTrait.php -->
+## version
+
+QR Code version number
+
+`1 ... 40` or `Version::AUTO` (default)
+
+**See also:**
+
+- `\chillerlan\QRCode\Common\Version`
+
+
+## versionMin
+
+Minimum QR version
+
+if `QROptions::$version` is set to `Version::AUTO` (default: 1)
+
+
+## versionMax
+
+Maximum QR version
+
+if `QROptions::$version` is set to `Version::AUTO` (default: 40)
+
+
+## eccLevel
+
+Error correct level
+
+`EccLevel::X` where `X` is:
+
+- `L` =>  7% (default)
+- `M` => 15%
+- `Q` => 25%
+- `H` => 30%
+
+**See also:**
+
+- `\chillerlan\QRCode\Common\EccLevel`
+- [github.com/chillerlan/php-qrcode/discussions/160](https://github.com/chillerlan/php-qrcode/discussions/160)
+
+
+## maskPattern
+
+Mask Pattern to use (no value in using, mostly for unit testing purposes)
+
+`0 ... 7` or `MaskPattern::PATTERN_AUTO` (default)
+
+**See also:**
+
+- `\chillerlan\QRCode\Common\MaskPattern`
+
+
+## addQuietzone
+
+Add a "quiet zone" (margin) according to the QR code spec
+
+**See also:**
+
+- [www.qrcode.com/en/howto/code.html](https://www.qrcode.com/en/howto/code.html)
+
+
+## quietzoneSize
+
+Size of the quiet zone
+
+internally clamped to `0 ... $moduleCount / 2` (default: 4)
+
+
+## outputType
+
+The built-in output type
+
+- `QROutputInterface::MARKUP_SVG` (default)
+- `QROutputInterface::MARKUP_HTML`
+- `QROutputInterface::GDIMAGE_BMP`
+- `QROutputInterface::GDIMAGE_GIF`
+- `QROutputInterface::GDIMAGE_JPG`
+- `QROutputInterface::GDIMAGE_PNG`
+- `QROutputInterface::GDIMAGE_WEBP`
+- `QROutputInterface::STRING_TEXT`
+- `QROutputInterface::STRING_JSON`
+- `QROutputInterface::IMAGICK`
+- `QROutputInterface::EPS`
+- `QROutputInterface::FPDF`
+- `QROutputInterface::CUSTOM`
+
+**See also:**
+
+- `\chillerlan\QRCode\Output\QREps`
+- `\chillerlan\QRCode\Output\QRFpdf`
+- `\chillerlan\QRCode\Output\QRGdImage`
+- `\chillerlan\QRCode\Output\QRImagick`
+- `\chillerlan\QRCode\Output\QRMarkupHTML`
+- `\chillerlan\QRCode\Output\QRMarkupSVG`
+- `\chillerlan\QRCode\Output\QRString`
+
+
+## outputInterface
+
+The FQCN of the custom `QROutputInterface`
+
+if `QROptions::$outputType` is set to `QROutputInterface::CUSTOM` (default: `null`)
+
+
+## returnResource
+
+Return the image resource instead of a render if applicable.
+
+- `QRGdImage`: `resource` (PHP < 8), `GdImage`
+- `QRImagick`: `Imagick`
+- `QRFpdf`:    `FPDF`
+
+This option overrides/ignores other output settings, such as `QROptions::$cachefile`
+and `QROptions::$outputBase64`. (default: `false`)
+
+**See also:**
+
+- `\chillerlan\QRCode\Output\QROutputInterface::dump()`
+
+
+## cachefile
+
+Optional cache file path `/path/to/cache.file`
+
+Please note that the `$file` parameter in `QRCode::render()` and `QRCode::renderMatrix()`
+takes precedence over the `QROptions::$cachefile` value. (default: `null`)
+
+**See also:**
+
+- `\chillerlan\QRCode\QRCode::render()`
+- `\chillerlan\QRCode\QRCode::renderMatrix()`
+
+
+## outputBase64
+
+Toggle base64 data URI or raw data output (if applicable)
+
+(default: `true`)
+
+**See also:**
+
+- `\chillerlan\QRCode\Output\QROutputAbstract::toBase64DataURI()`
+
+
+## eol
+
+Newline string
+
+(default: `PHP_EOL`)
+
+
+## bgColor
+
+Sets the image background color (if applicable)
+
+- `QRImagick`: defaults to `"white"`
+- `QRGdImage`: defaults to `[255, 255, 255]`
+- `QRFpdf`: defaults to blank internally (white page)
+
+
+
+## invertMatrix
+
+Whether to invert the matrix (reflectance reversal)
+
+(default: `false`)
+
+**See also:**
+
+- `\chillerlan\QRCode\Data\QRMatrix::invert()`
+
+
+## drawLightModules
+
+Whether to draw the light (false) modules
+
+(default: `true`)
+
+
+## drawCircularModules
+
+Specify whether to draw the modules as filled circles
+
+a note for `GdImage` output:
+
+if `QROptions::$scale` is less than 20, the image will be upscaled internally, then the modules will be drawn
+using `imagefilledellipse()` and then scaled back to the expected size
+
+No effect in: `QREps`, `QRFpdf`, `QRMarkupHTML`
+
+**See also:**
+
+- [php.net: `\imagefilledellipse()`](https://www.php.net/manual/function.imagefilledellipse)
+- [github.com/chillerlan/php-qrcode/issues/23](https://github.com/chillerlan/php-qrcode/issues/23)
+- [github.com/chillerlan/php-qrcode/discussions/122](https://github.com/chillerlan/php-qrcode/discussions/122)
+
+
+## circleRadius
+
+Specifies the radius of the modules when `QROptions::$drawCircularModules` is set to `true`
+
+(default: 0.45)
+
+
+## keepAsSquare
+
+Specifies which module types to exclude when `QROptions::$drawCircularModules` is set to `true`
+
+(default: `[]`)
+
+
+## connectPaths
+
+Whether to connect the paths for the several module types to avoid weird glitches when using gradients etc.
+
+**See also:**
+
+- [github.com/chillerlan/php-qrcode/issues/57](https://github.com/chillerlan/php-qrcode/issues/57)
+
+
+## excludeFromConnect
+
+Specify which paths/patterns to exclude from connecting if `QROptions::$connectPaths` is set to `true`
+
+
+## moduleValues
+
+Module values map
+
+- `QRImagick`, `QRMarkupHTML`, `QRMarkupSVG`: #ABCDEF, cssname, rgb(), rgba()...
+- `QREps`, `QRFpdf`, `QRGdImage`: `[R, G, B]` // 0-255
+- `QREps`: `[C, M, Y, K]` // 0-255
+
+**See also:**
+
+- `\chillerlan\QRCode\Output\QROutputAbstract::setModuleValues()`
+
+
+## addLogoSpace
+
+Toggles logo space creation
+
+**See also:**
+
+- `\chillerlan\QRCode\QRCode::addMatrixModifications()`
+- `\chillerlan\QRCode\Data\QRMatrix::setLogoSpace()`
+
+
+## logoSpaceWidth
+
+Width of the logo space
+
+if only `QROptions::$logoSpaceWidth` is given, the logo space is assumed a square of that size
+
+
+## logoSpaceHeight
+
+Height of the logo space
+
+if only `QROptions::$logoSpaceHeight` is given, the logo space is assumed a square of that size
+
+
+## logoSpaceStartX
+
+Optional horizontal start position of the logo space (top left corner)
+
+
+## logoSpaceStartY
+
+Optional vertical start position of the logo space (top left corner)
+
+
+## scale
+
+Pixel size of a QR code module
+
+
+## imageTransparent
+
+Toggle transparency
+
+- `QRGdImage` and `QRImagick`: the given `QROptions::$transparencyColor` is set as transparent
+
+**See also:**
+
+- [github.com/chillerlan/php-qrcode/discussions/121](https://github.com/chillerlan/php-qrcode/discussions/121)
+
+
+## transparencyColor
+
+Sets a transparency color for when `QROptions::$imageTransparent` is set to `true`.
+
+Defaults to `QROptions::$bgColor`.
+
+- `QRGdImage`: `[R, G, B]`, this color is set as transparent in `imagecolortransparent()`
+- `QRImagick`: `"color_str"`, this color is set in `Imagick::transparentPaintImage()`
+
+
+**See also:**
+
+- [php.net: `\imagecolortransparent()`](https://www.php.net/manual/function.imagecolortransparent)
+- [php.net: `\Imagick::transparentPaintImage()`](https://www.php.net/manual/imagick.transparentpaintimage)
+
+
+## quality
+
+Compression quality
+
+The given value depends on the used output type:
+
+- `QROutputInterface::GDIMAGE_BMP`:  `[0...1]`
+- `QROutputInterface::GDIMAGE_JPG`:  `[0...100]`
+- `QROutputInterface::GDIMAGE_WEBP`: `[0...9]`
+- `QROutputInterface::GDIMAGE_PNG`:  `[0...100]`
+- `QROutputInterface::IMAGICK`:      `[0...100]`
+
+**See also:**
+
+- [php.net: `\imagebmp()`](https://www.php.net/manual/function.imagebmp)
+- [php.net: `\imagejpeg()`](https://www.php.net/manual/function.imagejpeg)
+- [php.net: `\imagepng()`](https://www.php.net/manual/function.imagepng)
+- [php.net: `\imagewebp()`](https://www.php.net/manual/function.imagewebp)
+- [php.net: `\Imagick::setImageCompressionQuality()`](https://www.php.net/manual/imagick.setimagecompressionquality)
+
+
+## imagickFormat
+
+Imagick output format
+
+**See also:**
+
+- [php.net: `\Imagick::setImageFormat()`](https://www.php.net/manual/imagick.setimageformat)
+- [www.imagemagick.org/script/formats.php](https://www.imagemagick.org/script/formats.php)
+
+
+## cssClass
+
+A common css class
+
+
+## markupDark
+
+Markup substitute for dark (CSS value)
+
+
+## markupLight
+
+Markup substitute for light (CSS value)
+
+
+## svgAddXmlHeader
+
+Whether to add an XML header line or not, e.g. to embed the SVG directly in HTML
+
+`<?xml version="1.0" encoding="UTF-8"?>`
+
+
+## svgOpacity
+
+SVG path opacity
+
+Sets the value for the SVG "fill-opacity" on a `<path>` element. Only in effect when non-empty values
+for `QROptions::$markupDark` and `QROptions::$markupLight` are given.
+The opacity value is the same for all paths - please use CSS for more sophisticated implementations.
+
+
+## svgDefs
+
+Anything in the SVG `<defs>` tag
+
+**See also:**
+
+- [developer.mozilla.org/en-US/docs/Web/SVG/Element/defs](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/defs)
+
+
+## svgPreserveAspectRatio
+
+Sets the value for the "preserveAspectRatio" on the `<svg>` element
+
+**See also:**
+
+- [developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio)
+
+
+## textDark
+
+String substitute for dark
+
+
+## textLight
+
+String substitute for light
+
+
+## textLineStart
+
+An optional line prefix, e.g. empty space to align the QR Code in a console
+
+
+## jsonAsBooleans
+
+Whether to return matrix values in JSON as booleans or `$M_TYPE` integers
+
+
+## fpdfMeasureUnit
+
+Measurement unit for `FPDF` output: pt, mm, cm, in (defaults to "pt")
+
+**See also:**
+
+- `FPDF::__construct()`
+
+
+## readerUseImagickIfAvailable
+
+Use Imagick (if available) when reading QR Codes
+
+
+## readerGrayscale
+
+Grayscale the image before reading
+
+
+## readerIncreaseContrast
+
+Increase the contrast before reading
+
+note that applying contrast works different in GD and Imagick, so mileage may vary
+

docs/Usage-Quickstart.md → docs/Usage/Quickstart.md

@@ -35,7 +35,7 @@ header('Content-type: image/svg+xml'); // the image type is SVG by default
 echo (new QRCode($options))->render($data);
 ```
 
-See [Advanced usage](./Usage-Advanced-usage.md) for a more in-depth usage guide.
+See [Advanced usage](../Usage/Advanced-usage.md) for a more in-depth usage guide.
 Also, have a look [in the examples folder](https://github.com/chillerlan/php-qrcode/tree/main/examples) for some more usage examples.
 
 

docs/index.rst

@@ -1,10 +1,14 @@
 .. php-qrcode documentation master file, created by sphinx-quickstart on Sun Jul  9 21:45:56 2023.
+   markdown-rst converter: https://pandoc.org/try/
 
 =================
 PHP-QRCode Manual
 =================
 
-Edition for `chillerlan/php-qrcode <https://github.com/chillerlan/php-qrcode/>`__  [|version|]. Updated on |today|.
+User manual for `chillerlan/php-qrcode <https://github.com/chillerlan/php-qrcode/>`__  [|version|]. Updated on |today|.
+
+The phpDocumentor API documentation can be found at `chillerlan.github.io/php-qrcode <https://chillerlan.github.io/php-qrcode/>`__.
+
 
 This work is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) License.
 
@@ -12,38 +16,30 @@ This work is licensed under the Creative Commons Attribution 4.0 International (
    :maxdepth: 3
    :caption: Usage
 
-   Usage-Overview.md
-   Usage-Installation.md
-   Usage-Quickstart.md
-   Usage-Advanced-usage.md
+   Usage/Overview.md
+   Usage/Installation.md
+   Usage/Quickstart.md
+   Usage/Advanced-usage.md
+   Usage/Configuration-settings.md
 
 .. toctree::
    :maxdepth: 3
    :caption: Built-In Output Modules
 
-   Built-In-Output-QREps.md
-   Built-In-Output-QRFpdf.md
-   Built-In-Output-QRGdImage.md
-   Built-In-Output-QRImagick.md
-   Built-In-Output-QRMarkupHTML.md
-   Built-In-Output-QRMarkupSVG.md
-   Built-In-Output-QRString.md
-
-.. toctree::
-   :maxdepth: 3
-   :caption: Public API
-
-   API-QRCode.md
-   API-QROptions.md
-   API-QROutputInterface.md
-   API-QRMatrix.md
-   API-DecoderResult.md
+   Built-In-Output/QREps.md
+   Built-In-Output/QRFpdf.md
+   Built-In-Output/QRGdImage.md
+   Built-In-Output/QRImagick.md
+   Built-In-Output/QRMarkupHTML.md
+   Built-In-Output/QRMarkupSVG.md
+   Built-In-Output/QRString.md
 
 .. toctree::
    :maxdepth: 3
    :caption: Appendix
 
-   Appendix-Terminology.md
-   Appendix-URI-Content.md
-   Appendix-License.md
+   Appendix/Contribute.md
+   Appendix/Terminology.md
+   Appendix/URI-Content.md
+   Appendix/License.md