I am trying to understand how to find out how to use a gem that I have installed -
specifically fuzzy-string-match. I have not been able to find a description - rdoc
etc. are as easy to read as Sanskrit - is there an introduction to these mysteries
for the newcomer anywhere?
Is the issue that you don't know how to call the methods (which the
documentation shows), or that you don't know what and how to implement
a fuzzy search? The gem is giving you the means to calculate
"distance" between two strings (the algorithm is named "Jaro-Winkler"
which is the measure of similarity between two strings, c.f. https://en.wikipedia.org/wiki/Jaro–Winkler_distance), from
that you can choose how much "fuzziness" to apply, which can be highly
domain-specific.
I am trying to understand how to find out how to use a gem that I have
installed -
specifically fuzzy-string-match. I have not been able to find a description
- rdoc
etc. are as easy to read as Sanskrit - is there an introduction to these
mysteries
for the newcomer anywhere?
The issue is that I don't know how to read the documentation. Where, or how, does it show how to
call the methods? I would have thought there would be a general description somewhere explaining
the structure of Github or Gem documentation.
All I have found so far are disjointed fragments of code and some legalese. I only mention
fuzzy-string-match as an example. It might be easier for me to write my own code based on
theoretical descriptions of matching algorithms.
I am trying to understand how to find out how to use a gem that I have
installed -
specifically fuzzy-string-match. I have not been able to find a description
- rdoc
etc. are as easy to read as Sanskrit - is there an introduction to these
mysteries
for the newcomer anywhere?
Is the issue that you don't know how to call the methods (which the
documentation shows), or that you don't know what and how to implement
a fuzzy search? The gem is giving you the means to calculate
"distance" between two strings (the algorithm is named "Jaro-Winkler"
which is the measure of similarity between two strings, c.f. https://en.wikipedia.org/wiki/Jaro–Winkler_distance), from
that you can choose how much "fuzziness" to apply, which can be highly
domain-specific.
Github is way beyond the scope of a single gem to describe.
The README.md file in the repo pointed at by Mateusz shows how to make
the calls in the Sample Code section.
If the README.md file had been written as a README.rdoc, it would have
been included in the gem rdocs. That doesn't seem to be much in
practice any more as most people go to Github to find gems. Not sure
what to do about it.
The issue is that I don't know how to read the documentation. Where, or how,
does it show how to
call the methods? I would have thought there would be a general description
somewhere explaining
the structure of Github or Gem documentation.
When you install a gem in your machine, you can use "gem server" and go to
localhost:8808 to see its RDoc documentation in your browser.
But I must agree with you that lots of gems have awful documentation - I
lost count of how many times I had to read the code (ruby or C) to
understand what was going on and how to use/extend it. That's a problem we
should address.
Unfortunately, this seems to be the case with fuzzy-string-match. There's
no documentation except for the README - which is "fine" as its API is
extremely simple (there's just one method to call).
···
-----
Carlos Agarie
Control engineering
Polytechnic School, University of São Paulo, Brazil
Computer engineering
Embry-Riddle Aeronautical University, USA
On Tue, Jan 1, 2013 at 8:29 AM, John Sampson <jrs.idx@ntlworld.com> wrote:
> The issue is that I don't know how to read the documentation. Where, or
how,
> does it show how to
> call the methods? I would have thought there would be a general
description
> somewhere explaining
> the structure of Github or Gem documentation.
Github is way beyond the scope of a single gem to describe.
The README.md file in the repo pointed at by Mateusz shows how to make
the calls in the Sample Code section.
If the README.md file had been written as a README.rdoc, it would have
been included in the gem rdocs. That doesn't seem to be much in
practice any more as most people go to Github to find gems. Not sure
what to do about it.
So README.md is where one looks, and it is in the 'repo', whatever that is. I see that
the method ".create" is a combination of ".new" and ".save" - What does ".save" do?
For idle curiosity, what does ".md" mean? What are rdocs for? Are they no longer
useful?
The issue is that I don't know how to read the documentation. Where, or how,
does it show how to
call the methods? I would have thought there would be a general description
somewhere explaining
the structure of Github or Gem documentation.
Github is way beyond the scope of a single gem to describe.
The README.md file in the repo pointed at by Mateusz shows how to make
the calls in the Sample Code section.
If the README.md file had been written as a README.rdoc, it would have
been included in the gem rdocs. That doesn't seem to be much in
practice any more as most people go to Github to find gems. Not sure
what to do about it.
A "repo" is a repository. It's the place where your project is stored via
git, e.g. the git repository of fuzzy-string-match is hosted by Github and
is accessible via the URL git://github.com/kiyoka/fuzzy-string-match.git.
".md" is a format called Markdown, a plain text to HTML converter meant for
web usage. It's very simple and it's used in lots of places (e.g. Github,
Stackoverflow). You can read more about in this link: http://daringfireball.net/projects/markdown/
Finally, the method `create` is used to generate an object that will do the
work you need, at least this is what I get from reading the README:
If you have specific doubts about how to use this gem and/or want more
documentation (and you should), please create a free Github account and
open an issue in the issue tracker:
···
-----
Carlos Agarie
Control engineering
Polytechnic School, University of São Paulo, Brazil
Computer engineering
Embry-Riddle Aeronautical University, USA
The issue is that I don't know how to read the documentation. Where, or
how,
does it show how to
call the methods? I would have thought there would be a general
description
somewhere explaining
the structure of Github or Gem documentation.
Github is way beyond the scope of a single gem to describe.
The README.md file in the repo pointed at by Mateusz shows how to make
the calls in the Sample Code section.
If the README.md file had been written as a README.rdoc, it would have
been included in the gem rdocs. That doesn't seem to be much in
practice any more as most people go to Github to find gems. Not sure
what to do about it.
So README.md is where one looks, and it is in the 'repo', whatever that
is. I see that
the method ".create" is a combination of ".new" and ".save" - What does
".save" do?
For idle curiosity, what does ".md" mean? What are rdocs for? Are they no
longer
useful?
Many thanks for these pointers, especially the last one. I see that fuzzy-string-match has issues not fixed in the last nine months, so that saves me
some time!
Regards
_John Sampson_
···
On 01/01/2013 17:11, Carlos Agarie wrote:
A "repo" is a repository. It's the place where your project is stored via git, e.g. the git repository of fuzzy-string-match is hosted by Github and is accessible via the URL git://github.com/kiyoka/fuzzy-string-match.git <http://github.com/kiyoka/fuzzy-string-match.git>.
".md" is a format called Markdown, a plain text to HTML converter meant for web usage. It's very simple and it's used in lots of places (e.g. Github, Stackoverflow). You can read more about in this link: http://daringfireball.net/projects/markdown/
If you have specific doubts about how to use this gem and/or want more documentation (and you should), please create a free Github account and open an issue in the issue tracker: https://github.com/kiyoka/fuzzy-string-match/issues