Arch Linux User Repository

... /usr/share/doc/
... a standard place in the Linux filesystem 
... for Markdown (or more general non-man or -info) documentation 

Yeah sometimes there is no classical man page. Because nowadays many dont know/want to write them. But markdown is a very good powerfull choice also.

There can be a lot of very good stuff there, from simple .txt and .md, or even .pdf and .html . Sometimes even more usefull than a "proper" man page.

Try one of these

$ find /usr/share/doc/ -type f -iname '*ref*' -iname '*example*' -or -iname '*manual*' -or -iname  '*guide*' -or -iname '*tutorial*'

$ find /usr/share/doc/ -type f -iname '*news*' -or -iname  '*change*'

$ find /usr/share/doc/ -type f -iname '*readme*'

Sometimes they are not in /usr/share/doc/appXYZ, but directly put under /usr/share/appXYZ/foobar,

$ find /usr/share/ -type f -iname '*example*'  | grep  -i -v  "share.doc\|share.man"

All these simple plain text files are perfectly fine for offline reading without distractions. You can read them beautifully in the terminal with colors also.

For markdown files you can also use a colorizer like "mdcat/mdless". Or a very recommended general solution is "lesspipe" a companion to "less". Read the arch wiki.

You can even directly open hyperlinks (OSC*) http:// URL's from the terminal to the browser if needed.

man less:

  ^O^N  ^On         *  Search forward for (N-th) OSC8 hyperlink.
  ^O^P  ^Op         *  Search backward for (N-th) OSC8 hyperlink.
  ^O^L  ^Ol            Jump to the currently selected OSC8 hyperlink.

  ^O^O                 Open the currently selected OSC8 hyperlink.

and

   $ export LESS_OSC8_ANY="echo firefox %o"

Then try to open the http's in,

mdless /usr/share/doc/epubsynth/README.md

It is just that it's becoming a fashion for some developers to not write any manual or readme in plain text.

And then force a user to online visit a website, https://docs.mycoolclitool.com generated with sphinx or similar full of gimmicks and javascript animations.

It's absurd and distracting for simple TUI/CLI apps.

It's also the responsability of the Arch PKGBUILD creator to make sure these end up in /usr/share/docs. Many just throw them away.

@m040601

I've added /usr/share/doc/epubsynth/README.md to the package (and incremented pkgrel). Truth be told, I didn't know there was a standard place in the Linux filesystem for Markdown (or more general non-man or -info) documentation until I looked it up just now. Thanks for indirectly teaching me that, I suppose.

EDIT: I just saw your edits and added the license files too. Maybe down the line I'll add a changelog too, but I'd want to integrate that with my website if I do.

Very nice. Thank you for the tool and maintaing the PKGBUILD.

I'm always looking for and testing these CLI solutions for stiching by hand an epub file. Python seems a good fit.

$ tar tf epubsynth-v1.0.2.tar.gz

./README.md
./LICENSE.Apache-2.0
./epubsynth
....
.... etc

Ohh ... there is a nice big very helpfull README.md there. There is the help "-h" flag. But i think in the future i'll forget all these epub format options/specs/conventions to use it properly and need to read the README again.

But it doesnt land on my computer by default,

$ pacman -Ql epubsynth

epubsynth /usr/
epubsynth /usr/bin/
epubsynth /usr/bin/epubsynth
epubsynth /usr/lib/
epubsynth /usr/lib/python3.13/
epubsynth /usr/lib/python3.13/site-packages/
....
.... etc

And that's because the PKGBUILD uses the python/build/wheel system.

Could you enhance the PKGBUILD so that in the end it does land in,

/usr/share/doc/epubsynth/README.md
/usr/share/licenses/epubsynth/LICENSE

Something like for ex. adding the extra steps,

install -Dm644 "LICENSE-${pkgver}" "${pkgdir}/usr/share/licenses/${pkgname}/LICENSE"
install -Dm644 "README-${pkgver}.md" "${pkgdir}/usr/share/doc/${pkgname}/README.md"

Mmaybe in the future you'll also have a /usr/share/doc/epubsynth/NEWS or CHANGELOG)

Thanks in advance. Keep up the good work.