Re: v0.3 of Styleguide

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)

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 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
  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:
  For example, to define a section, you would use the following format:

<sect1 id="intro">

File Naming:
  Files should all end with .sgml.  They should also be an

  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 :
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
  Screenshots will follow the GDP's guidelines for screenshots.
  For up to date information on screenshot requirements, please
  see the GDP guidelines on CVS:
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.

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]