Re: Gnumeric Documentation styleguide

["Andreas J. Guelzow" <aguelzow taliesin ca>]

Kevin Breit wrote:

 > Greetings Gnumeric Hackers, First off, I'd like to wish everyone a Happy
 >  New Year!  I hope you had a most enjoyable and safe New Years.
 >
 > Now, onto the meat of the email.  Attached is the Gnumeric
 > Documentation styleguide I have written up.  I am taking up the
 > task of reorganizing (and redoing most of...) the Gnumeric
 > documentation for the upcoming 1.2 release.  The inspiration for
 > this styleguide is described at the top of the file.
 >
 > Because the styleguide is kind of stringent, I am allowing there to
 > be a review period.  If you disagree with a part of the styleguide,
 >  please don't hesitate to mention that.  However, once this
 > styleguide hits 1.0, it's too late.  Basically a "speak now or
 > forever hold your peace" action.
 >


Well here we go: (Had the e-mail message been wrapped at some reasonable
column this wuld look much better!)

------------------------------------------------------------------------
 >
 >
 > Gnumeric Styleguide v0.1 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 needs to follow understood standards.  This document
 > outlines the said 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 contraversial 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.
 > Filenames are hyphen delimited.

Since virtually everything in the documentation is going to talk about
using gnumeric, this seems to be silly. If I have a file describing how
to use say the ANOVA tool, it will be:

usage-analysistools-anova.sgml

perhaps we could have some examples of non usage-...

I guess this may also implies that  lt's say the Fourier anlysis section
can only contain info on how to use the tool, but not what the tool does??

 >
 > Section Naming: Sections should be both an abbrivated version of their
 >  title as well as their parent section.  These are hypen-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="intro"> <title>Introduction</title> <para> ... </para>
 > <sect2 id="intro-whatis"> <title>What is Gnumeric?</title> <para>
 > ... </para>
 >

 > </sect2> </sect1>
 >
 > Tags: Tags should be used promiscuously in the documentation, even when
 >  formatting is not changed due to the tag.

This is a really bad choice of words: We shouldn't use tags that are not
appropriate, but of course we should tag everything that has an
appropriate tag. Regarding formatting: you can in fact never know which
tags will in fact affect formatting and which ones will not.

 > All application names
 > should be wrapped in the <application> tag, menus should be wrapped
 >  in <menuchoice>, and so on.

When is a program an application and when a command?

 >
 > 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.  Only one chapter should occur per file as well.
 >
 > 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
 >

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


Unfortunately there is an important section missing:


The basic question that should be answered in that section would be:

If person A can't create screenshots according to those specs would you
prefer simply no screenshots, `wrong' screenshots (with the
understanding that somebody has to redo them), or as indicated in the
GDP styleguide that they are send to some address with the hope that
they may be returned after `adjustment'?

Is it better to have an incorrect screenshot or one that is not of the
proper format? For example would it be better to have that incorrect
screenshot in gnumeric/C/formatting.html (assuming it's of the correct
style) or a correct screenshot in the wrong style.

Similarly with the documentation. Are we going to have a `clearing
house' for documentation where incorrectly formatted documentation can
be send for correct formatting (according to the style guide) or do we
prefer no or incorrect documentation over incorrectly ftyled documentation?

In short: what is more important form or content.

Andreas

--
Prof. Dr. Andreas J. Guelzow
http://www.math.concordia.ab.ca/aguelzow