From owner-freebsd-doc@freebsd.org  Sat Sep  5 14:25:31 2015
Return-Path: <owner-freebsd-doc@freebsd.org>
Delivered-To: freebsd-doc@mailman.ysv.freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org
 [IPv6:2001:1900:2254:206a::19:1])
 by mailman.ysv.freebsd.org (Postfix) with ESMTP id 97AC49C94EE
 for <freebsd-doc@mailman.ysv.freebsd.org>;
 Sat,  5 Sep 2015 14:25:31 +0000 (UTC)
 (envelope-from wblock@wonkity.com)
Received: from wonkity.com (wonkity.com [67.158.26.137])
 (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
 (Client CN "wonkity.com", Issuer "wonkity.com" (not verified))
 by mx1.freebsd.org (Postfix) with ESMTPS id 5A30B1014
 for <freebsd-doc@freebsd.org>; Sat,  5 Sep 2015 14:25:31 +0000 (UTC)
 (envelope-from wblock@wonkity.com)
Received: from wonkity.com (localhost [127.0.0.1])
 by wonkity.com (8.15.2/8.15.2) with ESMTPS id t85EPTGx060647
 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO);
 Sat, 5 Sep 2015 08:25:29 -0600 (MDT)
 (envelope-from wblock@wonkity.com)
Received: from localhost (wblock@localhost)
 by wonkity.com (8.15.2/8.15.2/Submit) with ESMTP id t85EPSqo060644;
 Sat, 5 Sep 2015 08:25:29 -0600 (MDT)
 (envelope-from wblock@wonkity.com)
Date: Sat, 5 Sep 2015 08:25:28 -0600 (MDT)
From: Warren Block <wblock@wonkity.com>
To: Lowell Gilbert <freebsd-lists@be-well.ilk.org>
cc: Jeremy Gransden <jeremy.gransden@gmail.com>, freebsd-doc@freebsd.org
Subject: Re: Making changes to files from the handbook.
In-Reply-To: <44a8t2kqtt.fsf@be-well.ilk.org>
Message-ID: <alpine.BSF.2.20.1509050808390.46406@wonkity.com>
References: <CALi7Q_rg1KQAZCUwC09DFLaiN-P2+KKwsac7hPgqi_6jk3tf+A@mail.gmail.com>
 <44a8t2kqtt.fsf@be-well.ilk.org>
User-Agent: Alpine 2.20 (BSF 67 2015-01-07)
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII; format=flowed
X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3
 (wonkity.com [127.0.0.1]); Sat, 05 Sep 2015 08:25:29 -0600 (MDT)
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.20
Precedence: list
List-Id: Documentation project <freebsd-doc.freebsd.org>
List-Unsubscribe: <https://lists.freebsd.org/mailman/options/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc/>
List-Post: <mailto:freebsd-doc@freebsd.org>
List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help>
List-Subscribe: <https://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Sat, 05 Sep 2015 14:25:31 -0000

On Fri, 4 Sep 2015, Lowell Gilbert wrote:

> Jeremy Gransden <jeremy.gransden@gmail.com> writes:
>
>> Since the handbook, FAQ, and other docs come in a variety of formats; what
>> files are the correct ones to create a pr and diff from when changes are
>> made?
>
> The formats you see are all outputs.
> Like for programming, you want to change the source code.
>
> See the FreeBSD Documentation Project Primer for New Contributors:
> 	https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/
>
> In particular, your question is covered in:
> 	https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/working-copy-checking-out.html

To elaborate, most of the books and articles are written in DocBook XML, 
which is described in the FDP Primer.

Patches are nice but not required in doc bug reports.  The really 
important things in a doc bug report are:

   * the specific location of the problem
   * what is wrong
   * what it should be to be right

Patches cover all of that, but documentation markup can be intimidating. 
A bug report with just plain text that covers those three points is 
enough.  Markup can be added by the committer.

Thanks!