Return-Path: 
 <dev-return-7028-apmail-beehive-dev-archive=beehive.apache.org@beehive.apache.org>
Delivered-To: apmail-beehive-dev-archive@www.apache.org
Received: (qmail 42512 invoked from network); 24 Aug 2005 16:54:27 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur.apache.org with SMTP; 24 Aug 2005 16:54:27 -0000
Received: (qmail 73240 invoked by uid 500); 24 Aug 2005 16:54:27 -0000
Delivered-To: apmail-beehive-dev-archive@beehive.apache.org
Received: (qmail 73214 invoked by uid 500); 24 Aug 2005 16:54:26 -0000
Mailing-List: contact dev-help@beehive.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:dev-help@beehive.apache.org>
List-Unsubscribe: <mailto:dev-unsubscribe@beehive.apache.org>
List-Post: <mailto:dev@beehive.apache.org>
List-Id: <dev.beehive.apache.org>
Reply-To: "Beehive Developers" <dev@beehive.apache.org>
Delivered-To: mailing list dev@beehive.apache.org
Received: (qmail 73201 invoked by uid 99); 24 Aug 2005 16:54:26 -0000
Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 24 Aug 2005 09:54:26 -0700
X-ASF-Spam-Status: No, hits=0.0 required=10.0
	tests=RCVD_BY_IP,SPF_HELO_PASS,SPF_PASS
X-Spam-Check-By: apache.org
Received-SPF: pass (asf.osuosl.org: domain of richfeit@gmail.com designates
 64.233.170.197 as permitted sender)
Received: from [64.233.170.197] (HELO rproxy.gmail.com) (64.233.170.197)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 24 Aug 2005 09:54:42 -0700
Received: by rproxy.gmail.com with SMTP id a36so191928rnf
        for <dev@beehive.apache.org>; Wed, 24 Aug 2005 09:54:22 -0700 (PDT)
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
        s=beta; d=gmail.com;
        h=received:message-id:date:from:user-agent:x-accept-language:mime-version:to:subject:references:in-reply-to:x-enigmail-version:x-enigmail-supports:content-type:content-transfer-encoding;
        b=bacDOiyrodwHGzSeWyr//GZBQKwQbNif7MLsK/71+Kmk10fMXWdS1SsBX8S8Z1piXvDefMhUO08x3+k7F7YMaoY28Lgiw8CCxxSa1txDH9g7nbdm3Hq9ipFuwksnB3GhCp9IKjUYc3R2I7u4xvnNBSDENLipIcoZdbx5hbcyAF4=
Received: by 10.39.3.42 with SMTP id f42mr420080rni;
        Wed, 24 Aug 2005 09:54:22 -0700 (PDT)
Received: from ?10.36.33.148? ( [63.96.174.247])
        by mx.gmail.com with ESMTP id k23sm549302rnb.2005.08.24.09.54.22;
        Wed, 24 Aug 2005 09:54:22 -0700 (PDT)
Message-ID: <430CA63C.4000300@gmail.com>
Date: Wed, 24 Aug 2005 10:54:20 -0600
From: Rich Feit <richfeit@gmail.com>
User-Agent: Mozilla Thunderbird 1.0.6 (Windows/20050716)
X-Accept-Language: en-us, en
MIME-Version: 1.0
To: Beehive Developers <dev@beehive.apache.org>
Subject: Re: suggestions for Forrest documentation formatting
References: <e9ac83540508240946710cf167@mail.gmail.com>
In-Reply-To: <e9ac83540508240946710cf167@mail.gmail.com>
X-Enigmail-Version: 0.90.0.0
X-Enigmail-Supports: pgp-inline, pgp-mime
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-Virus-Checked: Checked by ClamAV on apache.org
X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N

+1 to all (and I'd emphasize #3 as "indent with four spaces rather than 
tabs *or two spaces*).

The one thing I'd clarify is that intra-page linking can still just use 
a href="#...".  Anyone feel like intra-page section links should go out 
through site.xml?

Rich

Eddie O'Neil wrote:

>All--
>
>  As several of us seem to be writing documentation, why don't we
>adopt some conventions for how the doc is formatted and how documents
>are named?
>
>  Suggestions:
>
>- use camel-case for document names rather than a mix of '_', '-', and
>camel case
>- use camel-case for Forrest <section> identifiers
>- indent with four spaces rather than tabs
>- do intra-site linking through site.xml for both document links and
>section links (see the <ant-macros> element in site.xml for an example
>of section links)
>- name documents without too much repetition.  For example, I just
>renamed some docs like: controls/controls_overview.xml to
>controls/overview.xml.
>
>  I'd be willing to keep going through the documentation changing some
>of this  before ship since it makes the doc kit more consistent and
>URL friendly if everyone agrees that it's the right thing to do.
>
>  Thoughts?  Other suggestions?
>
>Eddie
>
>  
>