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
Aredridel wrote:
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
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
···
On Mon, Feb 23, 2004 at 09:44:50AM +0900, Charles Comstock wrote:
… It may be as unpleasant as documentation, but that doesn’t mean
it doesn’t need to be done.
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.
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
···
On Mon, Feb 23, 2004 at 08:23:46PM +0900, Mauricio Fernndez wrote:
On Mon, Feb 23, 2004 at 01:18:14PM +0900, Aredridel wrote:
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
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
···
On Fri, 27 Feb 2004 12:29:28 +0900, Larry Felton Johnson larryj@gsu.edu wrote:
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.
–
Andrew L. Johnson http://www.siaris.net/
The generation of random numbers is too
important to be left to chance.
Larry Felton Johnson wrote:
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
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?
–
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
···
On Mon, Feb 23, 2004 at 08:23:46PM +0900, Mauricio Fernndez wrote:
On Mon, Feb 23, 2004 at 01:18:14PM +0900, Aredridel wrote:
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
Larry
···
On Fri, Feb 27, 2004 at 05:05:32PM +0900, Charles Comstock wrote:
Larry Felton Johnson wrote:
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
On Mon, Feb 23, 2004 at 08:23:46PM +0900, Mauricio Fernndez wrote:
On Mon, Feb 23, 2004 at 01:18:14PM +0900, Aredridel wrote:
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?
–
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
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
···
On Fri, Feb 27, 2004 at 04:59:57PM +0900, Andrew Johnson wrote:
On Fri, 27 Feb 2004 12:29:28 +0900, Larry Felton Johnson larryj@gsu.edu wrote:
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
–
Andrew L. Johnson http://www.siaris.net/
The generation of random numbers is too
important to be left to chance.
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
···
On Fri, Feb 27, 2004 at 04:59:57PM +0900, Andrew Johnson wrote:
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