docs/160696: style(9) should be mentioned in the devs' handbook

[Benjamin Kaduk]

On Wed, 12 Oct 2011, Niclas Zeising wrote:

> The following reply was made to PR docs/160696; it has been noted by GNATS.
>
> From: Niclas Zeising <niclas.zeising at gmail.com>
> To: bug-followup at FreeBSD.org, radiomlodychbandytow at o2.pl
> Cc:
> Subject: Re: docs/160696: style(9) should be mentioned in the devs' handbook
> Date: Wed, 12 Oct 2011 12:29:19 +0200
>
> This is a multi-part message in MIME format.
> --------------090008080408060608000208
> Content-Type: text/plain; charset=ISO-8859-1; format=flowed
> Content-Transfer-Encoding: 7bit
>
> Hi!
> Here is a patch that adds a section to the source tree guidelines and
> policies chapter of the developer's handbook about code style, with
> links to relevant manual pages.  It has not been build tested yet, since
> I'm away from my build environment.
> --
> Niclas Zeising
>
> --------------090008080408060608000208
> Content-Type: text/plain;
>  name="doc.developers-handbook.policies.chapter.sgml.diff"
> Content-Transfer-Encoding: 7bit
> Content-Disposition: attachment;
>  filename="doc.developers-handbook.policies.chapter.sgml.diff"
>
> Index: en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
> ===================================================================
> RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml,v
> retrieving revision 1.37
> diff -u -d -r1.37 chapter.sgml
> --- en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml	7 May 2010 06:33:09 -0000	1.37
> +++ en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml	12 Oct 2011 10:22:12 -0000
> @@ -24,6 +24,19 @@
>
>    <para>This chapter documents various guidelines and policies in force for
>      the FreeBSD source tree.</para>
> +
> +  <sect1 id="policies-style">
> +    <title>Style Guidlines</title>
> +    <indeterm><primary>style</primary></indexterm>
> +
> +    <para>In a big programming project like the &os; project, it is important
> +      that everybody involved adheres to the same coding style.  This ensures
> +      that all code looks consistent, and will improve the ability for people
> +      in the project to read and understand the source.  In &os; there are
> +      two manual pages describing the code style to adhere to. These are
> +      &man.style.9; and &man.style.Makefile.5;, for c code and make files,

C is capitalized, of course.
The overall paragraph feels a bit odd, though; maybe like it's written in 
a more informal style than I would expect?  A more standard dry, technical 
writing version might be:
%%%%%%%%%%
<para>When working in a large codebase such as the &os; source, it is 
important to adhere to a common coding style.  This provides uniformity 
amongst the entire code, improving the ability of developers to read, 
understand, and modify the source without needing to become familiar with 
different conventions in different areas of the tree.  The coding style in 
use for &os; is described in two manual pages, &man.style.9; and 
&man.style.Makefile.5;, for C code and makefiles respectively — note 
that style guidelines are implicit in the formatting of example code as 
well as in rules that are explicitly mentioned.
%%%%%%%%%%

Hmm, is it "make file" or "makefile" in this usage?  (I presume it does 
not get capitalized unless it is a <literal>Makefile</literal> or 
something like that ...)

-Ben


> +      respectively.</para>
> +  </sect1>
>
>    <sect1 id="policies-maintainer">
>      <title><makevar>MAINTAINER</makevar> on Makefiles</title>