This style guide is intended to be *in addition* to the O'Reilly and
Associates style guide at
http://www.ora.com/oreilly/author/stylesheet.html
===========================================================================
===========
Prose Guide
===========
Tone: somewhere between formal and informal.
For example:
- We use contractions
- We don't say things like "You see"
- Always title sidebars
- High level chapter outline:
- This is what I'm going to tell you.
- I'm telling you this *right now*.
- This is what I told you.
- We have a "Version Control System", NOT a "Revision Control
System"
- We have "working copies", not "working directories"
- Always use long Subversion commands (e.g. "checkout", not "co", etc)
- We perform "commits"; we don't "check in" or do "checkins"
===========================================================================
================
Subversion Guide
================
- Our sample repository will be its own repository that all
examples come from and it will be publically accessible. ###TODO
- Primary user: Sally
- Secondary user: Harry
- Tertiary user: Ira
- Primary client machine: newyork
- Primary server machine/URL: svn.red-bean.com
===========================================================================
============
Markup Guide
============
- The DTD used for the Subversion book is the Docbook Lite DTD as
defined by O'Reilly & Associates. You'll find it at in our source
tree and in ftp://ftp.oreilly.com/pub/dblite/
- You should *always* validate your xml before checking in. Do not
check in xml that is not well-formed. See the README for how to
validate your xml.
- All markup should be properly indented, with the exception of
blocks, which should be aligned all the way to the
left. For example:
Tips
Flornthorple Plathering
The real key to Plathering is to start with
a good glab. A good glab provides a solid thorpy foundation.
Cross-blather
Cross-blather tends to create a hoopy pile of crandy. You
can avoid this by using the cross-blather avoid
command.
$ cb-avoid
Avoiding blather......... Done
$
===========================================================================
=============
Miscellaneous
=============
- Anything that needs attention or fixing should be marked with
###TODO so that it's easy to find. Also, please add your userid to
any inline comments to facilitate discussion 'in the code.'
- Do you want to mention svnbook.el in here? Note that it's already
mentioned in the top-level HACKING file. Maybe this HACKING file
should be merged into that one? I dunno, you guys make the call.