Re: v0.3 of Styleguide

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 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 :
appendix.sgml doesn't cut it.  It's quite possible we'll have numerous
appendixes.  Evolution has:
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


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