Update 06-find.md

[sina-masoud-ansari]

Added quick tips on understanding and navigating man pages

[wking]

On Thu, Feb 12, 2015 at 03:25:08PM -0800, Sina Masoud-Ansari wrote:

Added quick tips on understanding and navigating man pages You can
view, comment on, or merge this pull request online at:

Minor typo: "recursvie" -> "recursive".

While I like this advice for students following along at home, I'm not
sure this is critical enough for actively teaching it during a lesson
(especially in light of #55).

[ChristinaLK]

I really like having this as part of the "helping people help themselves" ethic, and while I might not go over it in detail while teaching, I would at least handwave towards it ("here is a man page, shows options, shows how options can be combined, etc.")

Some suggestions, for discussion:

• leave text as is, but in a callout box
• don't callout text, but take away the 3rd bullet point, which is less about comprehending a man page and more about...well, less style navigation. ;)
• add to discussion.md or references.md instead
• my dream would be to see it incorporated with the changes described in Recommendation to Instructors about man because it doesn't work in Windows #55. @smas036, would you be up for that?

[gvwilson]

+1 to putting this in discussion.md, and putting a pointer to it in the main text.

[ChristinaLK]

Hey @smas036 , would you be willing to move this to discussion.md?

[gdevenyi]

If we're going to show a man page snippit, I think it's worth discussing how to read it.

If we don't want to include this here, I think the man page section in its entirety should be moved to the discussion (or a lesson in shell-extras).

For specifics, I would change "syntax" -> "markup" or "formatting" when describing the man page.

[sina-masoud-ansari]

Hi all, I incorporated some of the changes suggested here, and moved to discussion.md. Though I'm unsure what the outcome from #55 was so I'm tempted to leave any integration until there is some consensus. I think the brief note under grep in find.md was appropriate, and that if we are happy with this in discussion.md it would be best to elaborate on more details of using man pages. Alternatively we could point to something like http://www.linuxcommand.org/reading_man_pages.php for those who want to learn more. My initial suggestion was for some quick advice for people seeing a man page for the first time as it can be quite overwhelming, especially if you have never really programmed.

[wking]

On Mon, Mar 23, 2015 at 02:42:53PM -0700, Sina Masoud-Ansari wrote:

I incorporated some of the changes suggested here, and moved to
discussion.md.

It looks like you added them to discussion.md, but didn't remove them
from the find page.

Alternatively we could point to something like
http://www.linuxcommand.org/reading_man_pages.php for those who want
to learn more.

I'm all for linking to stable external docs for this sort of thing.
That looks like a short, clear explanation, and the 2001/2003
copyright means that the page is likely to be pretty stable.
Archive.org says the URL is pretty stable too 1, so I'm in favor of
a link from the find page with something like:

man is the Unix "manual" command: it prints a description of a
command and its options, and (if you're lucky) provides a few
examples of how to use it. For an overview of the format, see
Norman Robinson's notes on reading man pages.
…

That way folks who are confused by the output or our excerpt from
grep(1) have somewhere to go for more information, but it doesn't take
up class time (unless the instructor wants to get into the details).
If we go this route, I think we can drop the discussion.md entry too.

[ChristinaLK]

I like the idea of using the link from above and removing the callout box from 06-find.md - essentially what @wking suggests. I think we can leave the text in discussion.md for now, and possibly add the link there as well. @sina-masoud-ansari , would you be willing to do that?