ANN: PLD RPMs of rake and ruby-dbi and a plea to packagers

[Aredridel]

I've just created packages (including .spec files to be used as
templates in other distros) of rake and ruby-dbi for the PLD GNU/Linux
distribution. They should be at the builders reasonably quickly, and
available for general consumption after that.

I also have a plea for package maintainers: Make your packages
distribution friendly. Let the distribution build a package as a
non-root user -- supporting and documenting a DESTDIR variable,
"--destdir" config option or supporting "--prefix" in the install phase
is all fine. I'm tired of finding custom install.rb scripts, though,
that don't support it, and having to patch the packages before I commit
them.

Also, one thing to consider: Let the package install into
rubylibdir, not just sitelibdir. Many distributions consider it good
form to put distro-supplied packages in a "System" directory -- for
perl, this is the vendor_perl branch; in ruby, this is the rubylibdir.
That leaves the sitelibdir open for site-local modifications.

Making packaging easy isn't just a nice idea, either: it gains you wider
distribution, wider exposure, and more people giving constructive
criticism. It may be as unpleasant as documentation, but that doesn't
mean it doesn't need to be done.

Ari

 

[Charles Comstock]

I've just created packages (including .spec files to be used as
templates in other distros) of rake and ruby-dbi for the PLD GNU/Linux
distribution. They should be at the builders reasonably quickly, and
available for general consumption after that.

I also have a plea for package maintainers: Make your packages
distribution friendly. Let the distribution build a package as a
non-root user -- supporting and documenting a DESTDIR variable,
"--destdir" config option or supporting "--prefix" in the install phase
is all fine. I'm tired of finding custom install.rb scripts, though,
that don't support it, and having to patch the packages before I commit
them.

Also, one thing to consider: Let the package install into
rubylibdir, not just sitelibdir. Many distributions consider it good
form to put distro-supplied packages in a "System" directory -- for
perl, this is the vendor_perl branch; in ruby, this is the rubylibdir.
That leaves the sitelibdir open for site-local modifications.

Making packaging easy isn't just a nice idea, either: it gains you wider
distribution, wider exposure, and more people giving constructive
criticism. It may be as unpleasant as documentation, but that doesn't
mean it doesn't need to be done.

Ari

Documentation shouldn't be considered unpleasent. If you go to the
trouble of making something to share, it's common curtesy to at least
give basic instructions on it's use. Yes most of us are programmers not
tech writers, but we should take pride in explaining what our creation
is capable of.

Charlie

 

[Aredridel]

Documentation shouldn't be considered unpleasent. If you go to the
trouble of making something to share, it's common curtesy to at least
give basic instructions on it's use. Yes most of us are programmers
not tech writers, but we should take pride in explaining what our
creation is capable of.

Wholeheartedly agreed.

Thankfully, we have some very fine (and unobtrusive) tools with Ruby:
rdoc is a piece of work whose subtlety I'd love to see imitated.

In addition to rather liking test-first coding (which I'm just now
getting into), I like document-first coding. Write tests (expect them
to fail), write docs (expect them to be more complete than the code),
then write code that fulfils the tests and matches the docs.

I think that's why the Exim MTA is as successful as it is. In addition
to being wildly flexible, it's well-documented, because it's spec'd in
advance. It should be a standard practice, and is one I'm trying to
develop in myself.

Ari

 

[Mauricio Fernández]

In addition to rather liking test-first coding (which I'm just now
getting into), I like document-first coding. Write tests (expect them
to fail), write docs (expect them to be more complete than the code),
then write code that fulfils the tests and matches the docs.

Time to write RWEB?

--
_ _
| |__ __ _| |_ ___ _ __ ___ __ _ _ __
| '_ \ / _` | __/ __| '_ ` _ \ / _` | '_ \
| |_) | (_| | |_\__ \ | | | | | (_| | | | |
|_.__/ \__,_|\__|___/_| |_| |_|\__,_|_| |_|
Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com

"You, sir, are nothing but a pathetically lame salesdroid!
I fart in your general direction!"
-- Randseed on #Linux

 

[Larry Felton Johnson]

Funny you should mention that. I've been looking over the
CWEB syntax thinking about writing a simple tangle/weave system
in and for ruby as an exercise. I've always been interested in
literate programming, never really done anything with it except
read the docs.

I was thinking about something modelled on cweb as the source files,
xhtml as the weave output, and ruby as the tangle output.

Larry

 

[Charles Comstock]

Funny you should mention that. I've been looking over the
CWEB syntax thinking about writing a simple tangle/weave system
in and for ruby as an exercise. I've always been interested in
literate programming, never really done anything with it except
read the docs.

I was thinking about something modelled on cweb as the source files,
xhtml as the weave output, and ruby as the tangle output.

Larry

Umm isn't RDOC basically RWEB? I mean it's not really fancy as far as
the weave output but I mean it's pretty similar really. It's just the
overall weave output isn't designed to be read in book form. You could
just make a new formatter for RDOC that was more article/bookish.

Charles Comstock

 

[Andrew Johnson]

Funny you should mention that. I've been looking over the
CWEB syntax thinking about writing a simple tangle/weave system
in and for ruby as an exercise. I've always been interested in
literate programming, never really done anything with it except
read the docs.

Just for info: noweb is a language independent LP system that'll work
just fine for Ruby. However, development of noweb seems nonexistent
these days --- Norman started a version 3 reimplementation in Lua in
1999, but it didn't seem to go anywhere. A re-implementation in Ruby
would be nice. See: http://www.eecs.harvard.edu/~nr/noweb/

regards,
andrew

 

[Larry Felton Johnson]

I'll take a closer look at RDOC. If it meets the following
criteria or could be extended to meet those criteria it may be
the path of least resistance:

# 1) The high-level language code and the system
# documentation of the program come from the
# same set of source files.

# 2)The documentation and high-level language
# code are complementary and should address
# the same elements of the algorithms being
# written.

# 3)The literate program should have logical
# subdivisions. Knuth called these modules or
# sections.

# 4) The system should be presented in an order
# based upon logical considerations rather than
# syntactic constraints.

# 5)The documentation should include an examination
# of alternative solutions and should suggest
# future maintenance problems and extensions.

# 6) The documentation should include a description
# of the problem and its solution. This
# should include all aids such as mathematics
# and graphics that enhance communication of
# the problem statement and the understanding
# of its challenge.

# 7)Cross references, indices, and different fonts for
# text, high-level language keywords, variable
# names, and literals should be reasonably
# automatic and obvious in the source and the
# documentation.

The list above is from from Bart Child's article
"Literate Programming, a Practioner's View" which can be found at

http://www.tug.org/TUGboat/Articles/tb13-3/childs.pdf

Larry

 

[Larry Felton Johnson]

I haven't looked at noweb, but it's actually on my reading
list, since my reading list is basically from these two pages
on one of the Literate Programming web sites plus Knuth's
book.

http://www.literateprogramming.com/farticles.html
http://www.literateprogramming.com/fmanuals.html

I haven't gotten far enough along on the list to know
what the capabilities of all the different tools are.
It would be nice if both the tangle and the weave
portions of whatever tool I settled on were retargetable
(in other words in addition to adding languages one
could use whatever markup or formatting language was
to the environment).

I'm not overly ambitious with this idea (that is, it wasn't
my plan to try to foist a whole programming approach along
with its particular tools onto the ruby community before I've
programmed in that language long enough to be able to build
simple conditional statements without looking at a manual).
A round of documentation rewriting at my workplace got me interested
in approaches to documentation, so I was taking a fresh look
at literate programming. At the same time I had begun tinkering with
ruby again and had the thought

"Aha! I'm looking at literate programming plus I'm looking at a
language which is new to me. Why don't I mock up some tools for
literate programming in that language? It'll advance my understanding
of both the language and literate programming".


Larry

 

[Larry Felton Johnson]

Just for info: noweb is a language independent LP system that'll work
just fine for Ruby. However, development of noweb seems nonexistent
these days --- Norman started a version 3 reimplementation in Lua in
1999, but it didn't seem to go anywhere. A re-implementation in Ruby
would be nice. See: http://www.eecs.harvard.edu/~nr/noweb/

regards,
andrew

I read through the following article on noweb this morning

http://tex.loria.fr/litte/ieee.pdf

and the approach definitely looks promising.
The "simplified" part of his approach is one of the things I was interested
in pursuing.

Larry