<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto"><div dir="ltr">Hi Lloyd, tbh it sounds like you’re mostly having problems with regular expressions rather than the erlang docs for it. It’s a pretty dense subject, and unless you’ve already got a way up the learning curve, the syntax can appear arcane. Not only that but the way they are used and implemented in different systems is complex and unpredictable.</div><div dir="ltr"><br></div><div dir="ltr">Thing is once you’ve got your head round the basics by working through some regex-specific docs, then the docs dealing with the specifics of a given language’s implementation will make a lot more sense.</div><div dir="ltr"><br></div><div dir="ltr">I don’t think it’s really fair to criticise the erlang re docs without really grasping the meat of the subject it’s discussing, because it’s not there to teach regular expression purpose and syntax, rather the way to use it in the erlang re library. You wouldn’t criticise a Haines VW Golf manual for not explaining what a carburettor is :-)</div><div dir="ltr"><br></div><div dir="ltr">I’d suggest the “quick start” at <a href="https://regular-expressions.info/">https://regular-expressions.info/</a> to get you off the ground, and the site is a great reference later on as well. The classic book to get if you want a really clear non-screen version is the O’Reilly “Mastering Regular Expressions” by Jeffrey Friedl - in spite of the title it starts from the ground up and doesn’t assume any prior knowledge. Many happy hours spent poring over that tome!</div><div dir="ltr"><br></div><div dir="ltr">Cheers</div><div dir="ltr">Igor</div><div dir="ltr"><br><blockquote type="cite">On 30 Jan 2021, at 17:43, Lloyd R. Prentice <lloyd@writersglen.com> wrote:<br><br></blockquote></div><blockquote type="cite"><div dir="ltr"><span>Hi Dieter,</span><br><span></span><br><span>Thanks for the question. </span><br><span></span><br><span>I don’t like to criticize without having something constructive to contribute. Let me start by saying that I do understand that documentation of software is difficult for many reasons. Nevertheless, here are crucial questions we must ask when we set out to write documentation, indeed, write anything:</span><br><span></span><br><span>— Why am I writing this?</span><br><span>— Who am I writing this for?</span><br><span>— What is the context in which this will be read?</span><br><span>— What would I like my readers to gain by reading this work?</span><br><span>— What do my readers already understand?</span><br><span>— What style/formatting conventions do my readers expect?</span><br><span>— Have I structured my work logically?</span><br><span>— Have I drafted my work as clearly and concisely as I know how?</span><br><span>— Will my readers understand the technical terms or trade jargon that I’m temped to use?</span><br><span></span><br><blockquote type="cite"><span>...it has a nice interface, just a few functions with clear names.</span><br></blockquote><span></span><br><span>My guess, Dieter, is that the re doc works for you because you already have enough knowledge and experience to understand, say, when, where, and why you would want to compile a Regexp or run a (Subject, re). So, you scan down and see compile/1 and your needs are met. But you did have to scan down through some 14 blocks of dense text to find compile/1|2. But— given your need to refresh your memory about use of the compile/1|2 functions, did you really need to scan over the second and third paragraphs under Description? Maybe these should be a footnote.</span><br><span></span><br><span>As one who comes to Erlang re with less experience— I’m totally baffled by compile/1, inspect/2, and run/2|3. What in the world are they? How can they be useful to me? I can kind of sus replace/3|4 and split/2|3, but geez man, all that fine print is brain numbing. And most of the text from Perl-Like Regular Expression Syntax on down looks to me like a tutorial and densely written at that. Do I really need to know that stuff to program, say, an Erlang markdown interpreter? </span><br><span></span><br><span>I could say much more. But my take is that the re doc tries to convey much more information than warranted by a reference doc. This suggests, perhaps, the need for additional documentation such as a cookbook-like re tutorial for Erlang noobies and a technical white paper or some such for folks who need to get their hands greasy with internals.</span><br><span></span><br><span>As I scan down through the list of Erlang standard libraries I see any number of which I’d apply the same critique. So an offer to standard library doc writers: Show me when, why, and how to use your library, and I’ll do my best to help you write clear documentation. </span><br><span></span><br><span>LRP</span><br><span></span><br><span>Sent from my iPad</span><br><span></span><br><blockquote type="cite"><span>On Jan 30, 2021, at 12:30 AM, Dieter Schön <dieter@schoen.or.at> wrote:</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>Good morning,</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>I just looked at the erlang re documentation and I think it has a nice interface,</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>just a few functions with clear names.</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>I always have trouble to remember which of python's re.match and re.search does what.</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>For my taste, there are also enough examples included. Just the PCRE options are a bit overwhelming.</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>It would help if you could elaborate on the areas where you have problems.</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>Kind regards,</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span>Dieter</span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><span></span><br></blockquote><blockquote type="cite"><blockquote type="cite"><span>On 28.01.21 23:26, Lloyd R. Prentice wrote:</span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><span>I’ve used regular expressions including Erlang regex off and on over the years—enough to get the job done but barely enough to claim competence.</span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><span>But I’m sorry— the documentation for re is total inside baseball. Can’t make heads nor tails.</span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><span>Can someone please please suggest or write a tutorial with lots of examples for mortals who just want to get the job done?</span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><span>Happy to collaborate but can only contribute my ignorance.</span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><span>All the best,</span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><span>LRP</span><br></blockquote></blockquote><blockquote type="cite"><blockquote type="cite"><span>Sent from my iPad</span><br></blockquote></blockquote><span></span><br></div></blockquote></body></html>