From: Eric Hodel <drbrain@...7.net>
Date: 2008-07-24T03:39:08+09:00
Subject: Re: [ANN] rdoc 2.1.0 Released

On Jul 23, 2008, at 02:04 AM, Marcin Raczkowski wrote:

> I'm glad, i just started hacking, and don't know if i did good job,  
> and what coding convention to follow ;)

I made a change, is this suitable?

Index: lib/rdoc/generator/html.rb
===================================================================
--- lib/rdoc/generator/html.rb	(revision 114)
+++ lib/rdoc/generator/html.rb	(working copy)
@@ -256,8 +256,16 @@ class RDoc::Generator::HTML

        if main.nil? then
          main = @classes.find do |klass|
-          main_page == klass.context.full_name
+          @main_page == klass.context.full_name
          end
+
+        main = @files.find do |file|
+          file.name =~ /^README/
+        end
+      end
+
+      unless main then
+        raise RDoc::Error, 'main page not found, please specify with  
--main'
        end
      else
        main = RDoc::TemplatePage.new @template::INDEX

I have README, not README.txt, and some people have README.rdoc, so  
this should work better for most people.

> anyway I'm going to work some time on RDoc becouse i want it to  
> generate some other formats then what already is implemented, i have  
> question could you put together quick hacking guide?

What formats?

> What lies where, and what's the basic flow of data/calls?
>
> I promise patches and specs in return ^^

I will try to improve the RDoc documentation of various locations, but  
here's a quick guide:

RDoc is composed of the following parts: parsing, intermediate  
documentation representation, generators, markup and ri.

If you're writing a new output format, you're most interested in the  
intermediate documentation representation and generators, but you may  
want to build your own generator if you're not doing something roughly  
similar to HTML (ri has a completely separate thing to spit out its  
yaml files).

The intermediate representation is split amongst various classes in  
lib/rdoc/code_objects.rb.  How these fit together should be  
straightforward.

The heart of the generators is RDoc::Generator::build_indicies, which  
turns the various files, classes and modules found into a second  
intermediate representation for HTML, etc output.  (I'm not sure if  
this is strictly necessary, I am highly inclined to rip it out and  
simplify the generators, but that's a big, big job.)

I don't remember how ri does its thing, but part of it is in  
RDoc::RI::Writer.