Re: FOSDEM GTK+ brochure

[Sébastien Wilmet <swilmet gnome org>]

On Thu, Jan 08, 2015 at 05:31:39PM +0100, Olav Vitters wrote:
> On Thu, Jan 08, 2015 at 05:12:28PM +0100, Olav Vitters wrote:
> > GTK+ has been created in 1996 for the GIMP — the
> > GNU Image Manipulation Program — but has quickly
>
> Maybe:
> "- a photo retouching, image composition and image authoring program -"

The GIMP acronym is still relevant IMO.

> > become a general-purpose library used by a large
>
> Maybe something "and quickly evolved into"

Changed as:
"but quickly evolved into a general-purpose library"

> > • Cairo, a library for 2D graphics with support for
> >   multiple output devices (including the X Window
> >   System, Win32) while producing a consistent output
>
> Wayland, OS X?

I've added Quartz, as mentioned here:
http://cairographics.org/

But Wayland is mentioned nowhere. "git grep -i wayland" in the cairo
repo gives no results. Wayland is mentioned only once in the git log. So
I don't know how Cairo works on Wayland.

> I'm not sure, but with bullet points shouldn't you do:
> * bla;
> * bar;
> * foo.
>
> ?

Yes, I think it's better. But it looks a bit weird (maybe because I'm
not used to this style).

At the end of this page:
https://help.gnome.org/misc/release-notes/3.14/developers.html.en
dots are used for each item, with an uppercase letter at the beginning.

> > GLib contains also lots of utilities:
>
> Remove "also" IMO, or before "contains"
>
> Wondering about "lots" or "loads"

Changed as:
"GLib also contains loads of utilities:"

> > GObject – an Object System
> >
> > Most modern programming languages come with their
> > own native object systems and additional fundamental
> > algorithmic language constructs. Just as GLib
> > serves as an implementation of such fundamental types
> > and algorithms (linked lists, hash tables and so forth),
> > GObject provides the required implementations of a
>
> s/the required/an/ ?
> and s/implementations/implementation/ ?

Fixed.

> > GIO is striving to provide a modern, easy-to-use Virtual
>
> s/is striving to provide/provides/
>
> As we should not be doubting what we provide.

I prefer "is striving to provide", it's more humble. Making GIO "modern,
easy-to-use" is probably not easy, so "striving" means lots of effort
has been invested. At least it's how I see it.

The sentence comes from the GIO introduction:
https://developer.gnome.org/gio/stable/ch01.html

> > File System (VFS) API that sits at the right level
> > in the library stack, as well as other generally useful
> > APIs for desktop applications (such as networking and
> > D-Bus support). The goal is to provide an API that
>
> Above sentence seems a bit too long.
>
> s/The goal/It was created to/ IMO
>
> > is so good that developers prefer it over raw POSIX
> > calls. Among other things that means using GObject.
> > It also means not cloning the POSIX API, but providing
>
> The DBus and VFS seems like it should be split out a bit IMO.

Modified as:
"GIO is striving to provide a modern, easy-to-use Virtual File System
(VFS) API that sits at the right level in the library stack. GIO also
contains other generally useful APIs for desktop applications (such as
networking and D-Bus support). It was created to provide an API that is
so good that developers prefer it over raw POSIX calls."

> > The GTK+ Widget Toolkit
> >
> > GTK+ provides a flexible theming system with a CSSlike
> > syntax. The default theme is Adwaita, used by the
> > GNOME desktop, but other themes can be created
> > so an application can be well integrated with other
> > desktop environments or mobile devices.
>
> This gives the impression that e.g. GTK+ by default looks out of place
> on anything other than GNOME. E.g. bad in KDE, Mac OS X and Windows. I
> don't think that is the case though.

Changed as:
"Among other things, GTK+ provides a flexible theming system with a
CSS-like syntax, as well as an interactive inspector."

> > About Versions
>
> s/About Versions/Release schedule and versioning scheme/

Fixed.

> > There are new GLib, GObject, GIO, GTK+ and
> > GNOME stable releases every six months, around
>
> Maybe: "Every six months there are new..." ?

Fixed.

> > March and September. A version number has the form
> > X.Y.Z, where “Y” is even for stable versions and is
> > odd for unstable versions. A new minor stable version
> > (e.g. 3.14.0 ! 3.14.1) doesn’t add new features,
> > only translation updates, bug fixes and performance
> > improvements. For a library, a new major version number
> > (“X” in X.Y.Z) generally means there has been an
> > API break, but fortunately previous major versions are
>
> s/, but fortunately previous/. Previous/
> or
> s/, but fortunately previous/. To address this, previous/

I prefer the second one, so there is a link between the two sentences.

> > More information: http://www.gtk.org/
>
> This gives the impression it is part of the versioning scheme section.
> Could it be made to appear different?

I've added a section.

Another way is to add an horizontal line, but I prefer the section.

Thanks for the review! I've updated the PDF.

Sébastien