Re: Erlang re docs

On 30/01/2021 18:43, Lloyd R. Prentice wrote:
[...]
>> ...it has a nice interface, just a few functions with clear names.
> 
> 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.
> 
> 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?
> 
> 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.

You're conflating things. Regular expressions and Erlang are two 
completely different languages, where Erlang merely provides an 
interface to using regular expressions. It is not in anyone's interest 
to maintain another set of regexp tutorials for Erlang, it'd be like 
saying Erlang should come with C tutorials because it provides NIFs.

There's plenty of examples and tutorials just about everywhere. An oldie 
but goodie start would be at 
https://www.regular-expressions.info/examples.html?wlr=1

It's not a documentation problem, the documentation is perfectly fine, 
it's just that you do not possess the requisite knowledge. The re 
documentation is meant for people who have already used regular expressions.

 > And most of the text from Perl-Like Regular Expression Syntax on down 
looks to me like a tutorial and densely written at that.

It's the specification, not a tutorial. You must know regular 
expressions or be smart like a ROK to make use of it.

 > Do I really need to know that stuff to program, say, an Erlang 
markdown interpreter?

Regular expressions are very high level and tend to be very difficult to 
read, they're more of a write-once kind of thing, fine in quick and 
dirty shell scripts or for a quick email validator.

I would highly recommend against using regular expressions for any 
parser, except for parser generators such as yecc (because in that case 
the regexps tends to be small and focused on a single element).

That said, many Markdown parsers are implemented using regular 
expressions. But those are usually doing the parsing and transforming 
into HTML in one step, they don't give you something you can manipulate, 
for example some kind of AST.

And of course, there's so many Markdown parsers anyway that you don't 
need to write one unless you have very specific needs. But I don't think 
you would if you're looking at regular expressions.

-- 
Loïc Hoguin
https://ninenines.eu