A good way to do a book?

ruby-talk
1

http://www.sourcebeat.com/index.jsp

It would be great to get a “Ruby Live” book going. I like the idea of
having a book in PDF format that gets updated continually. It would be
an ever evolving book on the goodness of Ruby.

2

“Bob” bobx@linuxmail.org schrieb im Newsbeitrag
news:1001ff04.0402160819.6dae78e7@posting.google.com…

http://www.sourcebeat.com/index.jsp

It would be great to get a “Ruby Live” book going. I like the idea of
having a book in PDF format that gets updated continually. It would be
an ever evolving book on the goodness of Ruby.

… or goddess. :slight_smile:

Pun is fun!

robert
3

Bob wrote:

http://www.sourcebeat.com/index.jsp

It would be great to get a “Ruby Live” book going. I like the idea of
having a book in PDF format that gets updated continually. It would be
an ever evolving book on the goodness of Ruby.

As far as I read on that site, it’s about $30 per book per year. If I
participated in writing an open source book about Ruby, I’d rather do
that for free (as in free beer :wink: [but I would accept being paid for it
… :smiley: ]. However there’s the pickaxe book already, which is exellent
(both both the English edition right in 2001, and the German edition
when it was ‘on sale’ at the local book store - and I use the e-dition
quite a lot)

Happy Rubying

Stephan

4

Hi!

  • Bob:

http://www.sourcebeat.com/index.jsp

It would be great to get a “Ruby Live” book going. I like the idea
of having a book in PDF format that gets updated continually. It
would be an ever evolving book on the goodness of Ruby.

I don’t know of an affordable PDF editor. Minimalistic HTML plus CSS?

Josef ‘Jupp’ SCHUGT

···

–
http://oss.erdfunkstelle.de/ruby/ - German comp.lang.ruby-FAQ
http://rubyforge.org/users/jupp/ - Ruby projects at Rubyforge
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Germany 2004: To boldly spy where no GESTAPO / STASI has spied before

5

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

#{title} by #{author}

#{title}

#{author}

#{@date}

EOF end

def to_s
<<-EOF
#{@document}

Generated by Ruby HTML class on #{@date}

EOF end

def h1(text) @document << “

#{text}

\n” end
def h2(text) @document << “

#{text}

\n” end
def h3(text) @document << “

#{text}

\n” end
def h4(text) @document << “

#{text}

\n” end
def h5(text) @document << “
#{text}
\n” end
def h6(text) @document << “
#{text}
\n” end
def p(text) @document << “

\n#{text}\n

\n” end
def pre(text) @document << “
#{text}
\n” end

def ul(list)
@document << “

    \n
  • ”
    @document << list.join("
    • \n
  • ")
    @document << "
    • \n
\n"
end

def ol(list)
@document << “

    \n
  1. ”
    @document << list.join("
    2. \n
  2. ")
    @document << "
    3. \n
\n"
end

def dl(list)
@document << "

\n"
list.each { |entry|
@document << “
#{entry[0]}
\n”
@document << “
#{entry[1]}
\n”
}
@document << "
\n"
end

def table(list)
@document << "

\n"
list.each { |row|
@document << "\n"
row.each { |cell|
if cell.class == String
@document << "\n"
else
@document << “<th align=“left”>”
@document << “#{cell.first}”
@document << "\n"
end
}
@document << “\n”
}
@document << "
#{cell}
\n"
end

def HTML.i(text) “#{text}” end
def HTML.b(text) “#{text}” end
def HTML.tt(text) “#{text}\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

6

Stephan wrote:

Bob wrote:

http://www.sourcebeat.com/index.jsp

It would be great to get a “Ruby Live” book going. I like the idea of
having a book in PDF format that gets updated continually. It would be
an ever evolving book on the goodness of Ruby.

As far as I read on that site, it’s about $30 per book per year. If I
participated in writing an open source book about Ruby, I’d rather do
that for free (as in free beer :wink: [but I would accept being paid for it
… :smiley: ]. However there’s the pickaxe book already, which is exellent
(both both the English edition right in 2001, and the German edition
when it was ‘on sale’ at the local book store - and I use the e-dition
quite a lot)

Happy Rubying

Stephan
They are working out subscriptions. The initial $30 is for a first purchase.

7

That would make good sense to me.

(FWIW, those who have MacOS X already have PDF ‘print’ capabilities
from any application, so PDFs could be created from, say, HTML+CSS)

···

On Feb 16, 2004, at 4:38 PM, Josef ‘Jupp’ SCHUGT wrote:

I don’t know of an affordable PDF editor. Minimalistic HTML plus CSS?

8

Josef ‘Jupp’ SCHUGT wrote:

I don’t know of an affordable PDF editor. Minimalistic HTML plus CSS?

So use TeX, who can really afford, or want to buy, stuff like InDesign
(bar piracy) anyways?

···

–
That’s some catch, that Catch-22.
Oh, it’s the best there is.

9

I don’t know of an affordable PDF editor. Minimalistic HTML plus CSS?

OpenOffice will export to PDF.

Also, there was an attempt at a community-driven Ruby book at
http://www.rubydoc.org/book.

Good writing is time-consuming, and hard to do well. A Ruby book,
unless its something along the lines of a cookbook or “Ruby Hacks,”
should have a consistent author’s voice and theme. If it purports to
teach people Ruby, then what is offered in the early chapters should lay
the foundation for more advanced and interesting topics later on.

I’ve worked on a few Wrox books where 8-to-12 writers were all pitching
in on different topics. While the books were constructed to have a
central theme, they often came off as a collection of magazine articles.

This can be useful, but I don’t think we need to think in terms of a
book in order to assemble a collection of tutorials.

James

10

“Josef ‘Jupp’ SCHUGT” jupp@gmx.de writes:

Hi!

  • Bob:

http://www.sourcebeat.com/index.jsp

It would be great to get a “Ruby Live” book going. I like the idea
of having a book in PDF format that gets updated continually. It
would be an ever evolving book on the goodness of Ruby.

I don’t know of an affordable PDF editor. Minimalistic HTML plus CSS?

AFAIK, OpenOffice can export PDF.

kind regards
frank

···

–
Frank Schmitt
quattro research GmbH
e-mail: schmitt NO at SPAM quattro-research !@! dot com

11

OpenOffice.

-austin

···

On Tue, 17 Feb 2004 08:38:41 +0900, Josef ‘Jupp’ SCHUGT wrote:

I don’t know of an affordable PDF editor. Minimalistic HTML plus CSS?

–
austin ziegler * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2004.02.19
* 11.52.41

12

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

#{title} by #{author}

#{title}

#{author}

#{@date}

EOF end

def to_s
<<-EOF
#{@document}

Generated by Ruby HTML class on #{@date}

EOF end

def h1(text) @document << “

#{text}

\n” end
def h2(text) @document << “

#{text}

\n” end
def h3(text) @document << “

#{text}

\n” end
def h4(text) @document << “

#{text}

\n” end
def h5(text) @document << “
#{text}
\n” end
def h6(text) @document << “
#{text}
\n” end
def p(text) @document << “

\n#{text}\n

\n” end
def pre(text) @document << “
#{text}
\n” end

def ul(list)
@document << “

    \n
  • ”
    @document << list.join("
    • \n
  • ")
    @document << "
    • \n
\n"
end

def ol(list)
@document << “

    \n
  1. ”
    @document << list.join("
    2. \n
  2. ")
    @document << "
    3. \n
\n"
end

def dl(list)
@document << "

\n"
list.each { |entry|
@document << “
#{entry[0]}
\n”
@document << “
#{entry[1]}
\n”
}
@document << "
\n"
end

def table(list)
@document << "

\n"
list.each { |row|
@document << "\n"
row.each { |cell|
if cell.class == String
@document << "\n"
else
@document << “<th align=“left”>”
@document << “#{cell.first}”
@document << "\n"
end
}
@document << “\n”
}
@document << "
#{cell}
\n"
end

def HTML.i(text) “#{text}” end
def HTML.b(text) “#{text}” end
def HTML.tt(text) “#{text}\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

13

So does KDE directly from the print dialog.Or any un*x box with the
ps2pdf command.

Guillaume.

···

On Mon, 2004-02-16 at 19:00, Gavin Kistner wrote:

On Feb 16, 2004, at 4:38 PM, Josef ‘Jupp’ SCHUGT wrote:

I don’t know of an affordable PDF editor. Minimalistic HTML plus CSS?

That would make good sense to me.

(FWIW, those who have MacOS X already have PDF ‘print’ capabilities
from any application, so PDFs could be created from, say, HTML+CSS)

14

Shu-yu Guo wrote:

Josef ‘Jupp’ SCHUGT wrote:

I don’t know of an affordable PDF editor. Minimalistic HTML plus CSS?

So use TeX, who can really afford, or want to buy, stuff like InDesign
(bar piracy) anyways?

Or, if you prefer to work at a slightly higher level, LaTeX.

Harry O.

15

I don’t know of an affordable PDF editor. Minimalistic HTML plus CSS?

OpenOffice will export to PDF.

Also, there was an attempt at a community-driven Ruby book at
http://www.rubydoc.org/book.

Good writing is time-consuming, and hard to do well. A Ruby book,
unless its something along the lines of a cookbook or “Ruby Hacks,”
should have a consistent author’s voice and theme. If it purports to
teach people Ruby, then what is offered in the early chapters should lay
the foundation for more advanced and interesting topics later on.

I’ve worked on a few Wrox books where 8-to-12 writers were all pitching
in on different topics. While the books were constructed to have a
central theme, they often came off as a collection of magazine articles.

This can be useful, but I don’t think we need to think in terms of a
book in order to assemble a collection of tutorials.

IMHO the most sensible technology to use for a new collaborative Ruby book
would be WikiMedia. See http://www.wikibooks.org.

However, http://www.rubydoc.org/book/ is an existing collaborative Ruby
book. Why start another when you can help that?

These things just don’t tend to happen, for the reasons James mentioned:
difficult and time consuming.

Gavin

16

docbook is an option. Is coughxmlcough but goes to pdf, html, or
print equally easily

-Brian

···

On Feb 19, 2004, at 11:53 AM, Austin Ziegler wrote:

On Tue, 17 Feb 2004 08:38:41 +0900, Josef ‘Jupp’ SCHUGT wrote:

I don’t know of an affordable PDF editor. Minimalistic HTML plus CSS?

OpenOffice.

-austin

austin ziegler * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2004.02.19
* 11.52.41

17

Hi!

  • Zach Dennis:

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?

Maybe you misunderstood something:

a) The example document is part of the message I sent and in English.

b) The class that does the HTML representation does not generate a
table of contents because that is a bit more involved.

c) The reference to the Ruby source of the German FAQ[1] is present
because it implements more - like a table of contents and a LaTeX
representation. That would have gone beyond the scope of a message
that is nothing but a suggestion of how something could be done.

d) I would have suggested the text even if it were written in Klingon
because the language uses does not have anything to do with the
layout. At least if the language fits into the usual typographic
scheme. The text could be in Turkish - it simply wouldn’t matter.

[1] http://oss.erdfunkstelle.de/ruby/FAQ.rb

Josef ‘Jupp’ SCHUGT

···

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

18

Hi!

  • Harry Ohlsen:

Shu-yu Guo wrote:

Josef ‘Jupp’ SCHUGT wrote:

I don’t know of an affordable PDF editor. Minimalistic HTML plus
CSS?

So use TeX, who can really afford, or want to buy, stuff like
InDesign (bar piracy) anyways?

Or, if you prefer to work at a slightly higher level, LaTeX.

I don’t think that the actual format is very important. What is
needed?

Headlines of several levels
Paragraphs
italics, bold, typewriter
Preformatted text
Itemization
Enumeration
Description lists
Tables
Graphics

This can be done in HTML 3.2+, LaTeX, RTF and even in Ruby.

Yes, Ruby. The german edition of the comp.lang.ruby FAQ is a Ruby
script that generates HTML and LaTeX.

http://oss.erdfunkstelle.de/ruby/FAQ.rb

It may sound a bit strange but it was a proof of concept and it
works. All other representations are generated from the Ruby source.

Josef ‘Jupp’ SCHUGT

···

–
http://oss.erdfunkstelle.de/ruby/ - German comp.lang.ruby-FAQ
http://rubyforge.org/users/jupp/ - Ruby projects at Rubyforge
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Germany 2004: To boldly spy where no GESTAPO / STASI has spied before