Re: v0.3 of Styleguide

[Kevin Breit <mrproper ximian com>]

On Thu, 2002-01-03 at 13:14, Jody Goldberg wrote:
> On Thu, Jan 03, 2002 at 12:21:55PM -0600, Kevin Breit wrote:
> 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.
Is it still not wrapping for you?

> > 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
appendix.sgml doesn't cut it.  It's quite possible we'll have numerous
appendixes.  Evolution has:
apx-authors.sgml
apx-bugs.sgml
apx-gloss.sgml
It is forseeable that we will be doing this same setup.
  
> > 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.
There are id length limitations; which is why I say abbreviated instead
of regular full length words.  

> > 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'
What do you suggest I word it as?  That is one place I am not sure of.

> > 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 ?
It is, but people only sometimes follow this standard.  It's kind of a
pet pieve of mine, so I'm being redundant with the gdp standards.   

> Overall this seems useful.  Thanks Kevin.  Lets get rev 0.4 into cvs.
Yup, no problem!  I have a couple things to do, but I'll do this
sometime.

Kevin