#3341: Man pages for executable scripts in django/bin/
---------------------------------+------------------------------------------
Reporter: ubernostrum | Owner: jacob
Status: new | Component: Documentation
Version: SVN | Resolution:
Keywords: man documentation | Stage: Accepted
Has_patch: 0 | Needs_docs: 1
Needs_tests: 0 | Needs_better_patch: 1
---------------------------------+------------------------------------------
Changes (by mtredinnick):
* needs_better_patch: 0 => 1
* stage: Ready for checkin => Accepted
Comment:
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.
--
Ticket URL: <http://code.djangoproject.com/ticket/3341#comment:6>
Django Code <http://code.djangoproject.com/>
The web framework for perfectionists with deadlines
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en
-~----------~----~----~----~------~----~------~--~---
