From: Zach Dennis <zdennis@...>
Date: 2004-02-20T11:58:45+09:00
Subject: Re: Writing documents in Ruby (Was: A good way to do a book?)

What about those who can't read german? Should we send your site to google
to translate? Do you need someone to make an English version of your example
document?

Zach

-----Original Message-----
From: Josef 'Jupp' SCHUGT [mailto:jupp@gmx.de]
Sent: Thursday, February 19, 2004 3:57 PM
To: ruby-talk ML
Subject: Writing documents in Ruby (Was: A good way to do a book?)


Hi!

I think it is a good idea to illustrate how Ruby can be used as a
markup language. I therefore wrote an example document and a class
that generates HTML out of it. It is a quick hack but should give an
idea of how a more complex solution (including a couple of output
formats) could look like. For more take a look at the source of the
German comp.lang.ruby FAQ at http://oss.erdfunkstelle.de/ruby/

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Document in Ruby

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#!/usr/bin/env ruby

require "layout"

Fmt = HTML

d = Fmt.new("Documentation of Ruby in Ruby", "Josef 'Jupp' Schugt")
d.h1("Isn't that an absurd idea?")
d.p(
"At first sight it may seem absurd to use a " +
Fmt.i("programming") +
" language to write documents but it makes perfect sense. It requires
surprisingly little effort to write documentations in Ruby."
)
d.p(
"That simplicity results from Ruby's " + Fmt.i("object-oriented") +
" features."
)
d.p("Some of the advantages of using Ruby:")
d.ol([
  "People who document Ruby can be assumed to be familiar with Ruby's
  syntax.",
  "The formatting capabilities can easily be restricted or expanded
  according to the needs.",
  "It is very simple to generated any output format you like by
  simply instantiating the appropriate class.",
  "Separation of structure and layout is very strict.",
  "Output generation is incredibly fast.",
])
d.h1('What is needed?')
d.p(
"One needs very few means to typeset a book. As a rule of thumb one
can say that the typographic quality of a book " +
Fmt.i("decreases") + " with an " + Fmt.i("increasing") +
" number of typographic means used (unless you " + Fmt.b("really") +
" know what you are doing)."
)
d.p(
"If you think you need more than what is mentioned in the following
list you should consider reading a good book on typography."
)
d.ul([
"Headlines of several levels",
"Paragraphs",
"italics, bold, and typewriter font",
"Preformatted text",
"Itemization",
"Enumeration",
"Description lists",
"Tables",
"Graphics",
])
d.h1("Stuff not used above")
d.p("The stuff that hasn't been used above is:")
d.ul([
"Typewriter font",
"Preformatted text",
"Description lists",
"Tables",
"Graphics",
])
d.p("Let's demonstrate them now.")
d.h2("Preformatted text and Typewriter font")
d.p(
"The code given below extends the classes " + Fmt.tt("TrueClass") +
" and " + Fmt.tt("FalseClass") +
" so that they can be converted to an integer."
)
d.pre(
"
class TrueClass
  def to_i
    1
  end
end

class FalseClass
  def to_i
    0
  end
end
")
d.h2("Description List")
d.p(
"The description list below has some of the Ruby-related acronyms"
)
d.dl([
[ "DRY",                    "Don't repeat yourself"       ],
[ "IANYM",                  "I am not Yukihiro Matsumoto" ],
[ "POLS",                   "Principle of least surprise" ],
[ "YAGNI / YANGI / YANGNI", "You ain't gonna need it"     ],
[ "YWFWA",                  "Yes we freakin' well are"    ],
])
d.h2("Table")
d.p(
"The table shows the same as the description list above"
)
d.table([
[ [ "Acronym", "th" ],            ["Meaning", "th" ]            ],
[ [ "DRY", "th" ],                "Don't repeat yourself"       ],
[ [ "IANYM", "th" ],              "I am not Yukihiro Matsumoto" ],
[ [ "POLS", "th" ],               "Principle of least surprise" ],
[ [ "YAGNI/YANGI/YANGNI", "th" ], "You ain't gonna need it"     ],
[ [ "YWFWA", "th" ],              "Yes we freakin' well are"    ],
])
d.h2("Image")
d.p(
"Now it is time for the last element: A picture"
)
d.p(Fmt.img("./rubypower.gif"))
d.h1("Conclusion")
d.p(
"I hope to have shown that it is really easy to write documentations
in Ruby."
)
puts d

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Layout class for HTML

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#!/usr/bin/env ruby

class HTML
  def initialize(title, author)
    @date = Time.now.strftime("%Y-%m-%d, %H:%M:%S %Z")
    @document = <<-EOF
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>#{title} by #{author}</title>
<meta name="generator" content="Ruby HTML class"></meta>
</head>
<body>
<hr>
<h1>#{title}</h1>
<h2>#{author}</h2>
<h3>#{@date}</h3>
<hr>
    EOF
  end

  def to_s
    <<-EOF
#{@document}
<hr>
<p>
Generated by Ruby HTML class on #{@date}
</p>
</body>
</html>
    EOF
  end

  def h1(text)  @document << "<h1>#{text}</h1>\n"   end
  def h2(text)  @document << "<h2>#{text}</h2>\n"   end
  def h3(text)  @document << "<h3>#{text}</h3>\n"   end
  def h4(text)  @document << "<h4>#{text}</h4>\n"   end
  def h5(text)  @document << "<h5>#{text}</h5>\n"   end
  def h6(text)  @document << "<h6>#{text}</h6>\n"   end
  def p(text)   @document << "<p>\n#{text}\n</p>\n" end
  def pre(text) @document << "<pre>#{text}</pre>\n" end

  def ul(list)
    @document << "<ul>\n<li>"
    @document << list.join("</li>\n<li>")
    @document << "</li>\n</ul>\n"
  end

  def ol(list)
    @document << "<ol>\n<li>"
    @document <<  list.join("</li>\n<li>")
    @document << "</li>\n</ol>\n"
  end

  def dl(list)
    @document << "<dl>\n"
    list.each { |entry|
      @document << "<dt><b>#{entry[0]}</b></dt>\n"
      @document << "<dd>#{entry[1]}</dd>\n"
    }
    @document << "</dl>\n"
  end

  def table(list)
    @document << "<table border>\n"
    list.each { |row|
      @document << "<tr>\n"
      row.each { |cell|
        if cell.class == String
          @document << "<td>#{cell}</td>\n"
        else
          @document << "<th align=\"left\">"
          @document << "<b>#{cell.first}</b>"
          @document << "</th>\n"
        end
      }
      @document << "</tr>\n"
    }
    @document << "</table>\n"
  end

  def HTML.i(text)  "<i>#{text}</i>"                      end
  def HTML.b(text)  "<b>#{text}</b>"                      end
  def HTML.tt(text) "<code>#{text}</code>\n"              end
  def HTML.img(url) "<img src=\"#{url}\" alt=\"#{url}\">" end

end

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

That's it for now.

Josef 'Jupp' SCHUGT
--
http://oss.erdfunkstelle.de/ruby/    -     German comp.lang.ruby FAQ
http://rubyforge.org/users/jupp/     -     Ruby projects at Rubyforge


---
Incoming mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.576 / Virus Database: 365 - Release Date: 1/30/2004

---
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.576 / Virus Database: 365 - Release Date: 1/30/2004