Re: does django-admin need a man page?

[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

On Friday, June 19, 2015 at 10:55:53 AM UTC-4, Luke Plant wrote:
>
>  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
>
> On 03/03/15 15:42, Tim Graham wrote:
>  
> 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?
>
> On Wednesday, November 26, 2014 at 8:21:31 AM UTC-5, Markus Holtermann 
> wrote: 
>>
>> On Wednesday, November 26, 2014 7:46:16 AM UTC+1, Aymeric Augustin wrote: 
>>>
>>> Le 26 nov. 2014 à 01:51, Nick Phillips  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? 
>>>
>>
>>  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
>>  
>  -- 
> 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/
>
> 

-- 
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-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@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/c4f5e150-0015-4768-a16e-2e5debaa77b7%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: does django-admin need a man page?

[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

On 03/03/15 15:42, Tim Graham wrote:
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?


On Wednesday, November 26, 2014 at 8:21:31 AM UTC-5, Markus Holtermann 
wrote:


On Wednesday, November 26, 2014 7:46:16 AM UTC+1, Aymeric Augustin
wrote:

Le 26 nov. 2014 à 01:51, Nick Phillips 
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?


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

--
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-developers+unsubscr...@googlegroups.com 
.
To post to this group, send email to 
django-developers@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/

--
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-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@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/55842D5F.8010409%40cantab.net.
For more options, visit https://groups.google.com/d/optout.

Re: does django-admin need a man page?

[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?

On Wednesday, November 26, 2014 at 8:21:31 AM UTC-5, Markus Holtermann 
wrote:
>
> On Wednesday, November 26, 2014 7:46:16 AM UTC+1, Aymeric Augustin wrote:
>>
>> Le 26 nov. 2014 à 01:51, Nick Phillips  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? 
>>
>
> 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
>

-- 
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-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@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.

Re: does django-admin need a man page?

[Markus Holtermann]

On Wednesday, November 26, 2014 7:46:16 AM UTC+1, Aymeric Augustin wrote:
>
> Le 26 nov. 2014 à 01:51, Nick Phillips  > 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? 
>

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

-- 
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-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@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/e82f9bfd-b867-44cb-b3f1-4f7a223faf2a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: does django-admin need a man page?

[Anton Baklanov]

+1 for having updated man page.


On Wed, Nov 26, 2014 at 8:46 AM, Aymeric Augustin <
aymeric.augustin.2...@polytechnique.org> wrote:

> Le 26 nov. 2014 à 01:51, Nick Phillips  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?
>

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-developers+unsubscr...@googlegroups.com.
> To post to this group, send email to django-developers@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

-- 
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-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@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/CAC%3Dsm27-D-6_%2B4940R9K5UrdQTwXeUw3L4M3iH2tx6oNLaYe%3DQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: does django-admin need a man page?

[Aymeric Augustin]

Le 26 nov. 2014 à 01:51, Nick Phillips  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.

-- 
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-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@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.

Re: does django-admin need a man page?

[Nick Phillips]

On Mon, 2014-11-24 at 16:44 -0800, Tim Graham wrote: 
> 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?
> 

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 (g info gr). 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.phill...@otago.ac.nz / 03 479 4195
# These statements are mine, not those of the University of Otago

-- 
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-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@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/1416963109.6414.18.camel%40otago.ac.nz.
For more options, visit https://groups.google.com/d/optout.

Re: does django-admin need a man page?

[Ben Finney]

Tim Graham  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

-- 
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-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@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/85lhn0xfkl.fsf%40benfinney.id.au.
For more options, visit https://groups.google.com/d/optout.

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?

-- 
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-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@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/ff53d919-afed-4d59-8a2e-681d6a84fb98%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.