Include help buffer command and provide a release tarball

[wigust]

Hello @alphapapa

could you provide a release tarball, please?

Just add a tag, for example: 1.0.0 or v1.0.0 and git push --tags

[alphapapa]

Hi,

Are you planning to make a Guix package? ;)

I've been planning to put this on MELPA for a long time, and that would include tagging a stable release. However, since the package requires some manual configuration outside of Emacs, I'm not sure if putting it on MELPA is entirely appropriate. Anyone who installed it and expected it to work out-of-the-box would be disappointed, and they'd have to consult the readme, which isn't included.

Some thoughts:

1. I think there are other packages on MELPA that require manual configuration outside of Emacs. I can't recall any at the moment, since I don't think I use any, but I think I've come across some. So maybe this isn't that big of a deal.
2. I could do like Helm and add a command that opens documentation inside Emacs with instructions.
3. I could include the readme in the package and have a command that opens it.

What do you think?

Thanks.

[wigust]

alphapapa <[email protected]> writes:

Hi, Are you planning to make a Guix package? ;)

Of course I did this for such a great Emacs package! :-) Ready to send a patch as soon as you ready to release.

I've been planning to put this on MELPA for a long time, and that would include tagging a stable release. However, since the package requires some manual configuration outside of Emacs, I'm not sure if putting it on MELPA is entirely appropriate. Anyone who installed it and expected it to work out-of-the-box would be disappointed, and they'd have to consult the readme, which isn't included. Some thoughts: 1. I think there are other packages on MELPA that require manual configuration outside of Emacs. I can't recall any at the moment, since I don't think I use any, but I think I've come across some. So maybe this isn't that big of a deal.

Cannot say anything about Melpa too, sorry.

2. I could do like Helm and add a command that opens documentation inside Emacs with instructions. 3. I could include the readme in the package and have a command that opens it. What do you think?

Guix doesn't like READMEs in Emacs packages, as I saw. Build system just ignores to install them by default. I tried to force install README in one of sended patches, but maintainers don't think that it's worth to include them. So, documentation in elisp as comments or interactive command will be great, I guess. Something like smart-parens cheat buffer. M-x sp-cheat-sheet https://github.com/Fuco1/smartparens/blob/master/smartparens.el#L77 But I think it's overkill. Just a simple buffer with text instructions will be enough. Thanks!

[alphapapa]

Ok, thanks for your feedback.

I tried to force install README in one of sended patches, but maintainers don't think that it's worth to include them.

That's very disappointing to hear. I've been using Debian/Ubuntu for a long time, and I very much appreciate that I can always go to /usr/share/doc/package/README and find the package's readme file and other included documentation. I'm very interested in Guix, but if they refuse to include basic documentation, that is probably a deal-breaker for me. Considering how tiny text files are when compressed, and how huge disks are now, there's no reason to leave them out. Guess it just goes to show that Debian's policies are as important as its software.

Oh well, anyway, I'll leave this open until I come up with something. Thanks.

[wigust]

alphapapa <[email protected]> writes:

Ok, thanks for your feedback. > I tried to force install README in one of sended patches, but > maintainers don't think that it's worth to include them.

Actually they just do it, because everybody do it [1].

That's very disappointing to hear. I've been using Debian/Ubuntu for a long time, and I very much appreciate that I can always go to `/usr/share/doc/package/README` and find the package's readme file and other included documentation. I'm very interested in Guix, but if they refuse to include basic documentation, that is probably a deal-breaker for me. Considering how tiny text files are when compressed, and how huge disks are now, there's no reason to leave them out. Guess it just goes to show that Debian's policies are as important as its software.

Yes, Debian READMEs are helpful. But they are not *man* or *info* pages. They lack feautures like searching, indexing. So, I agree with Arun “A markdown README, IMHO, is not much of a documentation” [1]. Especially in Elisp, where code includes documentation in itself.

Oh well, anyway, I'll leave this open until I come up with something. Thanks.

Sorry for closing the issue. I replied via email and don't know why this happened. I hope this not happen again or I'll try to reopen it. [1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=28010

[alphapapa]

Yes, Debian READMEs are helpful. But they are not man or info pages. They lack feautures like searching, indexing.

Nevertheless, there are Debian packages which require reading the readme to configure properly. If someone wants to convert them to man or info pages, that's nice, and many Debian packages have man pages put together by Debian itself; but if not, the readmes should be included so the users have the necessary documentation. They might need it when offline, or the package's web site might go offline.

So, I agree with Arun “A markdown README, IMHO, is not much of a documentation” [1].

Documentation is documentation, regardless of its format. I think it's almost worse to make a package but leave out the documentation than to not make the package at all, because that's likely to just waste the user's time.

Especially in Elisp, where code includes documentation in itself.

Docstrings are function- and variable-level documentation. They aren't comprehensive, and they don't provide information about how to configure or integrate with external software that the package uses. They also don't provide an "entry-point" into using the package. I hope that Guix creates a more user-friendly policy on included documentation. (I know this isn't your decision.)

Sorry for closing the issue. I replied via email and don't know why this happened. I hope this not happen again or I'll try to reopen it.

No problem, easy enough to click the reopen button. :) Thanks.