I know the documentation may change with every new release, and I also know that to learn the language nothing better than following doc and doing practical example at the same time...

But, it will be great to be able to have the documentation as a PDF file (or similar) to print it and read it nicely lying in bed

I still find very difficult reading a lot of pages on screen...

Thanks.

I agree that would be nice.

I would expect there are tools out there that could suck up the html and generate a PDF, but I haven't investigated.

What I'd really like long term, is a Fantom gfx API which renders to PDF, then we could put a PDF backend on the fandoc compiler (all the docs are sourced as fandoc and compiled into HTML).

Fandoc actually shares a lot of functionality with my PaperClips library, it's interesting that the architectural style you've hinted at (swappable graphics rendering backend e.g. SWT printer, image, PDF, HTML) is exactly what I've been aiming for with my own library. My project is in Java but we may be able to trade notes here.

A couple things come to mind immediately:

• The gfx::Graphics, gfx::Point, gfx::Border, gfs::Font, gfx::Insets, gfx::Rect, etc all use Int for measuring distance in pixels. Code written against this will assume a certain DPI (96dpi or 120dpi for LCD screens) and will be strongly tied to the environment it was originally intended for. As soon as you translate to a printing environment where the resolutions are typically 600 or 1200DPI (often higher for PDF), then the proportions of your layout go all haywire. In PaperClips we are retargeting all our APIs away from points expressed in floats/ints (expressed as points) to a Size class which represents an arbitrary distance expressed in a unit of measurement, and where the distance can be converted to whatever unit is needed: e.g. double pixels = size.valueIn(Unit.INCH) * dpi;
• GfxEnv being a singleton does not sit well with me. I may want to be rendering to several different graphics environments within one runtime, e.g. native windows, PDFs, image files, and having a singleton means that people will rely on data from that singleton when inappropriate, e.g. if the singleton holds the graphics environment for native windows then code that relies on the singleton may behave strangely when rendering to a different graphics environment e.g. PDF. If there is to be a singleton, it should be located in the toolkit, in this case in the fwt pod.

Excellent observations qualidafial! At our old company we built a graphics API on top of Java2D and implemented a custom widget toolkit from scratch. We struggled with these same decisions, and decided to use doubles for everything. Based upon that experience Andy and I felt that using doubles was the wrong direction, and so decided to use Ints for gfx/fwt. That doesn't necessarily mean that the coordinate space maps to pixels, but it does mean that code has to work in whole numbers. I believe this is the right trade-off now that we've done it both ways. Andy can probably comment more.

The GfxEnv class is actually designed to solve the problem with multiple graphics engines. The key is that given a Color, Image, or Font that we can use the same instance with multiple graphics engines. That is the only way to have a constant such as Color.red which might be used for both SWT and PDF. The graphics device specific stuff is delegated by the Color, Image, Font to the GfxEnv. Right now the way I'm thinking is thag GfxEnv is basically a thread local, so that as long as different graphics engine are operating in different threads, the same immutable Color, Image, and Font instances can be shared. Probably still needs some more work, but I think that design hits the sweet spot where you have easy access to Colors, Images, or Fonts that can be declared as static fields, but the tradeoff is that GfxEnvs have to use different actors (threads).

Ok, I see what GfxEnv is doing now and it is pretty close to what I have planned. The only difference is that I'm using a Size class instead of Int. In Fantom it would look like:

Size width := Size(4, Unit.INCH)
Unit pixels := Unit.px(96)
Float widthPx := width.valueIn(pixels) // 384px

The benefit of such an approach is that your layout code is device- and DPI-agnostic. So even when expressing sizes in pixels, there is enough information to convert that size to any unit of measurement you like, including pixels in some other DPI.

Unit displayPixels := Unit.px(96)
Size displayWidth := Size(384, displayPixels) // 384px == 4"

Unit printerPixels := Unit.px(600)
Float printerPx := displayWidth.valueIn(printerPixels); // 2400px

Anyway, I'll stop hijacking this thread--if I remember anything else I'll start a new one.

What I'd really like long term, is a Fantom gfx API which renders to PDF, then we could put a PDF backend on the fandoc compiler (all the docs are sourced as fandoc and compiled into HTML).

Seaside PDF info page mentions a number of options; probably the most interesting for Fantom is Apache FOP -- a seemingly pretty advanced XSL-based Java app.