<p dir="ltr">Regarding documentation, I really wish the Linux man pages could reach the quality of the OpenBSD man pages. Many times I am looking for examples of how a command argument is supposed to be used and many pages are lacking. I realize documentation is the least enjoyable part if programming but clearer writing would bring huge benefit.</p>
<div class="gmail_quote">On May 17, 2015 7:10 PM, <<a href="mailto:jep200404@columbus.rr.com">jep200404@columbus.rr.com</a>> wrote:<br type="attribution"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Sun, 17 May 2015 10:11:29 -0400, Steve VanSlyck <<a href="mailto:s.vanslyck@postpro.net">s.vanslyck@postpro.net</a>> wrote:<br>
<br>
> ... asked me some good questions about my one-liner,<br>
><br>
> sed -i.bak 's:(^Defaults\s*Env_reset\s*)$:$1\nDefaults<br>
> editor=/bin/nano:' ./sudoers<br>
><br>
> , one of which was why "$1?"<br>
><br>
> For the "replace" portion of sed, I was trying to find out how to return<br>
> the result of the last search and $1 seemed to be the right way to do<br>
> it. I saw what I thought was a authoritative page on this but cannot<br>
> find it now. One that I did find is<br>
> <a href="http://stackoverflow.com/questions/2890700/backreferences-syntax-in-replacement-strings-why-dollar-sign" target="_blank">http://stackoverflow.com/questions/2890700/backreferences-syntax-in-replacement-strings-why-dollar-sign</a><br>
<br>
That article talks about Java and Perl.<br>
Your example used sed, which predates Perl by much.<br>
I saw no direct mention of sed in that article.<br>
<br>
What has your experimentation revealed about how sed works?<br>
<br>
> Everything I'm readying about regular expressions talks about this<br>
> engine does it this way and that engine does it that way and it's all<br>
> very confusing and frustrating.<br>
<br>
Indeed. It is that way. I don't pay any attention to the<br>
underlying engines, just how each program implements regexes.<br>
Knowing what the common themes are,<br>
I often figure things out with experimentation.<br>
<br>
> None of the "engines" are fedora-based bash,<br>
> so I have no idea which engine's requirements I'm<br>
> supposed to go by.<br>
<br>
You have to read the manual for each program _and_ experiment<br>
to back it up. I think of shells as implementing globs, not<br>
regexes, although they might have some regex capability that<br>
I'm not aware of. Learn the difference between globs and regexes.<br>
<br>
> On top of this I have to struggle with a problem endemic to technical<br>
> writing and which is far too common: writers who state a rule and then<br>
> give examples inconsistent with the rule just described!<br>
<br>
Yup. It sucks. Experiment. Sometimes even read the source code.<br>
<br>
> This makes me scream.<br>
<br>
Yup. It sucks.<br>
<br>
> ^A matches "A" at the beginning of a line A$ matches "A" at the end of<br>
> a line A^ matches "A^" anywhere on a line $A matches "$A" anywhere on a<br>
> line ^^ matches "^" at the beginning of a line $$ matches "$" at the<br>
> end of a line<br>
<br>
Those make sense to me.<br>
<br>
> On <a href="http://grymoire.com" target="_blank">grymoire.com</a>, for<br>
> example, Bruce Barnett writes, "If you need to match a "^" at the<br>
> beginning of the line, or a "$" at the end of a line, you must escape<br>
> the special character with a backslash."<br>
<br>
I think he is wrong and very close to being right.<br>
Better would have been to say pattern instead of line. I.e.,<br>
<br>
"If you need to match a "^" at the beginning of the<br>
pattern, or a "$" at the end of a pattern,<br>
you must escape the special character with a backslash."<br>
<br>
Submit a patch to him.<br>
<br>
Books benefit from the work of a good editor.<br>
Much online stuff does not have the benefit of editors,<br>
and it shows. Often it helps to consult several online<br>
sources, and compare them.<br>
<br>
By the way, there is often more than one way to do<br>
something. An exercise can be to see how many ways<br>
one can do something.<br>
<br>
> WT#! It maybe would've killed him to mention escaping the character OR<br>
> doubling it, and then give BOTH examples?:<br>
<br>
You are his editor. Submit a patch.<br>
<br>
> How are we supposed to learn anything if we can't trust our teachers!<br>
<br>
By experience, which involves making mistakes and getting burned<br>
by misplaced trust. You'll develop a sense of how much to trust<br>
information. The judgement for such is highly subjective.<br>
You'll notice a correlation between the various kinds of<br>
goodness in writing with the accuracy of the information.<br>
Having suffered from poor writing, you will appreciate good<br>
writing more and more. You will pay more attention to a well<br>
written question than lesser writing. You are not alone.<br>
Others behave similarly. They are waiting for a good question.<br>
This leads back to the advice at the top of <a href="http://colug.net" target="_blank">colug.net</a>.<br>
<br>
> I'm almost 60. I approach this stuff in good faith, with no<br>
> math training beyond high school, no programming experience<br>
> beyond Excel, ...<br>
<br>
Excel experience should have been enough to make you wary. :-)<br>
<br>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -<br>
<br>
Many O'Reilly books are good. Older editions are cheap.<br>
For classic Unix tools, old editions are still relevant.<br>
Consider reading the following:<br>
<br>
sed & awk by Dale Dougherty & Arnold Robbins<br>
<br>
It covers regular expressions as used by those programs.<br>
<br>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -<br>
<br>
I have found many documentation errors over the years.<br>
Sometimes I later realized that the documentation was<br>
correct and that I was wrong. An Intel 8051 manual was<br>
one manual I thought was wrong, but later realized was<br>
correct. The more I studied it, the more I realized how<br>
carefully it was written, that every word was chosen well.<br>
<br>
Some authors are great. Kernighan and Ritchie wrote<br>
"The C Programming Language" with wit. W. Richard Stevens<br>
wrote APUE with amazing precision. A Fortran manual from<br>
IBM by anonymouse authors was excellent.<br>
_______________________________________________<br>
colug-432 mailing list<br>
<a href="mailto:colug-432@colug.net">colug-432@colug.net</a><br>
<a href="http://lists.colug.net/mailman/listinfo/colug-432" target="_blank">http://lists.colug.net/mailman/listinfo/colug-432</a><br>
</blockquote></div>