Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

no man page #477

Open
ggl opened this issue Jun 8, 2016 · 12 comments
Labels

Comments

@ggl
Copy link

@ggl ggl commented Jun 8, 2016

Lacks documentation other than a basic usage message when run w/o arguments. A man file would be nice.

@ggl ggl changed the title no man file no man page Jun 8, 2016
@stefan2904

This comment has been minimized.

Copy link

@stefan2904 stefan2904 commented Jun 13, 2016

there is http --help ...

Re: manpage
One could add the manpage from the Debian project: https://sources.debian.net/src/httpie/0.9.2-1/debian/http.1/

It's rather short, but at least there is one. :-)

@bottlab

This comment has been minimized.

Copy link

@bottlab bottlab commented Apr 11, 2017

It seems like the http(1) manpage has been added, but there is issues with it.
The headers only option is --headers or -t on the http(1) man page, but it is --headers or -h for httpie instead.

@merwok

This comment has been minimized.

Copy link

@merwok merwok commented Dec 19, 2017

Tools such as help2man can help generate a man page.

@merwok merwok mentioned this issue Dec 19, 2017
@sigmavirus24

This comment has been minimized.

Copy link

@sigmavirus24 sigmavirus24 commented Dec 19, 2017

Duplicate of #248

@jakubroztocil

This comment has been minimized.

Copy link
Owner

@jakubroztocil jakubroztocil commented Dec 22, 2017

Any tips for good format/tools/workflow for the making a man page?

@sigmavirus24

This comment has been minimized.

Copy link

@sigmavirus24 sigmavirus24 commented Dec 22, 2017

Word of warning: Downstream Linux redistributors will not care about the man page you generate and in most cases generate one of equal or lesser quality. Further, pip doesn't always have the permissions to install man pages in the correct place. This probably shouldn't be much of a priority.

@pacoesteban

This comment has been minimized.

Copy link

@pacoesteban pacoesteban commented Jun 6, 2019

I would like to re-activate this thread, as httpie is a CLI tool, it seems logical to have a man page for it at hand. The --help suggested by @stefan2904 seems incomplete and I cannot agree with @sigmavirus24, downstream (at least OpenBSD and others) cares about man pages. I do not see a reason not to use a good man page already distributed with the software ...

To the point, my suggestion is to change the README.rst for a proper man page using mdoc, which could be used on all modern UNIX like systems (every linux distro, BSD, MacOSX, and many more). I volunteer for that. But I wanted to ask if you would consider this before investing any time on it.

I would leave a shorter README.[md,rst] with install instructions and some basic examples and the current animations. That will be the "face" on the github repo and can get you started. But I would convert the current documentation to an actual man page, one that can read in detail when needed, in a separate tmux pane or terminal, while actually working with httpie.

Later, that file will have to be maintained as you do now with the rst file.

What do you think ?

@pacoesteban

This comment has been minimized.

Copy link

@pacoesteban pacoesteban commented Jun 15, 2019

@jakubroztocil are you interested in this ?

Thanks.

@sigmavirus24

This comment has been minimized.

Copy link

@sigmavirus24 sigmavirus24 commented Jun 15, 2019

@pacoesteban why even bother rewriting in mdoc when there is rst2man utility that will generate the appropriate man page?

The python community prefers rst and so we keeping our docs in that would be more maintainable and preserve doc quality.

@pacoesteban

This comment has been minimized.

Copy link

@pacoesteban pacoesteban commented Jun 16, 2019

I brought this back because the current readme is not really structured as a man page. I think it should be something like a refactored mix of the readme and --help. Also, it bugs me every time I have to check docs on this cli tool I use quite often (as @dequis was saying on #248). Besides, the rst2man utility you mention fails to generate the man page (and no, is not because of the images at the front of the file).

Of course is not my intention to try to impose my view on how docs should be to the python community or to this project, and I see little interest on this.

So, do you think the current readme could be modified in a way that some tool like rst2man could be used to generate a man page ? "Not perfect man page is better than no man page".

@sigmavirus24

This comment has been minimized.

Copy link

@sigmavirus24 sigmavirus24 commented Jun 16, 2019

I'm not a maintainer but I definitely agree that "an imperfect man page is better than none at all". As for my comment, earlier, Debian and Fedora have outright refused to use man pages bundled in projects I've worked on (e.g., OpenStack CLI tooling) in the past. Combine that with the understanding that pip on most Linux distributions is intentionally patched to disallow installation beyond user-scope and you've got the perfect recipe for "This is something that benefits very few people in practice". Especially when you consider that Debian and Fedora variants often pin old versions so adding man pages only helps people a few years in the future.

@deed02392

This comment has been minimized.

Copy link

@deed02392 deed02392 commented Nov 7, 2019

I have made an alias for man httpie that does open https://httpie.org/doc xD

This is for ZSH on MacOS:

man() {
    if [[ $@ == "httpie" ]]; then
	command open https://httpie.org/doc
    else
        command man "$@"
    fi
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
8 participants
You can’t perform that action at this time.