Newbie questions

perldoc is closer to a database than a simple api help system. It
allows you to search on individual functions, modules, FAQ’s, etc.

Here’s a quick synopsis from “perldoc --help”:

=begin help output
perldoc [options] PageName|ModuleName|ProgramName…
perldoc [options] -f BuiltinFunction
perldoc [options] -q FAQRegex

Options:
-h Display this help message
-r Recursive search (slow)
-i Ignore case
-t Display pod using pod2text instead of pod2man and nroff
(-t is the default on win32 unless -n is specified)
-u Display unformatted pod text
-m Display module’s file in its entirety
-n Specify replacement for nroff
-l Display the module’s file name
-F Arguments are file names, not modules
-v Verbosely describe what’s going on
-X use index if present (looks for pod.idx at C:\Perl\lib)
-q Search the text of questions (not answers) in perlfaq[1-9]
-U Run in insecure mode (superuser only)

PageName>ModuleName…
is the name of a piece of documentation that you want to look
at. You
may either give a descriptive name of the page (as in the case
of
perlfunc') the name of a module, either like Term::Info’ or
like
Term/Info', or the name of a program, like perldoc’.

BuiltinFunction
is the name of a perl function. Will extract documentation
from
`perlfunc’.

FAQRegex
is a regex. Will search perlfaq[1-9] for and extract any
questions that match.

Any switches in the PERLDOC environment variable will be used before the
command line arguments. The optional pod index file contains a list of
filenames, one per line.
=end help output

So, for example, if I wanted everything from the FAQ that talks about
“unique”, I could do this:

perldoc -q unique

and get this:

Found in C:\Perl\lib\pod\perlfaq4.pod
How can I get the unique keys from two hashes?
First you extract the keys from the hashes into lists, then
solve the “removing duplicates” problem described above. For
example:

            %seen = ();
            for $element (keys(%foo), keys(%bar)) {
                $seen{$element}++;
            }
            @uniq = keys %seen;

        Or more succinctly:

            @uniq = keys %{{%foo,%bar}};

        Or if you really want to save space:

            %seen = ();
            while (defined ($key = each %foo)) {
                $seen{$key}++;
            }
            while (defined ($key = each %bar)) {
                $seen{$key}++;
            }
            @uniq = keys %seen;

Found in C:\Perl\lib\pod\perlfaq8.pod
How can I call my system’s unique C functions from Perl?
In most cases, you write an external module to do it–see
the
answer to “Where can I learn about linking C with Perl?
[h2xs,
xsubpp]”. However, if the function is a system call, and
your
system supports syscall(), you can use the syscall function
(documented in perlfunc).

        Remember to check the modules that came with your

distribution,
and CPAN as well–someone may already have written a module
to
do it.

Perl also has a series of “pages” (not sure what the official name is)
such as perlsyn, perlfunc, etc. These pages discuss specific topics,
such as syntax, functions, lists-of-lists, etc, and can be searched via
perldoc as well.

Hope that helps.

Dan

···

-----Original Message-----
From: Hal Fulton [mailto:hal9000@hypermetrics.com]
Sent: Tuesday, December 16, 2003 11:44 AM
To: ruby-talk ML
Subject: Re: Newbie questions

Jamis Buck wrote:

Daniel Carrera wrote:

I haven’t found any (and I’ve been around Ruby for over a year). I
think that Ruby could really benefit from the kind of
documentation
that I’ve seen from Perl.

Any volunteers? :wink:

OK, I’ve heard this discussed before, but as I’m not a
Perler, I don’t know what the big deal is with perldoc.

What is it, what can it do, how is it used, why is it better
than ri, etc.?

Hal

perldoc is closer to a database than a simple api help system. It
allows you to search on individual functions, modules, FAQ’s, etc.

Here’s a quick synopsis from “perldoc --help”:

Cool!

Sorry to say this on a Ruby list, but Perl rocks.

···


Daniel Carrera | “Software is like sex. It’s better when it’s free”.
PhD student. |
Math Dept. UMD | – Linus Torvalds

Berger, Daniel wrote:

perldoc is closer to a database than a simple api help system. It
allows you to search on individual functions, modules, FAQ’s, etc.

Thanks, Daniel B and Daniel C.

That gives me a much clearer idea of what perldoc is, and I see the
appeal of it.

We could always make our own version of the program.

Personally I’d call it “rman” or some such.

If I were designing it, this is how I would approach it:

  • store the data in a canonical format, probably rdoc
  • make converters for HTML, man, etc.
  • make sure all the content of ri is in there (pluggably,
    because this gets updated)
  • make sure there is one canonical version of each piece
    of documentation, versioned, in a central repository
  • I’d like a graphical doc viewer (though maybe a browser
    and HTML might suffice)

That’s a moderately tall order.

The real tall order, though, is producing the content itself (and
controlling the quality and accuracy).

I’d be willing to contribute now and then.

For $10/kilobyte, I’d contribute more frequently. :wink: But I don’t
see that happening.

Cheers,
Hal

Daniel Carrera wrote:

perldoc is closer to a database than a simple api help system. It
allows you to search on individual functions, modules, FAQ’s, etc.

Here’s a quick synopsis from “perldoc --help”:

Cool!

Sorry to say this on a Ruby list, but Perl rocks.

I would say Perl Documentation rocks.

Daniel Carrera wrote:

perldoc is closer to a database than a simple api help system. It
allows you to search on individual functions, modules, FAQ’s, etc.

Here’s a quick synopsis from “perldoc --help”:

Cool!

Sorry to say this on a Ruby list, but Perl rocks.

It’s permissible to speak kindly of one’s parents… :wink:

Hal

— Hal Fulton hal9000@hypermetrics.com wrote:

Personally I’d call it “rman” or some such.

You can’t, it is already taken.

apt-cache showpkg rman

– Thomas Adam

···

=====
“The Linux Weekend Mechanic” – http://linuxgazette.net
“TAG Editor” – http://linuxgazette.net


BT Yahoo! Broadband - Save £80 when you order online today. Hurry! Offer ends 21st December 2003. The way the internet was meant to be. http://uk.rd.yahoo.com/evt=21064/*http://btyahoo.yahoo.co.uk

We could always make our own version of the program.

Personally I’d call it “rman” or some such.

rman sounds good.

If I were designing it, this is how I would approach it:
[snip]

That’s a moderately tall order.

The real tall order, though, is producing the content itself (and
controlling the quality and accuracy).

Indeed. I think that the main thing Perl has is just plain age.
After being very popular for a long time, there has been enough
opportunity for the formation of a good system with good documentation.

If nothing else, we, as a Ruby community, should agree that these are
desirable goals. That is, that we want more than a list of module
names, but we want something like the “rman” you just described.

It’ll take time to make something like this, but if we agree that this
is what we want, then newly-produced documentation can be designed
accordingly.

I’d be willing to contribute now and then.

I’d be willing to contribute a few beginner tutorials.

I think that we should thrive towards a single repository of
documentation like “rman”.

We can start with some basic things like:

rman ruby → Overall description of ruby and a list of other
rman pages. See “man perl”.

rman rubytut → Intro to ruby

We can look at “man perl” for ideas.

Cheers,

···


Daniel Carrera | “Software is like sex. It’s better when it’s free”.
PhD student. |
Math Dept. UMD | – Linus Torvalds

Hal Fulton wrote about writing documentation:

I’d be willing to contribute now and then.

For $10/kilobyte, I’d contribute more frequently. :wink: But I don’t
see that happening.

Cheers,
Hal

I would pay $25 for a printed version of any ruby related stuff.
For example Mr.Webber could make some ‘nice prints’ for the StdLibApi
Doc and sale it
to get something in return for his effort…I’ll pay $25 for it.

If we just were more organized …(dreaming)…

-r.

Hal Fulton wrote:

I’d be willing to contribute now and then.

Then please consider (if you haven’t already) joining the ruby-doc
mailing list and pitching in (even if only with ideas) to the Ruby
Documentation Project

You can find list subscription info at http://www.ruby-doc.org

For $10/kilobyte, I’d contribute more frequently. :wink: But I don’t
see that happening.

All too true. But now and again folks do get paid to write articles on
Ruby for assorted magazines.

James

···

Cheers,
Hal

perldoc is closer to a database than a simple api help system. It
allows you to search on individual functions, modules, FAQ’s, etc.

Here’s a quick synopsis from “perldoc --help”:

Cool!

Sorry to say this on a Ruby list, but Perl rocks.

I would say Perl Documentation rocks.

Good documentation is part of what makes a language great. Not just the
language itself. I would also point out the availability of mature
modules as well as the ability to find them easily. I do think that
some of the greatest things about Perl are CPAN and its documentation.

Those two things can some times be enough to offset the technical merit
of a younger language.

Besides, even as “just a language”, Perl does rock. Even if Ruby is a
better language than Perl, that doesn’t make Perl bad.

I do think that the biggest things holding Ruby back (IMHO) are
documentation and availability of mature modules.

Cheers,

···


Daniel Carrera | “Software is like sex. It’s better when it’s free”.
PhD student. |
Math Dept. UMD | – Linus Torvalds

Thomas Adam wrote:

— Hal Fulton hal9000@hypermetrics.com wrote:

Personally I’d call it “rman” or some such.

You can’t, it is already taken.

apt-cache showpkg rman

Oops. How about “rperson”? :wink:

Actually I’ve always liked the name RubyLaser. Surely that one will be
used eventually. I hope the software is worthy of the name when it is.

Is “laser” a suitable name?

Hal

Personally I’d call it “rman” or some such.

You can’t, it is already taken.

apt-cache showpkg rman

Oops. How about “rperson”? :wink:

Actually I’ve always liked the name RubyLaser. Surely that one will be
used eventually. I hope the software is worthy of the name when it is.

Is “laser” a suitable name?

Now, why do we have to pick a creative name? Why don’t we pick a boring
uncreative name that is easy to remember, like “rubydoc”.

One beef I have with many OSS products is that they like choosing
creative but uninformative names like “Evolution”, or “Gimp”.

Don’t take me wrong, I don’t think that we should use dumb names like
“KSpreadSheet”, “KWordProcessor” or “KMailClient”. There has to be a
balance. Names like “OpenOffice” and “Abiword” are good.

Cheers,

···


Daniel Carrera | “Software is like sex. It’s better when it’s free”.
PhD student. |
Math Dept. UMD | – Linus Torvalds

Good documentation is part of what makes a language great. Not just the
language itself. I would also point out the availability of mature
modules as well as the ability to find them easily. I do think that
some of the greatest things about Perl are CPAN and its documentation.

Those two things can some times be enough to offset the technical merit
of a younger language.

Besides, even as “just a language”, Perl does rock. Even if Ruby is a
better language than Perl, that doesn’t make Perl bad.

I do think that the biggest things holding Ruby back (IMHO) are
documentation and availability of mature modules.

I couldn’t agree more.

Wow, I see my simple questions have started quite a long thread. I
started looking at Ruby because of a book I am reading “Code
Generation In Action”. Most people on this list know all about the
ruby “goodness” (object oriented goodness, clean syntax, simple yet
powerful, yield, etc…).

After taking a pretty good look, I am going to state why I will not
switch to Ruby for my scripting/programming tasks (at least not yet!).

  • Good documentation
  • Good documentation reader
  • Repository of mature modules
  • Repository that can be access from the command line and execute
    various actions (search, install, etc…)
  • Unit testing built into a standard build/install process.
  • A standard way to package up a module with docs/code/tests include
  • The ability to overload constructors.

Besides that, I am enjoying using the language while going through the
book referenced above.

Cheers,
JF

Daniel Carrera wrote:

Personally I’d call it “rman” or some such.

You can’t, it is already taken.

apt-cache showpkg rman

Oops. How about “rperson”? :wink:

Actually I’ve always liked the name RubyLaser. Surely that one will be
used eventually. I hope the software is worthy of the name when it is.

Is “laser” a suitable name?

Now, why do we have to pick a creative name? Why don’t we pick a boring
uncreative name that is easy to remember, like “rubydoc”.

:slight_smile:

I care much less about the name than the software functionality and
the content it exposes.

But as an old-time Unix hacker, I prefer short names. Two letters is
best, but my usual threshold is around five.

That’s one reason I like “lin” (on Lunar Linux) better than apt-get or
whatever. Though I will probably end up running Fedora instead…

Hal

GIMP isn’t “uninformative.” It’s the GNU Image Manipulation Program.

-austin

···

On Wed, 17 Dec 2003 04:41:42 +0900, Daniel Carrera wrote:

Now, why do we have to pick a creative name? Why don’t we pick a boring
uncreative name that is easy to remember, like “rubydoc”.

One beef I have with many OSS products is that they like choosing
creative but uninformative names like “Evolution”, or “Gimp”.


austin ziegler * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.12.16
* 15.45.15

I don’t know. Those seem like good reasons to switch. Look at it as an
oppotunity to provide something nice for the community. That’s how perl
got to the place it is now, and it’s the only way ruby will achieve the
same.

Regards,
Randy.

···

On 12/18/2003 1:11 AM, Jim Frapper wrote:

Good documentation is part of what makes a language great. Not just the
language itself. I would also point out the availability of mature
modules as well as the ability to find them easily. I do think that
some of the greatest things about Perl are CPAN and its documentation.

Those two things can some times be enough to offset the technical merit
of a younger language.

Besides, even as “just a language”, Perl does rock. Even if Ruby is a
better language than Perl, that doesn’t make Perl bad.

I do think that the biggest things holding Ruby back (IMHO) are
documentation and availability of mature modules.

I couldn’t agree more.

Wow, I see my simple questions have started quite a long thread. I
started looking at Ruby because of a book I am reading “Code
Generation In Action”. Most people on this list know all about the
ruby “goodness” (object oriented goodness, clean syntax, simple yet
powerful, yield, etc…).

After taking a pretty good look, I am going to state why I will not
switch to Ruby for my scripting/programming tasks (at least not yet!).

  • Good documentation
  • Good documentation reader
  • Repository of mature modules
  • Repository that can be access from the command line and execute
    various actions (search, install, etc…)
  • Unit testing built into a standard build/install process.
  • A standard way to package up a module with docs/code/tests include
  • The ability to overload constructors.

Besides that, I am enjoying using the language while going through the
book referenced above.

Cheers,
JF

Jim Frapper wrote:

  • The ability to overload constructors.

The way multiple constructors should probably be done in Ruby is similar
to the
way people do it in Smalltalk. For example, if you’re modeling a
mathematical
plane in Smalltalk, you might define the following constructors:

withPoint: p1 withPoint: p2 withPoint: p3

withPoint: p withNormalVector: n

doing:

plane ← Plane new

Would just make a default plane with no instance variables set, while

plane ← Plane withPoint: point1 withNormalVector: vector

Would make a fully qualified plane.

Analogues in Ruby would go something like:

class Plane
def Plane.fromPoints(p1, p2, p3)

end

def Plane.fromPointAndNormal(p, n)
   ...
end

end

There’s nothing special about #new that means it’s the only thing you’re
allowed to call a constructor (or that you need to allow it to be a public
constructor at all. In the above example, you’d probably want to make it
private). All you need to do is possibly broaden your
definition of constructor a bit.

  • Dan

YAGNI. There is no method overloading at all in Ruby at this point –
because Ruby isn’t restricted by static typing, and in my experience, it’s
not necessary. See my port of MIME::Types or Text::Format for how multiple
constructor forms can be provided in the singular mechanism – and it’s not
even necessarily the preferred way in Ruby.

-austin

···

On Thu, 18 Dec 2003 15:11:55 +0900, Jim Frapper wrote:

  • The ability to overload constructors.


austin ziegler * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.12.18
* 15.23.26

Now, why do we have to pick a creative name? Why don’t we pick a boring
uncreative name that is easy to remember, like “rubydoc”.

:slight_smile:

I care much less about the name than the software functionality and
the content it exposes.

But as an old-time Unix hacker, I prefer short names. Two letters is
best, but my usual threshold is around five.

That’s one reason I like “lin” (on Lunar Linux) better than apt-get or
whatever. Though I will probably end up running Fedora instead…

I hear you. Names with dashes are the worst (“apt-get”). My fingers
have to physically pause for a second to type a dash.

Oh, wait… how about “rdoc”?

That would rock. The name of the program could be the same as the name
of the documentation system, and at the same time be a sensible name.

If you like the name “rdoc” raise your hand.

Cheers,

···


Daniel Carrera | “Software is like sex. It’s better when it’s free”.
PhD student. |
Math Dept. UMD | – Linus Torvalds

It’s unly informative if you already know that. Like GNU or PINE.

···

On Wed, Dec 17, 2003 at 05:46:02AM +0900, Austin Ziegler wrote:

On Wed, 17 Dec 2003 04:41:42 +0900, Daniel Carrera wrote:

Now, why do we have to pick a creative name? Why don’t we pick a boring
uncreative name that is easy to remember, like “rubydoc”.

One beef I have with many OSS products is that they like choosing
creative but uninformative names like “Evolution”, or “Gimp”.

GIMP isn’t “uninformative.” It’s the GNU Image Manipulation Program.


Daniel Carrera | “Software is like sex. It’s better when it’s free”.
PhD student. |
Math Dept. UMD | – Linus Torvalds