docs: explain settings

.gitignore

@@ -1 +1,3 @@
-__pycache__
+__pycache__
+venv
+.idea

README.md

@@ -1,6 +1,10 @@
 # ASN labels for Paperless-ngx on Avery labels 
 
-The [recommended workflow](https://docs.paperless-ngx.com/usage/#usage-recommended-workflow) of [Paperless-ngx](https://docs.paperless-ngx.com/) uses QR codes for ASN (archive serial number) labels. This script helps creating them using Python. It outputs a PDF for printing on the label sheets. Make sure to set print size to 100%, not _fit to page_ or similar.
+The [recommended workflow](https://docs.paperless-ngx.com/usage/#usage-recommended-workflow) of [Paperless-ngx](https://docs.paperless-ngx.com/) uses QR codes for ASN (archive serial number) labels.
+
+![Single label](docs/single-label.svg)
+
+This script helps creating them using Python. It outputs a PDF for printing on the label sheets. Make sure to set print size to 100%, not _fit to page_ or similar.
 
 Other Avery (or competitor's) label sizes can be added to `labelInfo` in `AveryLabels.py`. All other settings are configured at the top part of `main.py`.
 
@@ -17,6 +21,32 @@ labelsToPrint = 1
 positionHelper = True
 ```
 
+## Settings
+
+Configurations available in `main.py`:
+
+* `labelForm`: Select your label sheet version from the `labelInfo` list in `AveryLabels.py`.
+* `mode`:
+  * `qr`: Print a QR code and a text next to it showing the ASN.
+  * `text`: Print a free text on the label.
+* `text`: The free text used for `mode = text`.
+* `subLabelsX`/`subLabelsX`: Print multiple labels on a single cutout of a label sheet.
+                             This is helpful for small label sizes even though your physical label cutout sizes are bigger.
+                             Use a steel ruler and a sharp box cutter knife after printing to split up the labels.
+* `firstASNOnSheet`: The first ASN number that is/has been printed on the current sheet. Set to `1` on your initial sheet.
+* `labelsAlreadyPrinted`: If you have already printed a some labels on the current sheet, use this to skip overwriting them.
+* `labelsCorrupted`: Due to misprints or other reason, some labels on the current sheet might have gotten corrupted. This skips the unusable labels.
+* `labelsToPrint`: How many labels you want to print now.
+
+More settings:
+* `debug`: For initial calibration, a solid border line will be printed that should line up with the cutouts on your sheet. In `mode = text`, label text will be ascending numbers.
+
+  ![debug.svg](docs/debug.svg)
+
+* `positionHelper`: Small dots will be printed in the corner of (sub-)labels. Useful  as subtle sublabel cutting guides.
+
+  ![position-helper.svg](docs/position-helper.svg)
+
 # Credits
 
 This is based on the [work from timrprobocom](https://gist.github.com/timrprobocom/3946aca8ab75df8267bbf892a427a1b7)

docs/debug.svg

@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="49.787998mm"
+   height="46.487999mm"
+   viewBox="0 0 49.787998 46.487999"
+   version="1.1"
+   id="svg1"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <defs
+     id="defs1" />
+  <g
+     id="layer3">
+    <rect
+       style="fill:#ffffff;stroke-width:0.397175"
+       id="rect1"
+       width="49.787998"
+       height="46.487999"
+       x="0"
+       y="0" />
+  </g>
+  <g
+     id="layer1"
+     transform="translate(-82.020829,-127.26457)">
+    <g
+       id="g1"
+       transform="translate(1.9999049,1.9998973)">
+      <path
+         id="path51"
+         d="m 82.064926,148.50867 h 45.699994 v -21.2 H 82.064926 Z"
+         style="fill:none;stroke:#000000;stroke-width:0.0881944;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         id="path52"
+         d="m 92.858243,133.60833 v -0.7276 h -1.314649 v -0.339 l 1.384929,-1.96371 h 0.30179 v 1.96371 h 0.409277 v 0.339 h -0.409277 v 0.7276 z m 0,-1.0666 v -1.36839 l -0.946713,1.36839 z m 2.564184,1.0666 h -0.37207 v -2.37298 c -0.09095,0.0858 -0.209807,0.17156 -0.355534,0.25631 -0.143661,0.0858 -0.272852,0.1509 -0.388607,0.19431 v -0.35967 c 0.206706,-0.0992 0.38654,-0.21704 0.541569,-0.35553 0.157096,-0.14056 0.268718,-0.27492 0.334863,-0.40515 h 0.239779 z m 0,0"
+         style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.352778"
+         aria-label="41" />
+      <path
+         id="path53"
+         d="m 92.858243,144.2082 v -0.7276 h -1.314649 v -0.339 l 1.384929,-1.9637 h 0.30179 v 1.9637 h 0.409277 v 0.339 h -0.409277 v 0.7276 z m 0,-1.0666 v -1.36839 l -0.946713,1.36839 z m 3.118155,0.70693 v 0.35967 h -2.005045 c -0.0031,-0.0909 0.0124,-0.17777 0.04548,-0.26045 0.04961,-0.13436 0.130225,-0.26872 0.243913,-0.40101 0.112654,-0.13229 0.274918,-0.28525 0.487825,-0.45888 0.327629,-0.26975 0.549838,-0.48369 0.665593,-0.64079 0.115755,-0.15916 0.173632,-0.31006 0.173632,-0.45062 0,-0.14573 -0.05271,-0.26975 -0.157096,-0.37207 -0.10542,-0.10129 -0.242879,-0.15296 -0.413411,-0.15296 -0.179834,0 -0.322461,0.0537 -0.429948,0.16123 -0.107487,0.10749 -0.161231,0.25631 -0.161231,0.44648 l -0.384472,-0.0372 c 0.02687,-0.28629 0.12609,-0.50437 0.297656,-0.65319 0.170532,-0.14883 0.398942,-0.22325 0.686263,-0.22325 0.291455,0 0.521932,0.0816 0.690397,0.24392 0.170532,0.16019 0.256315,0.35863 0.256315,0.59531 0,0.12196 -0.0248,0.24184 -0.07441,0.35967 -0.04961,0.11575 -0.132291,0.23874 -0.248047,0.36793 -0.115755,0.13023 -0.307991,0.30799 -0.574642,0.5333 -0.223242,0.18811 -0.366902,0.31626 -0.429947,0.38448 -0.06408,0.0661 -0.115756,0.13229 -0.157097,0.19843 z m 0,0"
+         style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.352778"
+         aria-label="42" />
+      <path
+         id="path54"
+         d="m 115.70852,133.60833 v -0.7276 h -1.31465 v -0.339 l 1.38493,-1.96371 h 0.30179 v 1.96371 h 0.40928 v 0.339 h -0.40928 v 0.7276 z m 0,-1.0666 v -1.36839 l -0.94671,1.36839 z m 1.16272,0.26458 0.37207,-0.0496 c 0.0434,0.21291 0.11679,0.36587 0.21911,0.45889 0.10129,0.091 0.22738,0.13643 0.37621,0.13643 0.17363,0 0.32039,-0.06 0.44235,-0.18191 0.12092,-0.12092 0.1819,-0.27078 0.1819,-0.45061 0,-0.17054 -0.0568,-0.3111 -0.1695,-0.42168 -0.11059,-0.10956 -0.25218,-0.16537 -0.42582,-0.16537 -0.0692,0 -0.15606,0.0145 -0.26045,0.0413 l 0.0413,-0.32659 c 0.0248,0.003 0.0434,0.004 0.0579,0.004 0.15917,0 0.30283,-0.0413 0.42995,-0.12402 0.12609,-0.0827 0.19017,-0.21084 0.19017,-0.38447 0,-0.13436 -0.0475,-0.24598 -0.14056,-0.33487 -0.091,-0.0909 -0.20981,-0.13642 -0.35553,-0.13642 -0.14676,0 -0.26769,0.0455 -0.36381,0.13642 -0.0971,0.0909 -0.15916,0.22738 -0.18603,0.40928 l -0.37207,-0.0661 c 0.0465,-0.25011 0.14986,-0.44338 0.31006,-0.57877 0.16226,-0.13746 0.3638,-0.20671 0.60358,-0.20671 0.16536,0 0.31626,0.0362 0.45475,0.10749 0.14056,0.0692 0.24598,0.16536 0.31833,0.28939 0.0744,0.12195 0.11162,0.25114 0.11162,0.3886 0,0.1323 -0.0362,0.25218 -0.10749,0.35967 -0.0692,0.10749 -0.1726,0.19327 -0.31006,0.25632 0.1788,0.0413 0.31833,0.12712 0.41755,0.25631 0.0992,0.13023 0.14883,0.29249 0.14883,0.48783 0,0.26458 -0.0971,0.48989 -0.28939,0.67386 -0.19327,0.185 -0.43718,0.27698 -0.73174,0.27698 -0.26458,0 -0.48576,-0.0785 -0.66146,-0.23564 -0.17673,-0.15916 -0.27698,-0.36587 -0.30179,-0.62012 z m 0,0"
+         style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.352778"
+         aria-label="43" />
+      <path
+         id="path55"
+         d="m 115.70852,144.2082 v -0.7276 h -1.31465 v -0.339 l 1.38493,-1.9637 h 0.30179 v 1.9637 h 0.40928 v 0.339 h -0.40928 v 0.7276 z m 0,-1.0666 v -1.36839 l -0.94671,1.36839 z m 2.35335,1.0666 v -0.7276 h -1.31465 v -0.339 l 1.38493,-1.9637 h 0.30179 v 1.9637 h 0.40927 v 0.339 h -0.40927 v 0.7276 z m 0,-1.0666 v -1.36839 l -0.94671,1.36839 z m 0,0"
+         style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.352778"
+         aria-label="44" />
+      <path
+         id="path56"
+         d="m 82.064926,169.70868 h 45.699994 v -21.2 H 82.064926 Z"
+         style="fill:none;stroke:#000000;stroke-width:0.0881944;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         id="path57"
+         d="m 92.858243,154.80911 v -0.72761 h -1.314649 v -0.339 l 1.384929,-1.9637 h 0.30179 v 1.9637 h 0.409277 v 0.339 h -0.409277 v 0.72761 z m 0,-1.06661 v -1.36839 l -0.946713,1.36839 z m 1.162719,0.27286 0.388607,-0.0331 c 0.02997,0.19017 0.09715,0.33383 0.202572,0.42995 0.104386,0.0941 0.23151,0.14056 0.380338,0.14056 0.1788,0 0.330729,-0.0672 0.454753,-0.20257 0.124023,-0.13436 0.186035,-0.31419 0.186035,-0.53744 0,-0.21187 -0.05994,-0.37827 -0.177767,-0.50022 -0.118856,-0.12403 -0.274919,-0.18604 -0.467155,-0.18604 -0.121956,0 -0.230477,0.0279 -0.326595,0.0827 -0.09715,0.0558 -0.172599,0.12609 -0.227376,0.21084 l -0.347266,-0.0455 0.293522,-1.55443 h 1.504818 v 0.35553 h -1.207162 l -0.165364,0.81443 c 0.181901,-0.1261 0.373104,-0.19017 0.574642,-0.19017 0.264583,0 0.487825,0.093 0.669726,0.27698 0.181901,0.1819 0.272852,0.41651 0.272852,0.7028 0,0.27595 -0.08061,0.51263 -0.239779,0.71107 -0.19637,0.24805 -0.461987,0.37207 -0.797884,0.37207 -0.275952,0 -0.500228,-0.0765 -0.673861,-0.23151 -0.173632,-0.1571 -0.272851,-0.36174 -0.297656,-0.61598 z m 0,0"
+         style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.352778"
+         aria-label="45" />
+      <path
+         id="path58"
+         d="m 92.858243,165.40897 v -0.72761 h -1.314649 v -0.33899 l 1.384929,-1.96371 h 0.30179 v 1.96371 h 0.409277 v 0.33899 h -0.409277 v 0.72761 z m 0,-1.0666 v -1.3684 l -0.946713,1.3684 z m 3.09335,-1.2237 -0.37207,0.0289 c -0.03307,-0.14573 -0.08061,-0.25218 -0.14056,-0.31833 -0.09922,-0.10439 -0.223242,-0.1571 -0.37207,-0.1571 -0.118856,0 -0.222208,0.0331 -0.310058,0.0992 -0.118856,0.0858 -0.212907,0.21084 -0.28112,0.37621 -0.06615,0.16329 -0.101286,0.39584 -0.103353,0.69866 0.09095,-0.13746 0.200505,-0.23978 0.330729,-0.30592 0.129191,-0.0661 0.264583,-0.0992 0.405143,-0.0992 0.248047,0 0.458887,0.093 0.63252,0.27698 0.1757,0.18191 0.264583,0.41755 0.264583,0.70694 0,0.19017 -0.04134,0.3669 -0.124023,0.52916 -0.08268,0.1633 -0.196371,0.28836 -0.338998,0.37621 -0.14366,0.0879 -0.305924,0.13229 -0.487825,0.13229 -0.309025,0 -0.561206,-0.11369 -0.756543,-0.34313 -0.196371,-0.22841 -0.293522,-0.60462 -0.293522,-1.12861 0,-0.58705 0.107487,-1.01286 0.322461,-1.27745 0.190169,-0.23151 0.444417,-0.34726 0.764811,-0.34726 0.236678,0 0.430981,0.0682 0.58291,0.20257 0.153996,0.13229 0.24598,0.31626 0.276985,0.54984 z m -1.521353,1.30638 c 0,0.13022 0.02687,0.25425 0.08268,0.37207 0.05478,0.11575 0.130224,0.20464 0.227376,0.26458 0.09922,0.061 0.202572,0.0909 0.310059,0.0909 0.157096,0 0.291455,-0.063 0.405143,-0.19017 0.112654,-0.12609 0.169499,-0.29869 0.169499,-0.51676 0,-0.20877 -0.05684,-0.37311 -0.169499,-0.49196 -0.110588,-0.12092 -0.251148,-0.1819 -0.42168,-0.1819 -0.168465,0 -0.312125,0.061 -0.429948,0.1819 -0.115755,0.11885 -0.173632,0.27595 -0.173632,0.47129 z m 0,0"
+         style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.352778"
+         aria-label="46" />
+      <path
+         id="path59"
+         d="m 115.70852,154.80911 v -0.72761 h -1.31465 v -0.339 l 1.38493,-1.9637 h 0.30179 v 1.9637 h 0.40928 v 0.339 h -0.40928 v 0.72761 z m 0,-1.06661 v -1.36839 l -0.94671,1.36839 z m 1.18753,-1.56683 v -0.35966 h 1.95957 v 0.28938 c -0.19327,0.20671 -0.38448,0.48163 -0.57464,0.82269 -0.18811,0.339 -0.33383,0.68833 -0.43822,1.04593 -0.0744,0.25425 -0.12196,0.53227 -0.14056,0.8351 h -0.38447 c 0.005,-0.23978 0.0517,-0.5271 0.14056,-0.86403 0.0909,-0.339 0.2191,-0.66353 0.38447,-0.97566 0.16743,-0.31419 0.34726,-0.57877 0.53743,-0.79375 z m 0,0"
+         style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.352778"
+         aria-label="47" />
+      <path
+         id="path60"
+         d="m 115.70852,165.40897 v -0.72761 h -1.31465 v -0.33899 l 1.38493,-1.96371 h 0.30179 v 1.96371 h 0.40928 v 0.33899 h -0.40928 v 0.72761 z m 0,-1.0666 v -1.3684 l -0.94671,1.3684 z m 1.73323,-0.57878 c -0.15503,-0.0548 -0.26872,-0.13436 -0.34313,-0.23978 -0.0744,-0.10439 -0.11162,-0.22944 -0.11162,-0.3762 0,-0.22015 0.0786,-0.40515 0.23564,-0.55397 0.15917,-0.1509 0.37207,-0.22738 0.63666,-0.22738 0.26458,0 0.47645,0.0775 0.63665,0.23151 0.16226,0.15193 0.24391,0.33796 0.24391,0.5581 0,0.14056 -0.0372,0.26355 -0.11162,0.36794 -0.0744,0.10542 -0.18603,0.185 -0.33486,0.23978 0.18397,0.061 0.32453,0.15916 0.42168,0.29352 0.0992,0.13539 0.14883,0.29662 0.14883,0.48369 0,0.25942 -0.093,0.47853 -0.27699,0.65733 -0.1819,0.17673 -0.42375,0.26458 -0.72347,0.26458 -0.29766,0 -0.5395,-0.0878 -0.72347,-0.26458 -0.1819,-0.1788 -0.27285,-0.40101 -0.27285,-0.6656 0,-0.19843 0.0496,-0.3638 0.14883,-0.49609 0.0992,-0.13229 0.24081,-0.22324 0.42581,-0.27285 z m -0.0744,-0.62839 c 0,0.14366 0.0455,0.26045 0.13642,0.3514 0.093,0.0909 0.21498,0.13643 0.3638,0.13643 0.14263,0 0.26045,-0.0455 0.3514,-0.13643 0.091,-0.091 0.13643,-0.2005 0.13643,-0.33073 0,-0.13745 -0.0475,-0.25218 -0.14056,-0.34313 -0.0941,-0.093 -0.21084,-0.14056 -0.3514,-0.14056 -0.14366,0 -0.26252,0.0455 -0.35553,0.13643 -0.0941,0.091 -0.14056,0.2005 -0.14056,0.32659 z m -0.11989,1.39733 c 0,0.10749 0.0248,0.21084 0.0744,0.31006 0.0517,0.0992 0.12816,0.17674 0.22738,0.23151 0.0992,0.0527 0.20464,0.0786 0.31832,0.0786 0.1788,0 0.3266,-0.0558 0.44235,-0.1695 0.11576,-0.11575 0.17364,-0.26148 0.17364,-0.43821 0,-0.1788 -0.061,-0.3266 -0.1819,-0.44235 -0.11886,-0.11783 -0.26769,-0.17777 -0.44649,-0.17777 -0.17363,0 -0.31833,0.0579 -0.43408,0.17363 -0.11576,0.11576 -0.17363,0.26045 -0.17363,0.43408 z m 0,0"
+         style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0.352778"
+         aria-label="48" />
+    </g>
+  </g>
+</svg>

main.py

@@ -11,14 +11,14 @@ labelForm = 4778
 
 # mode "qr" prints a QR code and an ASN (archive serial number) text
 mode = "qr"
-subLabelsX = 2
-subLabelsY = 2
 
 # mode text prints a free text
 #mode = "text"
 #text="6y"
-#subLabelsX = 5
-#subLabelsY = 3
+
+# print multiple labels on a single cutout of a label sheet
+subLabelsX = 2
+subLabelsY = 2
 
 # what was the first ASN number printed on this sheet
 firstASNOnSheet = 42