Re: v0.3 of Styleguide

[Jody Goldberg <jody gnome org>]

On Thu, Jan 03, 2002 at 12:21:55PM -0600, Kevin Breit wrote:
> Gnumeric Styleguide v0.2
 Gnumeric Styleguide v0.3
> by Kevin Breit (mrproper ximian com)
>
> Purpose:
> Gnumeric 1.0 came included with over 400 pages worth of
> documentation.  While generally complete in content, the
It was no where near complete in content.

> documentation was unsatisfactory in regards to organization.  The
> organization made navigating the SGML files a challenge.  Gnumeric
> 1.2 is going to be a port to Gnome 2.0.  In this port, the
> documentation is going to require a port to XML.  While not a
> large effort, the port is generally a good time to reorganize, if
> not rewrite, the Gnumeric documentation.  For the documentation to
> be easy to navigate, the documentation should follow understood
> standards.  This document outlines the recommended standards to
> follow while writing the documentation.
Please wrap lines.
The purpose paragraph need not be in the style guide.  With luck the
guide will surve well past the transition to xml.
 
> Indenting:
>   Indenting is a very controversial topic among most programmers.
>   I have found my favorite styles and found most people use the
>   same way.  Indenting will use 2 spaces.  If you're using emacs
s/will/should/
>   with psgml mode as your text editor, you can set the indenting
>   to 2 using the SGML -> File Options -> Indent Step menu option.
>   A carriage return occurs after most tags and is mostly indented.
>   The following are exceptions to a return after a tag:
> <title>
> <application>
> <xref>
> <graphic>
>   For example, to define a section, you would use the following format:
>
> <sect1 id="intro">
>   <title>Introduction</title>
>   <para>
>     ...
>   </para>
> </sect1>
>
> File Naming:
>   Files should all end with .sgml.  They should also be an
Reasonable.

>   annotated version of the chapter title.  All files should also
>   be prefixed with the type of file they are.  For example, a file
>   describing how to do basic navigating of the Gnumeric interface
>   would be a "usage" file.
This seems a tad arbitrary.  Maintaining a list of the blessed 'types'
and doing the characterization seems non-trivial.  Could we start
off a touch simpler and use something like :
    chapter-'name'
    appendix.sgml
 
> Section Naming:
>   Sections should be both an abbreviated version of their title as
>   well as their parent section.  These are hyphen-delimited.
Seems viable as long a we know there are no id length limitations.
 
> Tags: Tags should be used promiscuously in the documentation, even
> when formatting is not changed due to the tag.  However, the tags
> should be used only when relevant.
This is a somewhat vacuous statement.
    'Use tags everywhere they make sense'

> All application names should be wrapped in the <application> tag,
> menus should be wrapped in <menuchoice>, and so on.  <application>
> and <command> can often times can conflict.  <application> is used
> by default.  <command> is used only when you say something similar
> to "To run <application>Gnumeric</application>, type
> <command>gnumeric</command> at your terminal."  In summary,
> <command> is used when the application name is used to execute
> something (usually that application).
Very useful.  Having a this sort of list is helpful.  Would these
comments belong in the GDP ?
 
> Chapters: Chapters should be defined in the file which encompasses
> with them.  The entity for the chapter will of course be defined
> in the gnumeric.sgml file.  The <chapter> tag will be issued in
> the chapter files.  This will help to make associating files to
> content easier for new writers.  Number of chapters should be kept
> to a reasonable minimum.  One file cannot cover more than one
> chapter.
good.
 
> Screenshots:
>   Screenshots will follow the GDP's guidelines for screenshots.
>   For up to date information on screenshot requirements, please
>   see the GDP guidelines on CVS:
>       /cvs/gnome-docu/gdp/style/screenshots.sgml
With emphasis on : common theme.  Although I am not sure I agree
with the notion of including window manager decorations we should
adhere to the standard.

We might want to add some mode lines at
the top of docs, similar to what we've been moving to in the source.
see src/sheet.c for an example.

Overall this seems useful.  Thanks Kevin.  Lets get rev 0.4 into cvs.