headers
Eric Hodel | 17 Jul 2006 20:42
Favicon
Gravatar

1.8 vs 1.9 documentation

Currently the HEAD and ruby_1_8 branches have the following  
differences in their lib/.document files:

$ diff -u ruby_HEAD/lib/.document ruby_18/lib/.document
--- ruby_HEAD/lib/.document     2006-07-14 14:22:22.000000000 -0700
+++ ruby_18/lib/.document       2006-07-17 11:38:52.000000000 -0700
 <at>  <at>  -24,7 +24,6  <at>  <at> 
logger.rb
matrix.rb
monitor.rb
-net
observer.rb
optparse.rb
pathname.rb
 <at>  <at>  -33,7 +32,6  <at>  <at> 
pstore.rb
rational.rb
rinda
-resolv.rb
set.rb
shellwords.rb
singleton.rb

It would be great if somebody could verify that it is OK to turn on  
resolv.rb and net, or merge the doc changes back into 1.8.  I'd help,  
but I don't think I have enough free time lying about right now.

--

-- 
Eric Hodel - drbrain <at> segment7.net - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant
(Continue reading)

Permalink | Reply | 1 comment |
headers
Eric Hodel | 18 Jul 2006 00:48
Favicon
Gravatar

Re: 1.8 vs 1.9 documentation

On Jul 17, 2006, at 11:42 AM, Eric Hodel wrote:

> Currently the HEAD and ruby_1_8 branches have the following  
> differences in their lib/.document files:
>
> [...]
>
> It would be great if somebody could verify that it is OK to turn on  
> resolv.rb and net, or merge the doc changes back into 1.8.  I'd  
> help, but I don't think I have enough free time lying about right now.

Note: I can submit patches if you post them to -core.

--

-- 
Eric Hodel - drbrain <at> segment7.net - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com
Permalink | Reply | 0 comments |
headers
Dave Howell | 24 Jul 2006 23:03
Picon
Picon

New Arrival, and no link to some ruby-doc archives?

Hello apparently pleasantly low-traffic list members. I'm here as a 
preliminary step to hopefully improving the documentation for RDoc, and 
improving RDoc itself, especially in regards to generating improved 
HTML-based on-drive doc trees.

Since I'd been subscribed for a few days and hadn't seen any messages 
go by, I figured I probably ought to read back through the archives a 
little ways before posting.

I was unable to find any mention of the "ruby-doc" mailing list on 
www.ruby-doc.org

Is this deliberate?

I eventually located archives at www.nabble.com.

While writing this message for posting, it occured to me to check at 
ruby-lang.org. "Oops!" I thought to myself. But, oddly, although that 
site does have links for ruby-core and ruby-talk archives, there isn't 
a ruby-doc archive link.
Permalink | Reply | 4 comments |
headers
Dave Howell | 24 Jul 2006 23:46
Picon
Picon

RDoc HTML links?

I was trying to use my RubyAEOSA documentation, and started suspecting 
that there was stuff missing. Sure enough, there's a whole "doc" folder 
with stuff not generated by RDoc. It looks like RDoc-ready files, 
except there's both *.en and *.jp versions for most plus *.en.html and 
*.jp.html. None of those extensions will normally get read by RDoc, and 
there was no .document file.

Nor are there any doc-building commands in the install.rb file.

There IS a highly mysterious "build_html.rb" file in the doc directory. 
It appears to run a command-line tool named "rd2" against the non-html 
files. I don't have an rd2 command.

I did find a web-replica of a man page that said

	rd2 - converter from RD to other mark-up language.

and a different page that had

	Rd2		RDTool, http://www2.pos.to/ tosh/ruby/rdtool/en/index.html

But even when I removed the odd space before "tosh", that link still 
leads to a 404. I did eventually run down

	http://raa.ruby-lang.org/project/rdtool

Which got me this information:

	RDtool is RD formater and utilities. (RD is Ruby's POD)
	If you use Ruby 1.8, you might not need to install Racc and so on.
(Continue reading)

Permalink | Reply | 14 comments |
headers
James Britt | 25 Jul 2006 00:35
Favicon

Re: New Arrival, and no link to some ruby-doc archives?

Dave Howell wrote:
> Hello apparently pleasantly low-traffic list members. I'm here as a 
> preliminary step to hopefully improving the documentation for RDoc, and 
> improving RDoc itself, especially in regards to generating improved 
> HTML-based on-drive doc trees.
> 
> Since I'd been subscribed for a few days and hadn't seen any messages go 
> by, I figured I probably ought to read back through the archives a 
> little ways before posting.
> 
> I was unable to find any mention of the "ruby-doc" mailing list on 
> www.ruby-doc.org

Once upon a time there was an archive, but (as I recall, so please 
correct me, anyone who knows better) it deteriorated, and the maintainer 
  became unreachable.

I did not think all that much about it; the list traffic had become 
fairly mundane, and (for me at least) an archive , while nice, seemed 
extraneous.

However, gmane.org has a habit of Webifiying mailing lists.

http://dir.gmane.org/gmane.comp.lang.ruby.documentation

And they have a searchable archive.

Hope that helps.

James Britt
(Continue reading)

Permalink | Reply | 2 comments |
headers
Eric Hodel | 25 Jul 2006 01:16
Favicon
Gravatar

Re: RDoc HTML links?

On Jul 24, 2006, at 2:46 PM, Dave Howell wrote:

> I was trying to use my RubyAEOSA documentation, and started  
> suspecting that there was stuff missing. Sure enough, there's a  
> whole "doc" folder with stuff not generated by RDoc. It looks like  
> RDoc-ready files, except there's both *.en and *.jp versions for  
> most plus *.en.html and *.jp.html. None of those extensions will  
> normally get read by RDoc, and there was no .document file.
>
> Nor are there any doc-building commands in the install.rb file.
>
> There IS a highly mysterious "build_html.rb" file in the doc  
> directory. It appears to run a command-line tool named "rd2"  
> against the non-html files. I don't have an rd2 command.

...

> What does "RD is Ruby's POD" mean?

POD is Perl Online Documentation or similar.  RD2 predates RDoc.

> Is there any documentation about the markup language itself?

If you can find a copy of rd2 you can find the markup documentation.   
Its got all the standard stuff, you should be able to figure out 75%  
of the constructs from context.

> Is it still actively used, is it being replaced by SimpleMarkup  
> that ships with RDoc, or is something else replacing it?
(Continue reading)

Permalink | Reply | 9 comments |
headers
Eric Hodel | 25 Jul 2006 01:19
Favicon
Gravatar

Re: New Arrival, and no link to some ruby-doc archives?

On Jul 24, 2006, at 2:03 PM, Dave Howell wrote:

> I eventually located archives at www.nabble.com.
>
> While writing this message for posting, it occured to me to check  
> at ruby-lang.org. "Oops!" I thought to myself. But, oddly, although  
> that site does have links for ruby-core and ruby-talk archives,  
> there isn't a ruby-doc archive link.

The list is served through the same server as ruby-talk and ruby- 
core, so they may be able to enable an archive...

--

-- 
Eric Hodel - drbrain <at> segment7.net - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com
Permalink | Reply | 0 comments |
headers
Dave Howell | 25 Jul 2006 01:49
Picon
Picon

Re: New Arrival, and no link to some ruby-doc archives?


On Jul 24, 2006, at 15:35, James Britt wrote:

> I did not think all that much about it; the list traffic had become 
> fairly mundane, and (for me at least) an archive , while nice, seemed 
> extraneous.

Well, I tend to think of the archive as more useful to people who 
*aren't* subscribed, or weren't. :)

But my query wasn't so much "why isn't there an archive," but "Is the 
lack of a link to an archive from the web site intentional?"
Permalink | Reply | 1 comment |
headers
Dave Howell | 25 Jul 2006 03:16
Picon
Picon

The Secret of RDoc HTML links.


On Jul 24, 2006, at 16:16, Eric Hodel wrote:

>> [p.s. There's also the whole issue of SimpleMarkup's link markup, but 
>> that's for a different message...]
>
> RDoc just linkifies http://...
>
> See: http://rdoc.sourceforge.net/doc/files/README.html

Looks like the same readme that comes with RDoc itself. There's nothing 
whatsoever on that page about how to . . . what the heck?

Oh, that's really remarkable.

So, first, if one installs Ruby, RDoc pointedly installs absolutely no 
documentation about itself. Since getting RDoc to generate HTML 
documentation was nigh-impossible without instructions, I eventually 
convinced it that maybe documenting itself would be a good thing. I 
even suggested that it start its little section with the README file. 
Which it did. Because it's kind of important to me that I have 
documentation on my hard drive, linked together, ready to to go without 
the requirement of having a live net connection and putting up with the 
time delays inherent therein.

Except that my local RDoc-processed HTML version of the README 
conveniently stops right after "CREDITS". Thus eliminating all the 
documentation for "USAGE" and "MARKUP". The stuff that, oh, you know, 
explains how the heck markup's supposed to work.
(Continue reading)

Permalink | Reply | 8 comments |
headers
James Britt | 25 Jul 2006 03:51
Favicon

Re: New Arrival, and no link to some ruby-doc archives?

Dave Howell wrote:
> 
> On Jul 24, 2006, at 15:35, James Britt wrote:
> 
>> I did not think all that much about it; the list traffic had become 
>> fairly mundane, and (for me at least) an archive , while nice, seemed 
>> extraneous.
> 
> 
> Well, I tend to think of the archive as more useful to people who 
> *aren't* subscribed, or weren't. :)

True.  I guess after a while it just seems mundane.  Still, it's nice to 
be able to go back and look stuff up.

> 
> But my query wasn't so much "why isn't there an archive," but "Is the 
> lack of a link to an archive from the web site intentional?"

Sort of.   When the site got revamped, I dropped the reference to the 
archive because it was non-existent.    Had I thought a bit more, I 
would have added a link to a working alternative.

I've now added a link to Gmane.

James
Permalink | Reply | 0 comments |

Gmane