Package Details: automx2 2024.1-1

Git Clone URL: https://aur.archlinux.org/automx2.git (read-only, click to copy)
Package Base: automx2
Description: Mail User Agent (email client) configuration made easy
Upstream URL: https://github.com/rseichter/automx2
Licenses: GPL3
Submitter: Morbius
Maintainer: Morbius
Last Packager: Morbius
Votes: 1
Popularity: 0.26
First Submitted: 2024-02-19 10:25 (UTC)
Last Updated: 2024-02-21 09:03 (UTC)

Latest Comments

Morbius commented on 2024-02-20 08:05 (UTC) (edited on 2024-02-20 08:06 (UTC) by Morbius)

I didn't phrase my question clearly enough, but no matter. Future upstream releases will ship with bundled documentation, which I will then include in my AUR package.

By the way, the reason it was not previously included in automx2 releases is that locally stored docs can (and have) become stale when the online documentation changes.

m040601 commented on 2024-02-20 07:46 (UTC) (edited on 2024-02-20 08:22 (UTC) by m040601) 

What would you expect from an additional README file, seen from an Arch Linux perspective?

You are right that, in this particular case, and considering the current content of the README,

...
## Documentation

Detailed documentation is available in [HTML](https://rseichter.github.io/automx2/),
[PDF](https://github.com/rseichter/automx2/blob/master/docs/automx2.pdf) and
[other formats](https://github.com/rseichter/automx2/blob/master/docs).
....

one cannot expect much from the README. Except to tell you to go online and look for help. But that is just because the tool is shipped with absolutely no man page or help flag option.

But even so, why would you through the "README" to the trash in the PKGBUILD ? It is there, it was shipped. A README , if it is there, always belongs to /usr/share/doc no matter how poor it is. These are the AUR standards.

I wanted to keep things simple in the beginning.

You are already doing more than just "python setup ..." . And added extra files. You already have these 2 extra lines:

        install -D -m 0644 "${srcdir}/automx2.conf" "${pkgdir}/etc/automx2/automx2.conf"
        install -D -m 0644 "${srcdir}/automx2.service" "${pkgdir}/usr/lib/systemd/system/automx2.service"

Cant you put a third one ? Something like

        install -D -m 0644 "${srcdir}/README" "${pkgdir}/usr/share/doc/autoxm2/README"

What do I expect when I am using a new non trivial tool ?

I expect the same as when I type "man pacman", "man pacman.conf" or "git help" or I am inside my editor and type ":he vim".

I dont have to stop, open a web browser, and look for help on the Internet. I dont have to git clone the repo to have some sort of help file.

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

find /usr/share/doc/ -type f -iname '*.rst'

find /usr/share/doc/ -type d -iname '*examples*'

find /usr/share/doc/ -type d -iname '*html*'

As I said the docs are there, its just that the way he, the developer, packages everything for distribution dont include them. Forcing me to go online to read them.

It is just a matter of asking him to change a bit the Makefile and the python setup scripts for packaging.

Morbius commented on 2024-02-20 03:58 (UTC)

@m040601 This the first AUR package I have ever created, and I am grateful for suggestions regarding best practices and possible improvements. Version 2024.0 will follow, and I am also planning on adding a test stage to PKGBUILD. I wanted to keep things simple in the beginning.

As far as documentation is concerned, https://rseichter.github.io/automx2/ is the official "source of truth". What would you expect from an additional README file, seen from an Arch Linux perspective?

m040601 commented on 2024-02-20 03:39 (UTC)

Very interesting tool ! Thanks for the work providing this PKGBUILD. You even went to the trouble of adding the extra /etc/automx2/automx2.conf and the systemd service. Nice

I tested it and every thing seems to be working fine.

Reading the docs, today I finally learned how Mozilla Thunderbird and other do that autoconfiguration thing.

I didnt even know this was possible with an open source tool, that you can self host.

This avoid sending your email address to a third party. Very useful.

Two small questions about the version and docs.

2024-02-19 Ralph Seichter      o [master] {origin/master} {origin/HEAD} Improve Makefile
...
2024-02-19 Ralph Seichter      o <2024.0> Prepare release 2024.0
...
2022-05-20 Ralph Seichter      o <2022.1> Update release date
...

github also says,

TITLE     TYPE    TAG NAME  PUBLISHED
2024.0    Latest  2024.0    about 10 hours ago
2022.1            2022.1    about 1 year ago
2022.0            2022.0    about 1 year ago
2021.6            2021.6    about 2 years ago
2021.5            2021.5    about 2 years ago
2021.4            2021.4    about 2 years ago
2021.3.1          2021.3.1  about 2 years ago
2021.2            2021.2    about 2 years ago
2021.1            2021.1    about 2 years ago

So is this PKGBUILD installing the "2022" version ? Or will you be updating to the "2024" ?

About the docs,

pacman -Ql automx2  | grep -i "readme\|doc\|help\|man\|example" -

... sadly nothing

$ wget https://files.pythonhosted.org/packages/source/a/automx2/automx2-2022.1.tar.gz

$ tar tf automx2-2022.1.tar.gz

...
-rw-r--r--  0 ralph  staff   35149 Jan  7  2021 automx2-2022.1/LICENSE
-rw-r--r--  0 ralph  staff    2511 May 20  2022 automx2-2022.1/PKG-INFO
-rw-r--r--  0 ralph  staff    1822 May  5  2022 automx2-2022.1/README.md
....

So the developer at least ships the README. This is important. These kind of tools need locally offline docs/man/pages/help/examples for spending the necessary time to master them.

Can you please make sure it also lands in something like,

/usr/share/doc/automx2/README

Like you already do for the other extra files


        install -D -m 0644 "${srcdir}/automx2.conf" "${pkgdir}/etc/automx2/automx2.conf"
        install -D -m 0644 "${srcdir}/automx2.service" "${pkgdir}/usr/lib/systemd/system/automx2.service"

It's a pity the developer doesnt ship more docs in the tar.gz release. They are necessary, and he does have a lot on the repo. And he writes nicely explaining a lot of concepts and background

https://github.com/rseichter/automx2

....

├── CHANGELOG
├── contrib
│   ├── apache-sample.conf
│   ├── automx2-sample.conf
│   ├── automx2.service
│   ├── flask.sh
│   ├── mysql-schema.sql
│   ├── nginx-sample.conf
│   ├── OpenRC
│   │   ├── conf_d
│   │   └── init_d
│   ├── package.sh
│   ├── postgres-schema.sql
│   ├── seed-example.json
│   ├── setupvenv.sh
│   ├── sqlite-generate.sh
│   ├── sqlite-schema.sql
│   └── unittest.sh
├── docs
│   ├── automx2.adoc
│   ├── automx2.pdf
│   ├── config.adoc
│   ├── dbconfig.adoc
│   ├── dbupgrade.adoc
│   ├── howitworks.svg
│   ├── index.html
│   ├── installation.adoc
│   ├── ldap.adoc
│   ├── muaconfig.adoc
│   ├── operation.adoc
│   ├── running.adoc
│   └── webserver.adoc
│   └── Makefile
.....
├── README.md
.....

I would like to have them also shipped, and have them locally offline on my PC. I would maybe ask the developer to do so.

Thanks in advance.