classification
Title: use --directory option of make in describing how to build the docs
Type: Stage: resolved
Components: Devguide Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: chris.jerdonek, eric.araujo, ezio.melotti, georg.brandl, orsenthil, python-dev, r.david.murray, sandro.tosi, tshepang
Priority: normal Keywords: patch

Created on 2012-12-29 14:11 by tshepang, last changed 2013-01-11 16:21 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
make-can-specify-build-directory.diff tshepang, 2012-12-29 14:11
issue-16814-2.patch chris.jerdonek, 2012-12-30 05:10
issue-16814-3.patch chris.jerdonek, 2013-01-09 03:29
Messages (18)
msg178495 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-12-29 14:11
This avoids having to run 2 separate commands.
msg178496 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-12-29 14:28
i'd use

make -C Doc html

much more compact and what you would usually find on the internet for "cd into the dir and run the html target in it"
msg178497 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-12-29 14:51
I like long-form options for documentation purposes since it's clearer
what the option is for.
msg178505 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-12-29 15:47
I think the fact that the cd paradigm is more commonly encountered is a fairly strong argument in favor of keeping it, but I'm only -0 on this change.
msg178517 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-12-29 17:50
Agree with David.
msg178550 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-12-30 05:10
Another option is to give the shorter option as an alternative.  I for one didn't know about that option but would have liked to.  Patch attached.

Also, this way we can give the shorter option and the reader can still see pretty easily what it is for.
msg178552 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-12-30 05:12
> Another option is to give the shorter option as an alternative.

s/shorter option/one-liner/
msg178556 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-12-30 07:55
This is not a `make' tutorial...
msg178563 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-12-30 09:31
> This is not a `make' tutorial...

I find the latest patch to be a great compromise though. Many people
would be grateful to learn about the -C option. I am one of them.
msg178565 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-12-30 10:45
Well, I'm not -1 about the patch.  But there is something to be said for conciseness, and sprinkling the docs with endless alternate routes will not make it easier to read quickly and get the information you need.
msg178582 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-12-30 15:14
FWIW even if I heard about the one-liner a few times already I can't really seem to remember it, and prefer to do "cd Doc" anyway.  Using "cd Doc" also makes all the subsequent commands shorter (e.g. opening files, running other make targets).
The patch proposed by Chris looks OK to me though.
msg178753 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2013-01-01 20:39
I find, cd Doc easy to remember as well. If make tricks can be used then I
hope readers note it rather than be exposed via Documentation. Chris's
patch is helpful to me, but still I may not vote a +1 for it to be in
Documentation. thanks.

On Sun, Dec 30, 2012 at 7:14 AM, Ezio Melotti <report@bugs.python.org>wrote:

>
> Ezio Melotti added the comment:
>
> FWIW even if I heard about the one-liner a few times already I can't
> really seem to remember it, and prefer to do "cd Doc" anyway.  Using "cd
> Doc" also makes all the subsequent commands shorter (e.g. opening files,
> running other make targets).
> The patch proposed by Chris looks OK to me though.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue16814>
> _______________________________________
> _______________________________________________
> Python-bugs-list mailing list
> Unsubscribe:
> http://mail.python.org/mailman/options/python-bugs-list/senthil%40uthcode.com
>
>
msg179346 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-01-08 12:48
FWIW I use make -C Doc all the time but agree with Georg’s point about conciseness.  Ezio, I suggest you bookmark some make doc page if you can’t remember it :)
msg179407 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2013-01-09 03:29
For the record, we do have tutorial-like documentation and document more than one way to do things in multiple places throughout the devguide.  For example:

http://docs.python.org/devguide/faq.html#how-do-i-list-the-files-in-conflict-after-a-merge

Unlike the short options for long commands, though, it's not obvious to look for something like `make -C` (because you don't already know it's there).  That's why I think this option is more deserving.

Personally, when working on doc patches, I frequently go back and forth between `make html` and `hg diff`.  Knowing about -C means one doesn't have to cd up and down the directory each time or double-check what directory one is in.

I think it's okay and should even be a goal of the devguide to point out more efficient ways to contribute, which may sometimes involve saying more than the minimum (e.g. saying how something works, or stating a more "advanced" way to do something).  I still think we should strive for conciseness within those constraints.  Here is a new patch that makes the current language more concise in addition to some other minor changes.
msg179414 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-01-09 06:27
> I frequently go back and forth between `make html` and `hg diff`.

Mercurial commands work on the whole repo, regardless on the dir you are in (unlike SVN ones).  That's why I usually just cd in Doc/ and do everything (opening files with editor/browser, make *, hg *) from there.  Even when I prepare a patch I can do `hg di > ../patch.diff` if I want it in the root.

I don't think there's any harm in mentioning briefly `make -C Doc html` though.
msg179644 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-01-11 08:16
New changeset 5f24a77e7beb by Chris Jerdonek in branch 'default':
Issue #16814: add "make -C Doc html" short-cut to documentation instructions.
http://hg.python.org/devguide/rev/5f24a77e7beb
msg179645 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2013-01-11 08:17
I went ahead and committed this if that's okay.  I wasn't sensing any strong objection but -0 from some and +1 or +0 from others.  To compensate for the extra six words, I went ahead and first made the current language more concise here:

http://hg.python.org/devguide/rev/157066a204ab

If anyone feels strongly, I would be happy to revert the change though.
msg179695 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-01-11 16:21
LGTM.
History
Date User Action Args
2013-01-11 16:21:01eric.araujosetmessages: + msg179695
2013-01-11 08:17:47chris.jerdoneksetresolution: fixed
messages: + msg179645
stage: resolved
2013-01-11 08:16:57python-devsetnosy: + python-dev
messages: + msg179644
2013-01-09 06:27:44ezio.melottisetmessages: + msg179414
2013-01-09 03:29:41chris.jerdoneksetfiles: + issue-16814-3.patch

messages: + msg179407
2013-01-08 12:48:23eric.araujosetnosy: + eric.araujo
messages: + msg179346
2013-01-01 20:39:06orsenthilsetnosy: + orsenthil
messages: + msg178753
2012-12-30 15:14:44ezio.melottisetmessages: + msg178582
2012-12-30 10:45:09georg.brandlsetmessages: + msg178565
2012-12-30 09:31:44tshepangsetmessages: + msg178563
2012-12-30 07:55:41georg.brandlsetmessages: + msg178556
2012-12-30 05:12:56chris.jerdoneksetmessages: + msg178552
2012-12-30 05:10:36chris.jerdoneksetfiles: + issue-16814-2.patch
nosy: + chris.jerdonek
messages: + msg178550

2012-12-29 17:50:50georg.brandlsetstatus: open -> closed
nosy: + georg.brandl
messages: + msg178517

2012-12-29 15:47:43r.david.murraysettitle: use --directory option of make -> use --directory option of make in describing how to build the docs
2012-12-29 15:47:00r.david.murraysetnosy: + r.david.murray
messages: + msg178505
2012-12-29 14:51:01tshepangsetmessages: + msg178497
2012-12-29 14:28:31sandro.tosisetnosy: + sandro.tosi
messages: + msg178496
2012-12-29 14:11:51tshepangcreate