Re: GNOME Manual of Style (was: GNOME vs. Gnome)

[Mathieu Lacage <mathieu eazel com>]

Dan Mueth <d-mueth uchicago edu> writes:

> On Tue, 3 Oct 2000, John Kodis wrote:
> 
> [SNIP]
> > Also, when this is decided, it would be very handy if someone could
> > pull together a "Gnome Manual of Style" that authors could refer to
> > when deciding between GNOME and Gnome, Email and e-mail, left mouse
> > button and mouse button one, and all the other weighty decisions we
> > have hashed out on these lists over the last year or so.
> 
> Yes.  This is a very good suggestion.  I have actually had a few people
> suggest this recently.  John Fleck was even generous enough to offer to
> co-author a "GNOME Manual of Style".  We were originally going to put this
> in the GDP Handbook (in fact we put in the sections and then commented
> them out before the first version of the GDP Handbook appeared on the
> web), but I like your idea of making it a stand-alone document.
> 
> Dave, Sasha, and I started putting together what would be one section of
> the GMS - a description of what DocBook tags to use for various UI
> components, depending upon the context they are used in.  This was a long
> time ago, and we didn't quite finish it, but I think I can find it.
> 
> We will need to cover quite a few other topics, probably including:
>  - proper use of various entities such an endash, emdash, hellip, ...
>  - handling trademarks
>  - target audience
>  - how to avoid offending your reader
>  - how to avoid boring your reader
>  - how to make sure your document is "translatable"
>  - screenshot appearances
>  - diagram/illustration appearances
>  - proper markup and capitalization of GNOME UI terms 
>    (eg. Panel vs. panel, Main Menu vs. main menu, ...)
>  - licensing
>  - how to include content which is aimed outside the target audience
>  - commonly used terms with multiple spellings
>    (eg. e-mail vs. email vs. Email...)
>  - GNOME vs Gnome

In case, people are interested, here is the coding style dirk-jan and I try 
to folow:

It is pretty rough but... Never took time to improve it.

------------------------------------------------------------------------------
0) writing stuff
----------------
We will use: "we" when refering to the authors
and "you" when refering to the reader.

Some guidelines:
- use short to-the-point sentences.
decide what you want to say, then write it down. in general, a paragraph
should about one topic
- explain terms when they're used first
- we're not writing a scientific paper, but also not a comic book
therefore, avoid words like 'cool', 'sucks' etc. Also, use technical
terms when appropriate
- make things as simple as possible, but not more simple
- do not make too many assumptions about the reader.


1) docbook stuff
-----------------

Of course, each chapter will be in a <chapter> tag which will be
itself in a <book> tag.	Each paragraph will be in a <para> tag.
Tables will use the <table> tab, lists the <itemizedlist> tag.
When we want to show some simple text clearly, we use <emphasis>.
For links, use <xref linked="my-id">.
use <computeroutput> for command line stuff.
<footnote id="my-id"> should be used also for foot notes (how 
surprising...). Don't forget <footnoteref linkend="my-id"> to 
make ref to the footnote !!

Dirk-Jan noted the use of <simpara> -> what can we use it for ?

Directory paths must be tagged with <filename>.

Additions by Dirk-Jan.
---------------------
Applications: 		<application>Gnumeric</application>
Command:      		<command>sed</command>
Companies:              <corpname>HelixCode</corpname>

Comments (not part of the book, but on the meta-level)
                        <comment author="djcb">Bla!</comment>


To emphasize 'bla', use <emphasis>bla</emphasis> instead of 'BLA'

Citations (references to other books):
                <citation>Bro95</citation>
(take the keys from the books.bib file)



2) IDL code.
------------

For IDL code, we will use the folowing conventions:
	- when presenting in a paragraph an IDL interface, use
	the <classname> tag and fully qualify the interface name.
	eg: <classname>Bonobo::Control</classname>
	- when presenting in a paragraph an IDL method, use the
	<function> tag and do NOT fully qualify the method name
	unless necessary because the context is not self
	explanatory.
	eg: <function>open_stream</function>
	- when presenting a variable name, use the <property> tag.
	- when presenting an IDL interface definition outside of
	text, use the <programlisting> tag. eg:
	<programlisting>
interface Storage : Unknown {
	typedef long OpenMode;
	const OpenMode READ  = 1;
	const OpenMode WRITE = 2;
	const OpenMode DENY_READ = 4;
	const OpenMode DENY_WRITE = 8;

	exception NameExists {};
	exception NotFound {};
	exception NoPermission {};
	// ...
}
	</programlisting>
	The indenting in these areas should be 8 space char tabs
	(actually, real tabs, not 8 spaces but inpractice, due
        to the poor quality of the tools we use, it should be 
        8 spaces.).

3) C code.
----------
(or any other langage. Python will probably be used in the
Automation chapter)

The tags used here will be expanded to respectively:
<function>, <classname>, <property> and <programlisting>
We will write a simple perl script to do this before the
docbook compilation. (sed if our friend)

For C code, use the folowing conventions:
	- for C function names which are given in the body of the
	text, use the <cfunction> tag.
	eg: <cfunction>bonobo_control_new</cfunction>
	- for C types (ie: objects), use the <cclassname> tag.
	eg: <cclassname>BonoboObject</cclassname>
	- when commenting some code and refering to a variable
	name, use: <cproperty>obj</cproperty>.

	- when giving some C code listing, use the <cprogramlisting>
	tag. eg:
	<cprogramlisting>
/**
 * bonobo_object_ref:
 * @object: A BonoboObject you want to ref-count
 *
 * increments the reference count for the aggregate BonoboObject.
 */
void
bonobo_object_ref (BonoboObject *object)
{
	g_return_if_fail (object != NULL);
	g_return_if_fail (BONOBO_IS_OBJECT (object));
	g_return_if_fail (object->priv->ao->ref_count > 0);

	object->priv->ao->ref_count++;
}
	</cprogramlisting>
	The coding style for our C code should be that of Bonobo.

------------------------------------------------------------------------------

> 
> I propose we get a team of people to create a "GNOME Manual of Style" and
> then present it to this mailing list for discussion and modification if
> necessary.  It will require a fair amount of work as well as expertise.  
> So, I'd like to see at least two core GDP people in addition to a couple
> people who work with style guides in a corporate or professional setting.  
> I'm hoping a technical writer or editor from Sun and maybe somebody from
> Red Hat or any of the other GNOME Foundation companies would contribute.  
> Of course if any GDPers have a lot of experience with style guides, then
> that is even better.  John Fleck has already agreed to help, so we need
> one or two other core GDPers.
> 
> If anybody has expertise in this area and would like to help, I'd
> definitely like to hear from you.
> 
> Dan
> 
> 
> 
> 
> 
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list
> 

-- 
Mathieu Lacage <mathieu eazel com>