Re: inline docs

[Owen Taylor <otaylor redhat com>]

Havoc Pennington <hp redhat com> writes:

> "Matthias Clasen" <matthiasc poet de> writes: 
> > 1) Ok to commit this ?
> > 2) Are you interested in more changes like this ?
> 
> I think these changes look good.
> 
> > 3) Should I also move things from templates to doc comments in the c files ?
> > (I think the consensus is to
> >     move away from templates and go with inline docs.)
> 
> Owen has requested that for each file, all docs for that file are
> either in the template or inline. (Though this isn't totally true at
> the moment.) But for everything except GObject, inline is preferred
> and we would like to move that way.
> 
> > 4) Another thing where consistency could be improved is quoting in
> > externalized messages.
> >     I've seen `foo', 'foo' and "foo" (there may be more variants). What is
> > the preferred quoting in
> >     English text ?
> 
> I think "foo" is correct. The single quotes are inspired by /bin/sh,
> not written English. ;-)

It should be either 'foo' or "foo". Preference between these two
probably depends on what side of the Atlantic you are on; 

Despite being on the " side of the Atlantic, I prefer the 'foo' form a
bit because it has less visual clutter and probably because of
Perl/Shell experience.

`foo' is incorrect, and will display badly with current fonts on X.

Now that we have our messages in UTF-8, we in theory could use:
LEFT DOUBLE QUOTATION MARK (=U+201C) foo RIGHT DOUBLE QUOTATION MARK (=U+201D)
LEFT SINGLE QUOTATION MARK (=U+2018) foo RIGHT SINGLE QUOTATION MARK (=U+2019)

But that probably won't display right for a lot of people...

Regards,
                                        Owen