[DRE-maint] Bug#917474: librarian-puppet: documentation included with binary and package mostly useless and lacking lots of information

[Gabriel Filion]

Package: librarian-puppet
Version: 3.0.0-1
Severity: normal
Tags: upstream

Hi there,

Thanks for maintaining this package! it's super useful for us.

I find it hard to know how to use and configure this ruby script. The
main "binary" itself has some information with the "help" subcommand but
it's far from touching all necessary subjects.
The main man page for the package was probably auto-generated because
upstream doesn't provide one, and the information in the man page is
extremely basic and most incomplete.

For one thing, the package doesn't ship the README.md file in
/usr/shared/doc/librarian-puppet. This would help getting at least a
good portion of information that upstream already has documented at
least there. a man page could be based off of a lot of information in
the readme. it would be best if upstream could provide a man page,
though.

The parts that are lacking even upstream are:

 * there is no documentation of what the Puppetfile format and syntax is

 * there is no documentation at all on configuration options that can be
   used

cheers!

-- System Information:
Debian Release: buster/sid
  APT prefers unstable
  APT policy: (500, 'unstable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 4.18.0-2-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_CA.utf8, LC_CTYPE=en_CA.utf8 (charmap=UTF-8) (ignored: LC_ALL set to en_CA.utf8), LANGUAGE=en_CA.utf8 (charmap=UTF-8) (ignored: LC_ALL set to en_CA.utf8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Versions of packages librarian-puppet depends on:
ii  puppet             5.5.8-1
ii  ruby               1:2.5.1
ii  ruby-json          2.1.0+dfsg-2+b1
ii  ruby-librarian     0.6.4-1
ii  ruby-puppet-forge  2.2.9-2
ii  ruby-rsync         1.0.9-1

librarian-puppet recommends no packages.

librarian-puppet suggests no packages.

-- no debconf information