Man pages for executable scripts in django/bin/

[James Bennett]

I've been talking with people who maintain packages of Django for Linux distributions, and one concern that's come up is that they want to install the scripts from django/bin/ into systemwide locations like /usr/bin/, but doing so usually requires a man page; it'd make their lives easier if we could provide properly-formatted man pages documenting those scripts.

[Marc Fargas <telenieko@…>]

I'm on with "django-admin.1" just in case someone is going to take a binary to write a manpage for. It's the first time I try to write a manpage so, please, be patient! ;)

[Marc Fargas <telenieko@…>]

django-admin manpage.

[Marc Fargas <telenieko@…>]

Here's my first try to create a manpage! Just a few things to take into account:

• The manpage assumes django-admin is installed as django-admin NOT django-admin-py.
• The manpage has "Django developers" as it's author (see on the AUTHORS section), I set it that way as I think it's policy of the project to not set speciffic names.
• Anyone has a spell-checker?

You can try the manpage by:

groff -man -Tascii django-admin.1

ubernostrum: I think this is the only binary which needs a manpage, or are the other files in bin/ installed on system directories? (compile-messages.py, daily_cleanup.py , django-admin.py, make-messages.py, unique-messages.py), if so, with those names or something like django-* ?

[Marc Fargas <telenieko@…>]

Note: When commiting this manpage do not close this ticket, Reference the changeset but leave the ticket open as ubernostrum asked to have manpages for everything in bin/ it's nice to go on adding the manpages as they get added but better leave the ticket open so we know there are more manpages needed!

thanks ;)

[Malcolm Tredinnick]

Okay, I finally got around to reading this. A few comments

• Leave out the historical summary at the top. It's not normal man page practice. If you really want to put a capsule summary in, include a HISTORY section towards the end. Basically, everything under the "Django" subheading in the DESCRIPTION block should go, I think. Application manual pages do not generally do advocacy for the package they are part of and being consistent with the style of existing practice helps the user. You are writing the equivalent of, say, perldoc(1) here, not perl(1).
• The sentence "And is released as Open Source" in the AUTHORS section has a few problems. It's not a full sentence, it should really be in the LICENSE section and it should mention the actual license (which is "the same terms as the Python license, see the LICENSE file in the documentation for details"). Open Source is too generic.
• Rather than referring to any policy about not including authors' names, which reads a little oddy, just say "Originally developed at ...(blah-blah)... Refer to the AUTHORS file in the package documentation for contributors."
• The program is called django-admin.py, the man page should reflect that. It is installed as django-admin.py. If Debian (for example) are going to change the installation name, they would be responsible for also patching the man page. Our shipped version of this document should match the name of the program as we ship and install it -- which means it has a .py extension.
• It is quite okay (and recommended) to refer to the real documentation in a manual page like this. So listing all the options and then including something to say "full descriptions of all these options, with examples, can be found in blah-blah-blah" (or possibly putting that ahead of the options list) is fine.
• Probably worth including an ENVIRONMENT section that mentions the DJANGO_SETTINGS_MODULE variable.

[Paul <pb@…>]

I'm attaching a revised version of the manpage file that attempts to address Malcom's concerns and includes some other miscellaneous cleanup.

[Paul <pb@…>]

revised django-admin.py manpage

[Marc Fargas <telenieko@…>]

Replying to Paul <pb@e-scribe.com>:

I'm attaching a revised version of the manpage file that attempts to address Malcom's concerns and includes some other miscellaneous cleanup.

Thanks !

please: after check-in do not close this ticket, we still miss the rest of manpages! ;)

[Malcolm Tredinnick]

Great work, Paul. A couple of very small formatting issues, but this is pretty much perfect. I'll check it in.

Marc, leaving the ticket open is not a very neat workflow: there's no clear indication of which patches have been checked in and which are under consideration and which are ready to check-in. Trac sucks a lot in that respect.

I'll leave this open, but any new man pages should go in their own ticket and we can close this ticket once they've all been done.

[Jacob]

This looks great to me, but I'm not sure (a) where to put this in the tree (maybe under "extras"?) and (b) how to get it onto MANPATH from setup.py. Can someone who knows these things enlighten me so I can check this in?

[Marc Fargas <telenieko@…>]

/manpages
/docs/manpages
would be nice, if not, extras ;)

dunno about the setup.py question.

[Malcolm Tredinnick]

Jacob: I was going to shove it under docs/man/ ("man" is more traditional than "manpages"). I got as far as checking that wouldn't screw up the automatic docs generation on the website (you were clever there; you put recurse=False on the filename searching in the docs code :-) ).

We're screwed as far as automatically installing into MANPATH. Python's distutils doesn't support this for reasons passing all comprehension. So we'd either have to do it manually -- which is officially hard to get right for all cases -- or (and this was my preferred path) just install it under the docs directory and let distros put it into place as part of their installation scripts (we can fix the rpm generation from bdist_rpm to do that).

[Malcolm Tredinnick]

(In [5457]) Added a man page for django-admin.py. Also install it correctly as part of the
auto-generated rpm. Thanks to Marc Fargas and Paul Bissex for writing the man
page. Refs #3341.

[Simon G. <dev@…>]

I'm closing this in favor of #5180 which supercedes it.