Erlang re docs

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Erlang re docs

Lloyd R. Prentice-2
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.

But I’m sorry— the documentation for re is total inside baseball. Can’t make heads nor tails.

Can someone please please suggest or write a tutorial with lots of examples for mortals who just want to get the job done?

Happy to collaborate but can only contribute my ignorance.

All the best,

LRP

Sent from my iPad
Reply | Threaded
Open this post in threaded view
|

Re: Erlang re docs

Austin Ziegler
Erlang RE is based on PCRE2, so starting with a PCRE tutorial is
likely to help understanding of Erlang RE. (I mostly use re via
Elixir’s re support, but I have to look at Elixir, Erlang, and PCRE
documentation from time to time to understand certain features.
Fortunately, it’s all fairly similar to Onigmo, the Ruby re library
I’m most familiar with.)

-a

On Thu, Jan 28, 2021 at 5:26 PM Lloyd R. Prentice <[hidden email]> wrote:

>
> 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.
>
> But I’m sorry— the documentation for re is total inside baseball. Can’t make heads nor tails.
>
> Can someone please please suggest or write a tutorial with lots of examples for mortals who just want to get the job done?
>
> Happy to collaborate but can only contribute my ignorance.
>
> All the best,
>
> LRP
>
> Sent from my iPad



--
Austin Ziegler • [hidden email][hidden email]
http://www.halostatue.ca/ • http://twitter.com/halostatue
Reply | Threaded
Open this post in threaded view
|

Re: Erlang re docs

Hugo Mills-2
In reply to this post by Lloyd R. Prentice-2
On Thu, Jan 28, 2021 at 05:26:08PM -0500, Lloyd R. Prentice wrote:
> 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.
>
> But I’m sorry— the documentation for re is total inside baseball. Can’t make heads nor tails.
>
> Can someone please please suggest or write a tutorial with lots of examples for mortals who just want to get the job done?

   What are you having problems with? The API, or the regular
expressions themselves?

   Hugo.

--
Hugo Mills             | Great films about cricket: The Third Man
hugo@... carfax.org.uk |
http://carfax.org.uk/  |
PGP: E2AB1DE4          |
Reply | Threaded
Open this post in threaded view
|

Re: Erlang re docs

Dieter Schön
In reply to this post by Lloyd R. Prentice-2
Good morning,

I just looked at the erlang re documentation and I think it has a nice
interface,

just a few functions with clear names.

I always have trouble to remember which of python's re.match and
re.search does what.


For my taste, there are also enough examples included. Just the PCRE
options are a bit overwhelming.

It would help if you could elaborate on the areas where you have problems.


Kind regards,

Dieter


On 28.01.21 23:26, Lloyd R. Prentice wrote:

> 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.
>
> But I’m sorry— the documentation for re is total inside baseball. Can’t make heads nor tails.
>
> Can someone please please suggest or write a tutorial with lots of examples for mortals who just want to get the job done?
>
> Happy to collaborate but can only contribute my ignorance.
>
> All the best,
>
> LRP
>
> Sent from my iPad
Reply | Threaded
Open this post in threaded view
|

Re: Erlang re docs

Lloyd R. Prentice-2
In reply to this post by Lloyd R. Prentice-2
Hi Dieter,

Thanks for the question.  

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:

— Why am I writing this?
— Who am I writing this for?
— What is the context in which this will be read?
— What would I like my readers to gain by reading this work?
— What do my readers already understand?
— What style/formatting conventions do my readers expect?
— Have I structured my work logically?
— Have I drafted my work as clearly and concisely as I know how?
— Will my readers understand the technical terms or trade jargon that I’m temped to use?

> ...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.

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.

LRP

Sent from my iPad

> On Jan 30, 2021, at 12:30 AM, Dieter Schön <[hidden email]> wrote:
>
> Good morning,
>
> I just looked at the erlang re documentation and I think it has a nice interface,
>
> just a few functions with clear names.
>
> I always have trouble to remember which of python's re.match and re.search does what.
>
>
> For my taste, there are also enough examples included. Just the PCRE options are a bit overwhelming.
>
> It would help if you could elaborate on the areas where you have problems.
>
>
> Kind regards,
>
> Dieter
>
>
>> On 28.01.21 23:26, Lloyd R. Prentice wrote:
>> 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.
>> But I’m sorry— the documentation for re is total inside baseball. Can’t make heads nor tails.
>> Can someone please please suggest or write a tutorial with lots of examples for mortals who just want to get the job done?
>> Happy to collaborate but can only contribute my ignorance.
>> All the best,
>> LRP
>> Sent from my iPad

Reply | Threaded
Open this post in threaded view
|

Re: Erlang re docs

Loïc Hoguin-3
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
Reply | Threaded
Open this post in threaded view
|

Re: Erlang re docs

Attila Rajmund Nohl
In reply to this post by Lloyd R. Prentice-2
Lloyd R. Prentice <[hidden email]> ezt írta (időpont: 2021.
jan. 30., Szo, 18:43):
[...]
> 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.

I don't. On the https://erlang.org/doc/search/ page I can select the
function name from the menu on the left hand side.

> 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.

Actually those paragraphs are information for newbies like you. For
refreshing information (or just checking exactly how that option is
called) it's very easy to scan over those.

> 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?

Well, regular expressions can be complicated beasts. For those coming
from UNIX/Linux background, basic understanding of regular expressions
(as used by tools like grep, sed, vi) is given. I actually like that
the Erlang documentation doesn't punt the problem away with a link to
some other page about regular expressions, but includes a description,
especially because the regular expressions used by different tools and
programming environments are really similar, but do have their
differences. I believe Markdown grammar is not a Chomsky type-3
grammar, so you won't be able to parse Markdown purely by regular
expressions.
Reply | Threaded
Open this post in threaded view
|

Re: Erlang re docs

Igor Clark
In reply to this post by Lloyd R. Prentice-2
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.

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.

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 :-)

I’d suggest the “quick start” at https://regular-expressions.info/ 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!

Cheers
Igor

On 30 Jan 2021, at 17:43, Lloyd R. Prentice <[hidden email]> wrote:

Hi Dieter,

Thanks for the question.  

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:

— Why am I writing this?
— Who am I writing this for?
— What is the context in which this will be read?
— What would I like my readers to gain by reading this work?
— What do my readers already understand?
— What style/formatting conventions do my readers expect?
— Have I structured my work logically?
— Have I drafted my work as clearly and concisely as I know how?
— Will my readers understand the technical terms or trade jargon that I’m temped to use?

...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.

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.

LRP

Sent from my iPad

On Jan 30, 2021, at 12:30 AM, Dieter Schön <[hidden email]> wrote:

Good morning,

I just looked at the erlang re documentation and I think it has a nice interface,

just a few functions with clear names.

I always have trouble to remember which of python's re.match and re.search does what.


For my taste, there are also enough examples included. Just the PCRE options are a bit overwhelming.

It would help if you could elaborate on the areas where you have problems.


Kind regards,

Dieter


On 28.01.21 23:26, Lloyd R. Prentice wrote:
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.
But I’m sorry— the documentation for re is total inside baseball. Can’t make heads nor tails.
Can someone please please suggest or write a tutorial with lots of examples for mortals who just want to get the job done?
Happy to collaborate but can only contribute my ignorance.
All the best,
LRP
Sent from my iPad

Reply | Threaded
Open this post in threaded view
|

Re: Erlang re docs

Lloyd R. Prentice-2
Sorry guys, I do understand regular expressions well enough to use them the rare times when I need them.  I have read PCRE docs and various others and I would say that they are generally better written and presented than the re reference doc. And I do understand that regular expressions and Erlang are two completely different languages.

If the community is satisfied with the docs as they are then there’s nothing more to say.

But I do contend that there’s a problem. Software docs need to be fit for purpose.  In-line code comments, library references, tutorials, and technical white papers are all different formats with different functions and conventions. A language needs them all to attract and sustain a robust community. My read is that the re doc conflates these functions in a confusing and distracting text that well may discourage folks new to Erlang.

Assertions:

— Erlang is a tool.
— The value of a tool is the efficiency and effectiveness with which it solves real-world problems.
— As programmer, time is our most precious asset.
— A software library that is inadequately documented likely wastes our time when we first strive to understand why and how to use it, when we seek to refresh our memory of how to use it, and when we wish to extend it’s functionality.

When I turned to re to solve a problem at hand, the re doc was 90 percent a waste of my time. And that, sorry to say, diminishes the value of Erlang for me as a tool.

 I’m wondering how many others may have had the same experience. And how many of those have rejected Erlang as too much bother to learn.

Best wishes,

LRP

Sent from my iPad

On Jan 30, 2021, at 1:22 PM, Igor Clark <[hidden email]> wrote:


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.

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.

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 :-)

I’d suggest the “quick start” at https://regular-expressions.info/ 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!

Cheers
Igor

On 30 Jan 2021, at 17:43, Lloyd R. Prentice <[hidden email]> wrote:

Hi Dieter,

Thanks for the question.  

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:

— Why am I writing this?
— Who am I writing this for?
— What is the context in which this will be read?
— What would I like my readers to gain by reading this work?
— What do my readers already understand?
— What style/formatting conventions do my readers expect?
— Have I structured my work logically?
— Have I drafted my work as clearly and concisely as I know how?
— Will my readers understand the technical terms or trade jargon that I’m temped to use?

...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.

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.

LRP

Sent from my iPad

On Jan 30, 2021, at 12:30 AM, Dieter Schön <[hidden email]> wrote:

Good morning,

I just looked at the erlang re documentation and I think it has a nice interface,

just a few functions with clear names.

I always have trouble to remember which of python's re.match and re.search does what.


For my taste, there are also enough examples included. Just the PCRE options are a bit overwhelming.

It would help if you could elaborate on the areas where you have problems.


Kind regards,

Dieter


On 28.01.21 23:26, Lloyd R. Prentice wrote:
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.
But I’m sorry— the documentation for re is total inside baseball. Can’t make heads nor tails.
Can someone please please suggest or write a tutorial with lots of examples for mortals who just want to get the job done?
Happy to collaborate but can only contribute my ignorance.
All the best,
LRP
Sent from my iPad

Reply | Threaded
Open this post in threaded view
|

Re: Erlang re docs

Igor Clark
Hi Lloyd, I understand your points, but I think we'll have to agree to disagree on this one! Even just looking at the index to the re module docs, you get "compile, inspect, replace, run, split", and that really is pretty much all there is to it. I mean, you write a regex, you compile it, you run it on a string and check the matches. Maybe you split them or replace segments of them with it. That's it. The rest is either regex syntax or language-specific implementation detail / configuration options. Regex syntax documentation and tutorials are very widely available, and the details of the erlang implementation are comprehensively specced in the appropriate place in the docs.

I don't really want to get into the whole community/expansion can of worms here, because I feel like it's been implicitly done to death in The Other Thread(!) - but my personal view is that if people decide to reject erlang (and OTP!) because its regex docs are too terse, well, uh, that's a shame for them, because that's *really* not what it's about. I think the fact that the regex docs are so terse (read: limited to describing the erlang PCRE implementation/wrapper, on the assumption that regex documentation is available elsewhere) is indicative of that.

Best
Igor

On 30 Jan 2021, at 19:32, Lloyd R. Prentice <[hidden email]> wrote:

Sorry guys, I do understand regular expressions well enough to use them the rare times when I need them.  I have read PCRE docs and various others and I would say that they are generally better written and presented than the re reference doc. And I do understand that regular expressions and Erlang are two completely different languages.

If the community is satisfied with the docs as they are then there’s nothing more to say.

But I do contend that there’s a problem. Software docs need to be fit for purpose.  In-line code comments, library references, tutorials, and technical white papers are all different formats with different functions and conventions. A language needs them all to attract and sustain a robust community. My read is that the re doc conflates these functions in a confusing and distracting text that well may discourage folks new to Erlang.

Assertions:

— Erlang is a tool.
— The value of a tool is the efficiency and effectiveness with which it solves real-world problems.
— As programmer, time is our most precious asset.
— A software library that is inadequately documented likely wastes our time when we first strive to understand why and how to use it, when we seek to refresh our memory of how to use it, and when we wish to extend it’s functionality.

When I turned to re to solve a problem at hand, the re doc was 90 percent a waste of my time. And that, sorry to say, diminishes the value of Erlang for me as a tool.

 I’m wondering how many others may have had the same experience. And how many of those have rejected Erlang as too much bother to learn.

Best wishes,

LRP

Sent from my iPad

On Jan 30, 2021, at 1:22 PM, Igor Clark <[hidden email]> wrote:


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.

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.

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 :-)

I’d suggest the “quick start” at https://regular-expressions.info/ 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!

Cheers
Igor

On 30 Jan 2021, at 17:43, Lloyd R. Prentice <[hidden email]> wrote:

Hi Dieter,

Thanks for the question.  

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:

— Why am I writing this?
— Who am I writing this for?
— What is the context in which this will be read?
— What would I like my readers to gain by reading this work?
— What do my readers already understand?
— What style/formatting conventions do my readers expect?
— Have I structured my work logically?
— Have I drafted my work as clearly and concisely as I know how?
— Will my readers understand the technical terms or trade jargon that I’m temped to use?

...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.

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.

LRP

Sent from my iPad

On Jan 30, 2021, at 12:30 AM, Dieter Schön <[hidden email]> wrote:

Good morning,

I just looked at the erlang re documentation and I think it has a nice interface,

just a few functions with clear names.

I always have trouble to remember which of python's re.match and re.search does what.


For my taste, there are also enough examples included. Just the PCRE options are a bit overwhelming.

It would help if you could elaborate on the areas where you have problems.


Kind regards,

Dieter


On 28.01.21 23:26, Lloyd R. Prentice wrote:
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.
But I’m sorry— the documentation for re is total inside baseball. Can’t make heads nor tails.
Can someone please please suggest or write a tutorial with lots of examples for mortals who just want to get the job done?
Happy to collaborate but can only contribute my ignorance.
All the best,
LRP
Sent from my iPad


Reply | Threaded
Open this post in threaded view
|

Re: Erlang re docs

Lloyd R. Prentice-2
In reply to this post by Lloyd R. Prentice-2
Hi Igor,

> ...you get "compile, inspect, replace, run, split", and that really is pretty much all there is to it. I mean, you write a regex, you compile it, you run it on a string and check the matches.

You’ve pretty much just written a nice succinct tutorial. Explain why we may  need to compile the regex, e.g. rather than just run the regexp from the parameter field, add well-selected examples for each function, and now we have a document from which one can get the gist with a rapid look up. A footnote pointing to useful details might round it out. 

Best,

LRP



Sent from my iPad

On Jan 30, 2021, at 3:35 PM, Igor Clark <[hidden email]> wrote:


Hi Lloyd, I understand your points, but I think we'll have to agree to disagree on this one! Even just looking at the index to the re module docs, you get "compile, inspect, replace, run, split", and that really is pretty much all there is to it. I mean, you write a regex, you compile it, you run it on a string and check the matches. Maybe you split them or replace segments of them with it. That's it. The rest is either regex syntax or language-specific implementation detail / configuration options. Regex syntax documentation and tutorials are very widely available, and the details of the erlang implementation are comprehensively specced in the appropriate place in the docs.

I don't really want to get into the whole community/expansion can of worms here, because I feel like it's been implicitly done to death in The Other Thread(!) - but my personal view is that if people decide to reject erlang (and OTP!) because its regex docs are too terse, well, uh, that's a shame for them, because that's *really* not what it's about. I think the fact that the regex docs are so terse (read: limited to describing the erlang PCRE implementation/wrapper, on the assumption that regex documentation is available elsewhere) is indicative of that.

Best
Igor

On 30 Jan 2021, at 19:32, Lloyd R. Prentice <[hidden email]> wrote:

Sorry guys, I do understand regular expressions well enough to use them the rare times when I need them.  I have read PCRE docs and various others and I would say that they are generally better written and presented than the re reference doc. And I do understand that regular expressions and Erlang are two completely different languages.

If the community is satisfied with the docs as they are then there’s nothing more to say.

But I do contend that there’s a problem. Software docs need to be fit for purpose.  In-line code comments, library references, tutorials, and technical white papers are all different formats with different functions and conventions. A language needs them all to attract and sustain a robust community. My read is that the re doc conflates these functions in a confusing and distracting text that well may discourage folks new to Erlang.

Assertions:

— Erlang is a tool.
— The value of a tool is the efficiency and effectiveness with which it solves real-world problems.
— As programmer, time is our most precious asset.
— A software library that is inadequately documented likely wastes our time when we first strive to understand why and how to use it, when we seek to refresh our memory of how to use it, and when we wish to extend it’s functionality.

When I turned to re to solve a problem at hand, the re doc was 90 percent a waste of my time. And that, sorry to say, diminishes the value of Erlang for me as a tool.

 I’m wondering how many others may have had the same experience. And how many of those have rejected Erlang as too much bother to learn.

Best wishes,

LRP

Sent from my iPad

On Jan 30, 2021, at 1:22 PM, Igor Clark <[hidden email]> wrote:


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.

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.

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 :-)

I’d suggest the “quick start” at https://regular-expressions.info/ 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!

Cheers
Igor

On 30 Jan 2021, at 17:43, Lloyd R. Prentice <[hidden email]> wrote:

Hi Dieter,

Thanks for the question.  

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:

— Why am I writing this?
— Who am I writing this for?
— What is the context in which this will be read?
— What would I like my readers to gain by reading this work?
— What do my readers already understand?
— What style/formatting conventions do my readers expect?
— Have I structured my work logically?
— Have I drafted my work as clearly and concisely as I know how?
— Will my readers understand the technical terms or trade jargon that I’m temped to use?

...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.

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.

LRP

Sent from my iPad

On Jan 30, 2021, at 12:30 AM, Dieter Schön <[hidden email]> wrote:

Good morning,

I just looked at the erlang re documentation and I think it has a nice interface,

just a few functions with clear names.

I always have trouble to remember which of python's re.match and re.search does what.


For my taste, there are also enough examples included. Just the PCRE options are a bit overwhelming.

It would help if you could elaborate on the areas where you have problems.


Kind regards,

Dieter


On 28.01.21 23:26, Lloyd R. Prentice wrote:
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.
But I’m sorry— the documentation for re is total inside baseball. Can’t make heads nor tails.
Can someone please please suggest or write a tutorial with lots of examples for mortals who just want to get the job done?
Happy to collaborate but can only contribute my ignorance.
All the best,
LRP
Sent from my iPad


Reply | Threaded
Open this post in threaded view
|

Re: Erlang re docs

Loïc Hoguin-3
On 31/01/2021 00:25, Lloyd R. Prentice wrote:
> Hi Igor,
>
>> ...you get "compile, inspect, replace, run, split", and that really is pretty much all there is to it. I mean, you write a regex, you compile it, you run it on a string and check the matches.
>
> You’ve pretty much just written a nice succinct tutorial. Explain why we
> may  need to compile the regex, e.g. rather than just run the regexp
> from the parameter field, add well-selected examples for each function,
> and now we have a document from which one can get the gist with a rapid
> look up. A footnote pointing to useful details might round it out.

It's already there.

"Compiling the regular expression before matching is useful if the same
expression is to be used in matching against multiple subjects during
the lifetime of the program. Compiling once and executing many times is
far more efficient than compiling each time one wants to match."

Anyway if you think things would be better done another way, send a PR.

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