Return-Path: X-Original-To: apmail-httpd-docs-archive@www.apache.org Delivered-To: apmail-httpd-docs-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 61B6417EBD for ; Wed, 15 Apr 2015 20:38:30 +0000 (UTC) Received: (qmail 75186 invoked by uid 500); 15 Apr 2015 20:38:25 -0000 Delivered-To: apmail-httpd-docs-archive@httpd.apache.org Received: (qmail 75119 invoked by uid 500); 15 Apr 2015 20:38:25 -0000 Mailing-List: contact docs-help@httpd.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: docs@httpd.apache.org List-Id: Delivered-To: mailing list docs@httpd.apache.org Received: (qmail 75108 invoked by uid 99); 15 Apr 2015 20:38:25 -0000 Received: from mail-relay.apache.org (HELO mail-relay.apache.org) (140.211.11.15) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 15 Apr 2015 20:38:25 +0000 Received: from asf-bz1-us-mid.priv.apache.org (nat1-us-mid.apache.org [23.253.172.122]) by mail-relay.apache.org (ASF Mail Server at mail-relay.apache.org) with ESMTPS id D4A7D1A003F for ; Wed, 15 Apr 2015 20:38:24 +0000 (UTC) Received: by asf-bz1-us-mid.priv.apache.org (ASF Mail Server at asf-bz1-us-mid.priv.apache.org, from userid 33) id B0FCD60862; Wed, 15 Apr 2015 20:38:23 +0000 (UTC) From: bugzilla@apache.org To: docs@httpd.apache.org Subject: [Bug 57819] New: Need a conventions document Date: Wed, 15 Apr 2015 20:38:23 +0000 X-Bugzilla-Reason: AssignedTo X-Bugzilla-Type: new X-Bugzilla-Watch-Reason: None X-Bugzilla-Product: Apache httpd-2 X-Bugzilla-Component: Documentation X-Bugzilla-Version: 2.5-HEAD X-Bugzilla-Keywords: X-Bugzilla-Severity: normal X-Bugzilla-Who: coar@apache.org X-Bugzilla-Status: NEW X-Bugzilla-Priority: P2 X-Bugzilla-Assigned-To: docs@httpd.apache.org X-Bugzilla-Target-Milestone: --- X-Bugzilla-Flags: X-Bugzilla-Changed-Fields: bug_id short_desc product version rep_platform op_sys bug_status bug_severity priority component assigned_to reporter Message-ID: Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 7bit X-Bugzilla-URL: https://bz.apache.org/bugzilla/ Auto-Submitted: auto-generated MIME-Version: 1.0 https://bz.apache.org/bugzilla/show_bug.cgi?id=57819 Bug ID: 57819 Summary: Need a conventions document Product: Apache httpd-2 Version: 2.5-HEAD Hardware: All OS: All Status: NEW Severity: normal Priority: P2 Component: Documentation Assignee: docs@httpd.apache.org Reporter: coar@apache.org We should have a document that defines conventions for the documentation, and then apply & follow it. For example, in some places is used where occurs elsewhere; occasionally appears *inside* code segments, "
" sometimes appears in code blocks, etc. I suggest we come up with conventions patterned after those already pioneered by books (like O'Reilly), or man pages, or *some*thing. We probably need two documents: one for the documentation writers defining how stuff should be written, and one for users explaining how to interpret styles in the documentation. * Distinguish between keywords and arbitrary user-supplied text; * What arguments should be quoted? (I vote for filesystem paths, URLs, AuthName values, and regexes..) Sometimes it's unclear when quotation marks are optional, recommended, or required -- and when they're illegal (think RAW_ARGS directive arguments). * When to use as opposed to . * Consistent indentation. This is just a start.. -- You are receiving this mail because: You are the assignee for the bug. --------------------------------------------------------------------- To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org For additional commands, e-mail: docs-help@httpd.apache.org