does django-admin need a man page?

[Tim Graham]

I raised the issue in #23903 and Aymeric mentioned that it may be useful for downstream packagers, e.g. Debian. I installed python-django via apt-get on Ubuntu 14.04 and confirmed the existence of the man page. I'd like to remove it though (or make it point people to 'django-admin --help') as it's out-of-date and 'django-admin --help' provides the same information in a much easier to maintain format. Does anyone else have input on this?

[Ben Finney]

Tim Graham <timog...@gmail.com> writes:

> I'd like to remove it though (or make it point people to 'django-admin
> --help') as it's out-of-date and 'django-admin --help' provides the
> same information in a much easier to maintain format. Does anyone else
> have input on this?

Man pages are a standard interface on Unix, and it's very helpful to
keep the man page up to date for any command available at the command
line.

Certainly when I'm in my IDE it's much better to be able to query the
manpage database for a command, than to figure out whatever
idiosyncratic help system it prefers me to use.

--
\ “Most people, I think, don't even know what a rootkit is, so |
`\ why should they care about it?” —Thomas Hesse, Sony BMG, 2006 |
_o__) |
Ben Finney

[Nick Phillips]

As far as Debian is concerned, not having a manpage for an executable
installed in the standard path is a bug. So if you don't provide one,
one will probably be written for Debian anyway, albeit not a
particularly good one.

However, as Ben pointed out, "man foo" is the standard interface to
getting long-format information on the "foo" command, if not always the
full docs (grrrr info grrrrr). So I'd suggest considering implementing
something to generate a man page from whatever you wish the "canonical"
source of the information to be.


Cheers,


Nick
--
Nick Phillips / nick.p...@otago.ac.nz / 03 479 4195
# These statements are mine, not those of the University of Otago

[Aymeric Augustin]

Le 26 nov. 2014 à 01:51, Nick Phillips <nick.p...@otago.ac.nz> a écrit :
>
> I'd suggest considering implementing
> something to generate a man page from whatever you wish the "canonical"
> source of the information to be.

The canonical source of information is:
https://docs.djangoproject.com/en/dev/ref/django-admin/

Does a rst-->man conversion tool exist?

--
Aymeric.

[Anton Baklanov]

+1 for having updated man page.

Sphinx can build man pages. You can actually do `make man` in current django docs but you will have ALL docs formatted into 1 man page as a result. So perhaps this needs some tuning :)

 

--
Aymeric.

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.
To post to this group, send email to django-d...@googlegroups.com.
Visit this group at http://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/4D909BC0-48D2-4064-B8EC-8B70903F2474%40polytechnique.org.

For more options, visit https://groups.google.com/d/optout.

--

Regards,

Anton Baklanov

[Markus Holtermann]

Yes, rst2man.py is part of docutils. And Sphinx even has a man builder. Inside the docs directory run "make man". The generated man page is 4MB though, and contains the _entire_ documentation, not only the django-admin.py command. But there should be some way to work around that.

 

/Markus

[Tim Graham]

Is anyone interested in updating Django's man page? It's a bit embarrassing that the one that ships with 1.7 includes commands that no longer exist (cleanup, install (never heard of that one before), etc.). The fact that it is so outdated and that we've gotten no complaints about it is why I thought we could consider it for removal).

Any recommendations for a program to edit/preview manpage sources that's more human friendly?

[Luke Plant]

Another argument for removing it (or trimming it down to minimum) is that it's actually extensible (https://docs.djangoproject.com/en/1.8/howto/custom-management-commands/ ), and some packages (at least in the past) have actually changed the behaviour of built in commands (e.g. http://south.readthedocs.org/en/latest/commands.html#syncdb ).

So, the man page is doomed to be both incomplete and possibly incorrect. Surely it makes more sense for a man page to just point to the "--help" tag and official docs online?

Luke

--

You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.
To post to this group, send email to django-d...@googlegroups.com.
Visit this group at http://groups.google.com/group/django-developers.

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/1ecfaac4-b31a-4675-bd62-95e76369a6e5%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

-- 
"He knows the way I take: when he has tried me, I shall come forth 
as gold" (Job 23:10).

Luke Plant || http://lukeplant.me.uk/

[Tim Graham]

Erik found a way to generate the man page automatically from docs/ref/django-admin.txt and this has now been merged & integrated into the release process. See the ticket for details: https://code.djangoproject.com/ticket/23903