Making changes to files from the handbook.

[Warren Block]

On Fri, 4 Sep 2015, Lowell Gilbert wrote:

> Jeremy Gransden <jeremy.gransden at 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!