docs/DOCGUIDE - third_party/freetype2 - Git at Google

 Introduction
 ------------

 Documentation is an extremely important part of any project, and it
 helps a lot if it uses consistent syntax and layout.

 The documentation for the FreeType library is maintained in header
 files in the `include/` directory in the form of code comments.  These
 comments are extracted and organized by 'docwriter' (previously
 'docmaker').  The generated docs can be viewed in the
 `docs/reference/site/` directory after running `make refdoc`.

 Documentation comments follow a specific structure and format as
 described below.


 Documentation Structure
 -----------------------

 The documentation is divided into multiple chapters, which contain
 sections relevant to it.  The chapter details and sections contained
 in them are listed in `include/freetype/ftchapters.h`.  Any unlisted
 section is added to the 'Miscellaneous' chapter.

 Sections may contain sub-sections which consist of properties,
 enumerations, and other data types.


 Comment Blocks
 --------------

 Documentation blocks follow a specific format:

     /***************************** (should end on column 77)
      *
      *                             (1 asterisk, 1 space, then content)
      *
      */                            (end of block)

 To make 'docwriter' recognize a comment block, there must be at least
 two asterisks in the first line.  As a consequence, you should change
 the second asterisk to something else if you want to prevent a comment
 block being handled by 'docwriter' (for example, change `/****/` to
 `/*#**/`).


 Markup Tags
 -----------

 Markup tags are used to indicate what comes next.  The syntax for a
 tag is:

     @foo:

 An `@`, followed by the tag, and then `:`.


 Reserved Tags
 -------------

 There are some keywords that have a special meaning to docwriter.
 As a convention, all keywords are written in lowercase.

 * `chapter`: Defines a chapter.  Usually the title with underscores.
 * `sections`: List of sections in the chapter, in order.
 * `section`: Defines the start or continuation of a section.
 * `title`: Title for a chapter or section.  May contain spaces.
 * `abstract`: The abstract for a section, visible in the Table of
               Contents (TOC).
 * `description`: Detailed description of a tag (except chapters),
                  shown as synopsis.
 * `values`: A list of 'values' for the tag.  These values are used for
             cross-referencing.


 Other Tags
 ----------

 Except the ones given above, any other tags will be added as a part of
 a subsection.  All tags are lowercase by convention.


 Public Header Definitions
 -------------------------

 The public headers for FreeType have their names defined in
 `include/freetype/config/ftheader.h`.  Any new public header file must
 be defined in this file, in the following format:

     #define FT_NEWNAME_H  <freetype/newname.h>

 Where `newname` is the name of the header file.

 This macro is combined with the file location of a sub-section and
 printed with the object.


 Note on code blocks captured after comments
 -------------------------------------------

 All non-documentation lines after a documentation comment block are
 captured to be displayed as the code for the sub-section.  To stop
 collection, a line with `/* */` should be added.


 General Formatting Conventions
 ------------------------------

 * Use two spaces after a full stop ending a sentence.
 * Use appropriate uppercasing in titles.  Refer

   https://english.stackexchange.com/a/34

   for more information.
 * Do not add trailing parentheses when citing a C function.


 Markdown Usage
 --------------

 All tags, except the ones that define the name and title for a block
 support markdown in them.  Docwriter uses a markdown parser that
 follows rules given in John Gruber's markdown guide:

   https://daringfireball.net/projects/markdown/syntax

 with a few exceptions and extensions, detailed below.  This may also
 be referred to as the **FreeType Flavored Markdown**.


 Headers
 -------

 Markdown headers should not be used directly, because these are added
 based on section titles, sub-section names, and tags.  However, if a
 header needs to be added, note the following correspondence to HTML tags:

 * Section title on top of the page is `H1`.
 * Sub-section titles are `H2`.
 * Parts of sub-sections are `H4`.
 * Any header added will be visible in the Table of Contents (TOC) of
   the page.


 Emphasis
 --------

 * Use `_underscores_` for italics.
 * Use `**double asterisks**` for bold.

 Although the other notations (double underscore for bold, single
 asterisk for italics) are supported, it is recommended to use the
 above for consistency.

 Note that there may be cases where having two asterisks or underscores
 in a line may lead to text being picked up as italics or bold.
 Although unintentional, this is correct markdown behavior.

 For inline code, wrap the sequence with backticks (see below).  This
 renders symbols correctly without modifications.  If a symbol is
 absolutely required outside of an inline code block or code sequence,
 escape it with a backslash (like `\*` or `\_`).


 Lists
 -----

 Unordered lists can be created with asterisks:

     * Unordered list items can use asterisks.
     * Another list item.

 Ordered lists start with numbers:

     1. This is an ordered list item.
     2. Brackets after numbers won't work.

 To continue a list over multiple paragraphs, indent them with at least
 four spaces.  For example:

     1.  Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
         Aliquam hendrerit mi posuere lectus.  Vestibulum enim wisi,
         viverra nec, fringilla in, laoreet vitae, risus.

         Donec sit amet nisl.  Aliquam semper ipsum sit amet velit.
         Suspendisse id sem consectetuer libero luctus adipiscing.

     2.  This is the second list item.

     This paragraph is not a part of the list.

 More information on lists in markdown is available at

   https://daringfireball.net/projects/markdown/syntax#list


 Cross-references
 ----------------

 Other sub-sections can be linked with the `@` symbol:

     @description:
       While FreeType's CFF driver doesn't expose API functions by
       itself, it is possible to control its behaviour with
       @FT_Property_Set and @FT_Property_Get.

 If a field in the `values` table of another sub-section is linked, the
 link leads to its parent sub-section.


 Links and Images
 ----------------

 All URLs are converted to links in the HTML documentation.

 Markdown syntax for links and images are fully supported.


 Inline Code
 -----------

 To indicate a span of code, wrap it with backtick quotes (`` ` ``):

     Use the `printf()` function.

 Cross-references, markdown, and html styling do not work in inline code
 sequences.


 Code and Syntax Highlighting
 ----------------------------

 Blocks of code are fenced by lines with three back-ticks `` ``` ``
 followed by the language name, if any (used for syntax highlighting),
 as demonstrated in the following example.

     ```c
       x = y + z;
       if ( zookoo == 2 )
       {
         foobar();
       }
     ```

 Note that the indentation of the opening line and the closing line
 must be exactly the same.  The code sequence itself should have a
 larger indentation than the surrounding back-ticks.

 Like inline code, markdown and html styling is *not* supported inside
 code blocks.


 Tables
 ------

 Tables are used to list values, input, and other fields.  The FreeType
 Flavored Markdown adopts a simple approach to tables with two columns,
 or field definition tables.

 Field definition names may contain alphanumeric, underscore, and the
 `.` characters.  This is followed by `::`.  The following lines are
 the second column of the table.  A field definition ends with the
 start of another field definition, or a markup tag.

     @Input:
       pathname ::
         A path to the font file.

       face_index ::
         See @FT_Open_Face for a detailed description of this
         parameter.


 Non-breaking Space
 ------------------

 A tilde can be used to create a non-breaking space.  The example

     The encoding value~0 is reserved.

 is converted to

     The encoding value&nbsp;0 is reserved.


 ----------------------------------------------------------------------

 Copyright (C) 2018-2022 by
 Nikhil Ramakrishnan, David Turner, Robert Wilhelm, and Werner Lemberg.

 This  file is  part of  the FreeType  project, and  may only  be used,
 modified,  and distributed  under the  terms of  the  FreeType project
 license,  LICENSE.TXT.  By  continuing to  use, modify,  or distribute
 this file you  indicate that you have read  the license and understand
 and accept it fully.


 --- end of DOCGUIDE ---
	Introduction
	------------

	Documentation is an extremely important part of any project, and it
	helps a lot if it uses consistent syntax and layout.

	The documentation for the FreeType library is maintained in header
	files in the `include/` directory in the form of code comments. These
	comments are extracted and organized by 'docwriter' (previously
	'docmaker'). The generated docs can be viewed in the
	`docs/reference/site/` directory after running `make refdoc`.

	Documentation comments follow a specific structure and format as
	described below.


	Documentation Structure
	-----------------------

	The documentation is divided into multiple chapters, which contain
	sections relevant to it. The chapter details and sections contained
	in them are listed in `include/freetype/ftchapters.h`. Any unlisted
	section is added to the 'Miscellaneous' chapter.

	Sections may contain sub-sections which consist of properties,
	enumerations, and other data types.


	Comment Blocks
	--------------

	Documentation blocks follow a specific format:

	/***************************** (should end on column 77)
	*
	* (1 asterisk, 1 space, then content)
	*
	*/ (end of block)

	To make 'docwriter' recognize a comment block, there must be at least
	two asterisks in the first line. As a consequence, you should change
	the second asterisk to something else if you want to prevent a comment
	block being handled by 'docwriter' (for example, change `/****/` to
	`/#*/`).


	Markup Tags
	-----------

	Markup tags are used to indicate what comes next. The syntax for a
	tag is:

	@foo:

	An `@`, followed by the tag, and then `:`.


	Reserved Tags
	-------------

	There are some keywords that have a special meaning to docwriter.
	As a convention, all keywords are written in lowercase.

	* `chapter`: Defines a chapter. Usually the title with underscores.
	* `sections`: List of sections in the chapter, in order.
	* `section`: Defines the start or continuation of a section.
	* `title`: Title for a chapter or section. May contain spaces.
	* `abstract`: The abstract for a section, visible in the Table of
	Contents (TOC).
	* `description`: Detailed description of a tag (except chapters),
	shown as synopsis.
	* `values`: A list of 'values' for the tag. These values are used for
	cross-referencing.


	Other Tags
	----------

	Except the ones given above, any other tags will be added as a part of
	a subsection. All tags are lowercase by convention.


	Public Header Definitions
	-------------------------

	The public headers for FreeType have their names defined in
	`include/freetype/config/ftheader.h`. Any new public header file must
	be defined in this file, in the following format:

	#define FT_NEWNAME_H <freetype/newname.h>

	Where `newname` is the name of the header file.

	This macro is combined with the file location of a sub-section and
	printed with the object.


	Note on code blocks captured after comments
	-------------------------------------------

	All non-documentation lines after a documentation comment block are
	captured to be displayed as the code for the sub-section. To stop
	collection, a line with `/* */` should be added.


	General Formatting Conventions
	------------------------------

	* Use two spaces after a full stop ending a sentence.
	* Use appropriate uppercasing in titles. Refer

	https://english.stackexchange.com/a/34

	for more information.
	* Do not add trailing parentheses when citing a C function.


	Markdown Usage
	--------------

	All tags, except the ones that define the name and title for a block
	support markdown in them. Docwriter uses a markdown parser that
	follows rules given in John Gruber's markdown guide:

	https://daringfireball.net/projects/markdown/syntax

	with a few exceptions and extensions, detailed below. This may also
	be referred to as the FreeType Flavored Markdown.


	Headers
	-------

	Markdown headers should not be used directly, because these are added
	based on section titles, sub-section names, and tags. However, if a
	header needs to be added, note the following correspondence to HTML tags:

	* Section title on top of the page is `H1`.
	* Sub-section titles are `H2`.
	* Parts of sub-sections are `H4`.
	* Any header added will be visible in the Table of Contents (TOC) of
	the page.


	Emphasis
	--------

	* Use `_underscores_` for italics.
	* Use `double asterisks` for bold.

	Although the other notations (double underscore for bold, single
	asterisk for italics) are supported, it is recommended to use the
	above for consistency.

	Note that there may be cases where having two asterisks or underscores
	in a line may lead to text being picked up as italics or bold.
	Although unintentional, this is correct markdown behavior.

	For inline code, wrap the sequence with backticks (see below). This
	renders symbols correctly without modifications. If a symbol is
	absolutely required outside of an inline code block or code sequence,
	escape it with a backslash (like `\*` or `\_`).


	Lists
	-----

	Unordered lists can be created with asterisks:

	* Unordered list items can use asterisks.
	* Another list item.

	Ordered lists start with numbers:

	1. This is an ordered list item.
	2. Brackets after numbers won't work.

	To continue a list over multiple paragraphs, indent them with at least
	four spaces. For example:

	1. Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
	Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
	viverra nec, fringilla in, laoreet vitae, risus.

	Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
	Suspendisse id sem consectetuer libero luctus adipiscing.

	2. This is the second list item.

	This paragraph is not a part of the list.

	More information on lists in markdown is available at

	https://daringfireball.net/projects/markdown/syntax#list


	Cross-references
	----------------

	Other sub-sections can be linked with the `@` symbol:

	@description:
	While FreeType's CFF driver doesn't expose API functions by
	itself, it is possible to control its behaviour with
	@FT_Property_Set and @FT_Property_Get.

	If a field in the `values` table of another sub-section is linked, the
	link leads to its parent sub-section.


	Links and Images
	----------------

	All URLs are converted to links in the HTML documentation.

	Markdown syntax for links and images are fully supported.


	Inline Code
	-----------

	To indicate a span of code, wrap it with backtick quotes (`` ` ``):

	Use the `printf()` function.

	Cross-references, markdown, and html styling do not work in inline code
	sequences.


	Code and Syntax Highlighting
	----------------------------

	Blocks of code are fenced by lines with three back-ticks `` ``` ``
	followed by the language name, if any (used for syntax highlighting),
	as demonstrated in the following example.

	```c
	x = y + z;
	if ( zookoo == 2 )
	{
	foobar();
	}
	```

	Note that the indentation of the opening line and the closing line
	must be exactly the same. The code sequence itself should have a
	larger indentation than the surrounding back-ticks.

	Like inline code, markdown and html styling is not supported inside
	code blocks.


	Tables
	------

	Tables are used to list values, input, and other fields. The FreeType
	Flavored Markdown adopts a simple approach to tables with two columns,
	or field definition tables.

	Field definition names may contain alphanumeric, underscore, and the
	`.` characters. This is followed by `::`. The following lines are
	the second column of the table. A field definition ends with the
	start of another field definition, or a markup tag.

	@Input:
	pathname ::
	A path to the font file.

	face_index ::
	See @FT_Open_Face for a detailed description of this
	parameter.


	Non-breaking Space
	------------------

	A tilde can be used to create a non-breaking space. The example

	The encoding value~0 is reserved.

	is converted to

	The encoding value 0 is reserved.


	----------------------------------------------------------------------

	Copyright (C) 2018-2022 by
	Nikhil Ramakrishnan, David Turner, Robert Wilhelm, and Werner Lemberg.

	This file is part of the FreeType project, and may only be used,
	modified, and distributed under the terms of the FreeType project
	license, LICENSE.TXT. By continuing to use, modify, or distribute
	this file you indicate that you have read the license and understand
	and accept it fully.


	--- end of DOCGUIDE ---