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

Content:
This paper outlines the following items:
* Indenting
* File naming
* Section naming
* Tags
* Chapters
* Screenshots
* 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 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:
<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 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>

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.  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).

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.

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)