Examples Refactoring
Felipe Doria
I'm Felipe Doria and currently a student of Greg Brown's RMU (Ruby Mendicant University). Each student is required to propose an individual project to accomplish during the course and I chose (with some help from Greg) to refactor Prawn examples.
Two of my ideas to improve the current set of examples are to reduce the number of reference pdf files to one file per example topic (text, bounding boxes, graphics, and so on), and to have self-documenting examples so that the generated pdfs revealed the code used to generate them.
My first very rough attempt on self-documenting examples can be found here. The generated document with code borrowed directly from the rounded polygons example can be seen here (I only committed this to be able to show it easily, I promise I won't do this in the future =)
I will appreciate if you guys help me with suggestions and overall Prawn knowledge cause if you help me code before the class ends Greg might find I'm cheating.
--Felipe Doria
Brad Ediger
> Let me introduce myself first.
>
> I'm Felipe Doria and currently a student of Greg Brown's RMU (Ruby Mendicant
> University). Each student is required to propose an individual project to
> accomplish during the course and I chose (with some help from Greg) to
> refactor Prawn examples.
Hi Felipe,
It's good to hear you are working on the self-documenting examples.
Those will be very helpful to aid in our documentation.
The example you posted looks like a great start. I'd work on cleaning
up the look of the code -- set it in a monospace font and turn spaces
in the input text into non-breaking spaces so line indentation is
properly preserved.
One major issue with your Snippet module: I believe
Proc#source_location is 1.9-only. Since we support Ruby 1.8.7 as well,
you'll have to find some other way to extract the source text.
Thanks and keep up the good work!
Brad
Felipe Doria
The example you posted looks like a great start. I'd work on cleaning
up the look of the code -- set it in a monospace font and turn spaces
in the input text into non-breaking spaces so line indentation is
properly preserved.
Done. I still want to improve here with syntax highlighting and a nice box.
One major issue with your Snippet module: I believe
Proc#source_location is 1.9-only. Since we support Ruby 1.8.7 as well,
you'll have to find some other way to extract the source text.
Probably there is some better way to get the original code back from a Proc other than reading the file and relying on indentation. For the time being we can get the source_location info from Proc#to_s.
Thanks for the comments Brad. Please keep them coming.
-- Felipe Doria
Felipe Doria
Single examples can be ran on their own, and each examples folder has a file that groups all the examples of that folder. The extraction of comments and code from the single examples is still rather weak using regular expressions.
On a recent 1-1 talk with Greg he told me to ask the Prawn devs a couple of points:
1) What will I need to do before merging it upstream?
2) Should I use some well defined comments to ease the code parsing? like:
# BEGIN_EXAMPLE
do_stuff
# END_EXAMPLE
3) Any other input or comment you might have about it. (This project has almost been accepted on RMU so any help will be welcome from now on and won't be considered cheating =D)
-- Felipe Doria
Brad Ediger
> You will find the code quite updated here:
> http://github.com/aguids/prawn/tree/examples/new_examples/
>
> Single examples can be ran on their own, and each examples folder has a file
> that groups all the examples of that folder. The extraction of comments and
> code from the single examples is still rather weak using regular
> expressions.
This stuff looks great. I really like the direction this is going.
One note on Ruby 1.9.2 compatibility: The current directory (.) has
been removed from $LOAD_PATH. So requiring a file relative to the
current directory won't work. This can bite you in weird ways -- one
of which is that the previous require statements:
require File.join(File.dirname(__FILE__), '..', 'example_helper.rb'))
should be changed to use File.expand_path:
require File.expand_path(File.join(File.dirname(__FILE__),
'..', 'example_helper.rb'))
in order to be able to run the examples via a relative path (ruby
new_examples/graphics/hexagon.rb).
Similarly, try running your examples from outside of that directory --
for example, in Prawn's root directory:
ruby new_examples/graphics/graphics.rb
and fix any LoadErrors that pop there.
As for the text introducing the examples: It would be nice if you
could flow the text naturally instead of forcing linebreaks where they
appear in the source file. For example, in origin.rb, we probably
don't need a linebreak before "page".
> 2) Should I use some well defined comments to ease the code parsing? like:
>
> # BEGIN_EXAMPLE
> do_stuff
> # END_EXAMPLE
I think that this would probably be a good thing to do. I would prefer
if we could find a way around it, but I can't immediately think of a
way to avoid it if we're trying to pull the exact source text.
Eventually I can see something like this becoming Prawn's reference
manual. You could add in higher-level functions to create a chapter
for each directory (graphics being one). I'm sure you have thought of
these ideas already... I think this is off to a great start and I'm
excited to see where this can go.
Brad
Felipe Doria
Please reply with your feedback. Any help is welcome be it in regard to the code or to the document formatting.
Eventually I can see something like this becoming Prawn's reference
manual. You could add in higher-level functions to create a chapter
for each directory (graphics being one). I'm sure you have thought of
these ideas already... I think this is off to a great start and I'm
excited to see where this can go.
I'll start working on this direction. Is "Prawn by example" a good name?
-- Felipe Doria
Tom Dyer
--
Tom Dyer
Gregory Brown
> I updated the inner workings of the example generator and finished the
> Graphics examples (file is attached).
Thank you so much Felipe. This looks excellent.
You've really set a high bar for what sort of great things can be
started through RMU projects.
-greg
Brad Ediger
> I updated the inner workings of the example generator and finished the
> Graphics examples (file is attached).
>
> Please reply with your feedback. Any help is welcome be it in regard to the
> code or to the document formatting.
This is fantastic! As Greg said, you have truly set the bar high for
RMU projects, as well as for Prawn contributions. These examples are
incredibly clear and self-explanatory; excellent work.
I'll read over your code and post comments I may have, but I just
wanted to say that I'm very impressed with the result here.
-be
Felipe Doria
I'm starting to lay the structure for the reference manual and would like some help on two points:
1. The current structure of running the example code inside the reference document pages might not work for some examples like those that depend on Prawn::Document.generate.
What should be done? Leave these examples off the manual? Show the code but don't execute it?
2. The first examples on the manual will be those about creating and generating Prawn::Document. After that what should be the order for examples or example packages?
--fd
Brad Ediger
> Guys,
>
> I'm starting to lay the structure for the reference manual and would like
> some help on two points:
>
> 1. The current structure of running the example code inside the reference
> document pages might not work for some examples like those that depend on
> Prawn::Document.generate.
> What should be done? Leave these examples off the manual? Show the code but
> don't execute it?
I think it's fine if those examples aren't strictly self-executing.
But it would be good to have some information in the manual about how
Prawn::Document.generate behaves.
> 2. The first examples on the manual will be those about creating and
> generating Prawn::Document. After that what should be the order for examples
> or example packages?
Start with the simple stuff: basic graphics and text. Then you could
move on to page layout, more complex text formatting (like inline
formatting), tables, outlines, document security, and everything else.
-be
Felipe Doria
It contains some explanation pages and four chapters: Basic Concepts, Graphics, Bounding Box and Text. I found that those are the chapters with the most basic functionality for beginners so they should come first.
If you think any important example or functionality regarding these first four chapters is missing or not covered please reply (Image will have its own chapter).
As usual please reply with your reviews.
I'll procede with the work on the other chapters.
--fd
Tim Benest
Tom Dyer
"Reading the examples
The title of each example is the relative path from the Prawn source
examples/ folder."
I can't see the any of the examples in the examples dir? For example,
basic_concepts/creation.rb ?
thanks
--
Tom Dyer
Tom Dyer
the examples branch, got it.
--
Tom Dyer
Felipe Doria
Ok, needed to clone https://github.com/aguids/prawn.git and switch to
the examples branch, got it.