Gnumeric Styleguide v0.5
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 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.

Note:
This is optional.  This is a recommendation for SGML/XML that is easy for the
writer to deal with.  Personally, going file to file with different indenting styles is quite challenging to do.  You don't need to follow this guide.  However, following it will make life easier for the writers.

Content:
This paper outlines the following items:
* Indenting
* File naming
* Section naming
* Chapters
* Screenshots
* Misc.
* emacs goodies

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

<sect1 id="intro">
  <title>Introduction</title>
  <para>
    ...
  </para>
</sect1>
Lines should be wrapped at 80 or less characters.

File Naming:
  Files should all end with .xml.  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 would be named usage-navigation.sgml.  If a file grows to be too large for one file, it can be changed to be two or more files.  These should associate by name to the parent file.  If the previous example had a section about using the keyboard, the file would be called: usage-navigation-kbd.sgml.  The other file prefix is apx, standing for appendix.  Such files would be a glossary or a menu reference.  Filenames are hyphen delimited. 

Section Naming:
  Sections should be both an abbreviated version of their title as well as their parent section.  These are hyphen-delimited.  An author should be able to open up a section in an SGML section title and be able to identify the parent sections.  For example:

<sect1 id="usage-mail-composing">
  <title>Composing Mail</title>
  <para>
    ...
  </para>
  <sect2 id="usage-mail-composing-html">
    <title>Composing HTML Mail</title>
    <para>
      ...
    </para>
  </sect2>
</sect1>
All titles should be capitalized except for articles.

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.

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

If a screenshot cannot be taken by the writer, they should try to find someone else to take it for them.  This can be done by emailing gnumeric-list gnome org or asking on irc.gnome.org #gnumeric or #gnome.

Misc:
  The documentation is to be done in American English.  We'll leave it to the translators to do the en_GB version.
  When refering to keys on a keyboard, use the name on the keyboard.  Ctrl, not Control key.  It is Enter, not Return.

emacs Goodies:
  This section is in no way a guideline on style.  This is a kind of...reward for reading through this, and hopefully following this.  It includes some nifty emacs tricks which I have learned.
  The first and foremost is nearly a requirement for you emacs users: psgml mode.  psgml mode is used for dealing with XML, SGML, and HTML.  It is very useful, and comes default with most distributions.  The following tips are dependent on psgml mode.  Once psgml mode is installed, you can activate it by adding the following to your .emacs file:

(setq sgml-indent-data t)
(autoload 'sgml-mode "psgml" "My Most Major Mode" t)
(setq sgml-mode-hook '(lambda () "Defaults for SGML mode."
(auto-fill-mode) (setq fill-column 70)))

  The following script finds the nearest ChangeLog file, prepends an entry to the top, and is ready for you to type your changes.  This is activated by typing M-n.

(defun changelog-entry ()
  "Add entry to ChangeLog"
  (interactive)
  (progn
    (if (equal (file-name-nondirectory (buffer-file-name)) "ChangeLog")
        (progn
          (basic-save-buffer)
          (kill-buffer "ChangeLog"))
      (progn
        (add-change-log-entry)))
;       (insert (current-time-string) "\n")))
))
(setq user-mail-address "youremail domain com")
(setq user-full-name "Your Name")

(global-set-key "\M-n" 'changelog-entry)

This will add the <figure> structure for you to your SGML file where the cursor is.  It will prompt for the title of the figure as well as the filename (no extension).  All the data will be generated for you.  This is used by hitting F7.


(defun gdp-insert-figure (title filename)
  (interactive "MTitle: \nMFilename (no extension): ")
  (let ((point (point)))
    (insert
     "<figure>
	<title>"title"</title>
<screenshot>
<screeninfo></screeninfo>
<graphic  format=\"png\" fileref=\""filename"\" srccredit=\"Kevin Breit\">
</screenshot>
</figure>")
    (indent-region point (point) nil)
    (search-backward "</screeninfo>" point t)))
(define-key global-map [f7] 'gdp-insert-figure)

This will add the very common <listitem><para> tags on separate lines.  This is used by hitting F1:

(defun kevin-insert-listitem ()
  (interactive)
  (let ((point (point)))
    (insert
     "<listitem>
        <para>")
    (indent-region point (point) nil)))
(define-key global-map [f1] 'kevin-insert-listitem)