Re: [ft-devel] Documentation guidelines file

[Werner LEMBERG]

>> I've attached the `docs/DOCUMENTATION' file (from the draft work at
>> https://github.com/nikramakrishnan/freetype-docs/wiki/Documentation-Guidelines-for-The-FreeType-Project).
>> This should cover everything needed to understand the basics and
>> the markdown formatting of the docs.
> 
> Thanks, very informative! :) The only thing missing (if I haven't
> missed it) is the fact that apostrophes are used to refer to other
> parameters of the same function ... eg:
> 
> ```
>   /****** ...
>    * ...
>    * @description:
>    *   Uses 'a' to meep 'b'.
>    * ...
>    */
>   FT_EXPORT( void )
>   FT_Meep ( A a,
>             B b );
> ```

Ah, this is a slight issue I'm not happy yet in the docs.  I think
this should rather be

  /****** ...
   * ...
   * @description:
   *   Uses `a` to meep `b`.
   * ...
   */

In general, address@hidden' should also use a typewriter face if it links to
C stuff like address@hidden' or address@hidden'.  Nikhil, any chance to adjust
`docwriter' accordingly?  For 'a' vs. `a`, we probably have to walk
manually over all header files.

This somehow slipped my attention, sorry.

>> * Shall we mention that we prefer two spaces after a full stop
>>   ending a sentence?
> 
> Please do, esp. for people who're new to FreeType;

Yep.

>> Ditto for details on uppercasing in section titles (US style, for
>>  example `This and That'), how to cite a C function (without
>>  trailing parentheses), etc., etc.
> 
> Ditto, please do, for the sake of everyone who's new to contributing
> to FT :)

Yep.

>> Also, I'm not sure about the `forced' line filling to column 71 as
>> seen in other files in the `docs' directory.

Ah, this is due to my formatting using Emacs, which has a default line
width of 72 chars.  For the sake of consistency the style guide should
rather mention to use 78 chars.  On the other hand, a well-formatted
document with a shorter line length doesn't hurt...


    Werner