Backport changes

README.md

@@ -5,7 +5,7 @@
 ## Features
 
 - Directory hierarchy support
-- Virtual directories: new books, authors, languages, decade issued, etc.
+- Virtual directories/shelves: new books, authors, languages, decade issued, etc.
 - ePUB format: metadata extraction, thumbnail generation
 - PDF format: metadata extraction, thumbnail generation
 - "Lazy" updating of feeds. `lib2opds` re-generates feeds only when new files are added into the library
@@ -18,23 +18,32 @@
 
 `lib2opds` is distributed on PyPI. The best way to install it is with [pipx](https://pipx.pypa.io).
 
-```
-pipx install lib2opds
+```shell
+$ pipx install lib2opds
 ```
 
 ## How to use
 
+Please read the manual frist:
+```shell
+$ man lib2opds
 ```
+Let's consider the following library directory:
+```shell
 $ tree ./test-library/
 ./test-library/
 ├── Linux
 │   └── How Linux Works - Brian Ward.epub
 └── Science Fiction
     ├── All Systems Red.epub
     └── I, Robot - Isaac Asimov.epub
-
+```
+Generate OPDS catalog and complimenting HTML site for the library directory: 
+```shell
 $ lib2opds --opds-base-uri "/opds/" --library-base-uri "/library/" --library-dir "./test-library" --opds-dir "./output" --generate-site-xslt
-
+```
+Get the following result:
+```shell
 $ tree ./output/
 ./output/
 
@@ -54,28 +63,25 @@ $ tree ./output/
 └── index.xml
 ```
 
-`/etc/lib2opds.ini` is used by default and options can be overridden via command line arguments.
+`/etc/lib2opds.ini` is used by default and options can be overridden via command line arguments. See `$ man 5 lib2opds.ini` for more details.
 
-Example of configuration file for Nginx:
+Now it is possible to serve it with any HTTP server. Example of configuration file for Nginx with HTTP Basic Authentication:
 
 ```nginx
 location /library {
-        alias /library-dir;
+        auth_basic  "Library Area";
+        auth_basic_user_file /etc/nginx/htpasswd;
+        alias /library-dir-path;
 }
 
 location /opds {
         auth_basic  "Library Area";
         auth_basic_user_file /etc/nginx/htpasswd;
-        alias /opds-dir;
+        alias /opds-dir-path;
         index index.xml;
 }
-
-location /opds/covers {
-        alias /opds-dir/covers;
-}
 ```
-
-Library location here is not protected with basic auth because of the bug in some e-book reader software.
+Notice: There might be issues with some e-book reader software because of the library location protected with basic auth.
 
 ## Sidecar files
 

lib2opds/__init__.py

@@ -1 +1 @@
-__version__ = "0.3.0"
+__version__ = "0.4.0"

man/lib2opds-sidecar-files.5

@@ -0,0 +1,44 @@
+.TH LIB2OPDS-SIDECAR-FILES 5
+.SH DESCRIPTION
+.BR lib2opds (1)
+detects sidecar files for the target e-book file and extracts metadata and cover from them.
+For example, in case of
+.BR some-book.epub
+e-book file lib2opds will try to check for
+.BR some-book.info
+and
+.BR some-book.cover
+files.
+.BR .cover
+is just an image file.
+.PP
+.BR .info
+sidecar files are basically INI-format files started with
+.BR [Publication]
+section.
+.PP
+The possible keys and their meanings are as follows:
+.TP
+.BR title
+title of the book
+.TP
+.BR authors
+comma-separated list of authors of the book
+.TP
+.BR description
+description of the book
+.TP
+.BR language
+language of the book
+.TP
+.BR issued
+when was the book issued?
+.TP
+.BR publisher
+What is publisher of the book
+.TP
+.BR identifier
+What is identifier of the book, e.g. ISBN
+.SH SEE ALSO
+.BR lib2opds (1),
+.BR lib2opds.ini (5)

man/lib2opds.1

@@ -0,0 +1,143 @@
+.TH LIB2OPDS 1
+.SH NAME
+lib2opds \- static OPDS catalog generator for ebook library
+.SH SYNOPSIS
+.SY lib2opds
+.OP options
+.OP \-\-help
+.OP \-\-version
+.YS
+.SH DESCRIPTION
+.B lib2opds
+generates OPDS catalog for local e-book library.
+Additionally, it can generate HTML output with both options: XLST client-side templating for OPDS/Atom XML output or separate HTML files generation.
+.SH OPTIONS
+.TP
+.BR \-\-help
+print a help message and exit
+.TP
+.BR \-\-version
+display version information and exit
+.TP
+.BR \-\-library-dir " "\fILIBRARY_DIR\fR
+directory with your books
+.TP
+.BR \-\-opds-dir " "\fIOPDS_DIR\fR
+target directory for OPDS feeds
+.TP
+.BR \-\-library-base-uri " "\fILIBRARY_BASE_URI\fR
+base URI for serving books from the library, for example https://your-domain.com/library
+.TP
+.BR \-\-opds-base-uri " "\fIOPDS_BASE_URI\fR
+base URI for OPDS, for example https://domain.example/opds
+.TP
+.BR \-\-library_title " "\fILIBRARY_TITLE\fR
+library title
+.TP
+.BR \-\-clear-opds-dir
+clear OPDS directory before generating result feeds
+.TP
+.BR \-\-invalidate-cache
+clear cache directory before generating result feeds
+.TP
+.BR \-\-generate-site
+generate static site additionally to OPDS catalog
+.TP
+.BR \-\-generate-site-xslt
+generate HTML output with help of XSLT client-side processing of OPDS catalog
+.TP
+.BR \-\-cache-dir " "\fICACHE_DIR\fR
+directory for caching ebook metadata
+.TP
+.BR \-c ", " \-\-config " "\fICONFIG\fR
+config path
+.TP
+.BR \-u ", " \-\-update
+force recreation of ODPS feeds
+.SH EXAMPLES
+Consider following directory with some structure and which contains ebook files:
+.PP
+.nf
+.RS
+$ tree ./test-library/
+./test-library/
+├── Linux
+│   └── How Linux Works - Brian Ward.epub
+└── Science Fiction
+    ├── All Systems Red.epub
+    └── I, Robot - Isaac Asimov.epub
+.RE
+.fi
+.PP
+Run
+.B lib2opds
+with the following options:
+.PP
+.nf
+.RS
+$ lib2opds --opds-base-uri "/opds/" --library-base-uri "/library/" --library-dir "./test-library" --opds-dir "./output" --generate-site-xslt
+.RE
+.fi
+.PP
+See the following output in the specified target directory for OPDS catalog:
+.PP
+.nf
+.RS
+$ tree ./output/
+./output/
+
+├── assets
+│   ├── acquisition-feed.xsl
+│   ├── navigation-feed.xsl
+│   └── style.css
+├── covers
+│   ├── a965b65e-85f9-4e98-a02b-4ff316869a2c.jpg
+│   └── d738ea6d-f205-45e6-b09d-17d9b95c0286.jpg
+├── feeds
+│   ├── 142ccd52-436c-402f-8094-524fb20af9d3.xml
+│   ├── 414562bf-c592-47f3-a94d-b01120ee22ca.xml
+│   ├── 44d48843-196b-409b-9bd9-67d928505121.xml
+...
+│   └── fab6423d-a3ea-4027-8d84-b372fbef4503.xml
+└── index.xml
+.RE
+.fi
+.PP
+.BR /etc/lib2opds.ini
+is used by default.
+Options specified in configuation file can be overridden via command line arguments.
+.PP
+Example of the Nginx configuration file:
+.PP
+.nf
+.RS
+location /library {
+        auth_basic  "Library Area";
+        auth_basic_user_file /etc/nginx/htpasswd;
+        alias /library-dir-path;
+}
+
+location /opds {
+        auth_basic  "Library Area";
+        auth_basic_user_file /etc/nginx/htpasswd;
+        alias /opds-dir-path;
+        index index.xml;
+}
+.RE
+.fi
+.PP
+Notice: There might be issues with some e-book reader software because of the library location protected with basic auth.
+.SH FILES
+.TP
+.BR /etc/lib2opds.ini
+Default system-wide configuration file. See
+.BR lib2opds.ini (5)
+for details on the syntax.
+.TP
+.BR "Sidecar files"
+lib2opds detects sidecar files for the target e-book file and extracts metadata and cover from them.
+.SH REPORTING BUGS
+Please use the bug tracker on https://\:github.com/\:oxdef/\:lib2opds/\:issues to report bugs and feature requests.
+.SH SEE ALSO
+.BR lib2opds.ini (5),
+.BR lib2opds-sidecar-files (5)

man/lib2opds.ini.5

@@ -0,0 +1,82 @@
+.TH LIB2OPDS.ini 5
+.SH NAME
+lib2opds.ini \- lib2opds configuration file
+.SH SYNOPSIS
+.SY /etc/lib2opds.ini
+.YS
+.SH DESCRIPTION
+.BR lib2opds (1)
+reads configuration options from the system-wide configuration file
+.BR /etc/lib2opds.ini
+, or the file specified with
+.BR \-c ", " \-\-config " "
+on the command  line.
+The  file is in the INI format and started with
+.BR [General]
+section.
+.PP
+The possible keys and their meanings are as follows:
+.TP
+.BR library_dir
+directory with your books
+.TP
+.BR opds_dir
+target directory for OPDS feeds
+.TP
+.BR library_base_uri
+base URI for serving books from the library, for example https://your-domain.com/library
+.TP
+.BR opds_base_uri
+base URI for OPDS, for example https://domain.example/opds
+.TP
+.BR root_filename
+root file name for the OPDS catalog, e.g. index.xml
+.TP
+.BR library_title
+title of the library, e.g. "My Library"
+.TP
+.BR cover_width
+width of cover images, e.g. 500 px
+.TP
+.BR cover_height
+height of cover images, e.g. 500 px
+.TP
+.BR cover_quality
+quality value for the result cover image file in JPEG format
+.TP
+.BR clear_opds_dir
+clear OPDS directory before generating result feeds
+.TP
+.BR generate_site
+generate static site additionally to OPDS catalog
+.TP
+.BR generate_site_xslt
+generate HTML output with help of XSLT client-side processing of OPDS catalog
+.TP
+.BR generate_issued_feed
+Should
+.B lib2opds
+generate the "Issued" feed? true/false
+.TP
+.BR generate_languages_feed
+Should
+.B lib2opds
+generate the "Languages" feed? true/false
+.BR generate_random_book_feed
+Should
+.B lib2opds
+generate the "Random" feed? true/false
+.TP
+.BR publication_freshness_days
+How many days should be from the adding of the ebook file to consider it new one, e.g. 14
+.TP
+.BR cache_dir
+directory for caching ebook metadata
+.SH FILES
+.TP
+.BR /etc/lib2opds.ini
+Default system-wide configuration file
+.SH SEE ALSO
+.BR lib2opds (1),
+.BR lib2opds-sidecar-files (5)
+

pyproject.toml

@@ -45,6 +45,11 @@ path = "lib2opds/__init__.py"
 [project.scripts]
 lib2opds = "lib2opds.__main__:cli"
 
+[tool.hatch.build.targets.wheel.shared-data]
+"man/lib2opds.1" = "share/man/man1/lib2opds.1"
+"man/lib2opds.ini.5" = "share/man/man5/lib2opds.ini.5"
+"man/lib2opds-sidecar-files.5" = "share/man/man5/lib2opds-sidecar-files.5"
+
 [tool.black]
 line-length = 90
 target-version = ['py311']