minhngoc25a
/
freetype2
mirror of git://git.savannah.gnu.org/freetype/freetype2.git
2
1
Fork 2
Code Issues 4 Releases Wiki Activity

Minor documentation updates and fixes.

This commit is contained in:
Werner Lemberg 2018-12-10 12:11:54 +01:00
parent d01e28f41f
commit 0c83ba6d61
3 changed files with 49 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/CHANGES
View File

@ -53,7 +53,15 @@ CHANGES BETWEEN 2.9.1 and 2.10
- `FT_Outline_New_Internal' and `FT_Outline_Done_Internal' have - `FT_Outline_New_Internal' and `FT_Outline_Done_Internal' have
been removed. These two functions were public by oversight only been removed. These two functions were public by oversight only
and were never documented either. and were never documented.
- A new function `FT_Error_String' returns descriptions of error
codes if configuration macro FT_CONFIG_OPTION_ERROR_STRINGS is
defined.
- `FT_Set_MM_WeightVector' and `FT_Get_MM_WeightVector' are new
functions limited to Adobe MultiMaster fonts to directly set and
get the weight vector.
====================================================================== ======================================================================

38
docs/DOCGUIDE
View File

@ -1,5 +1,6 @@
Introduction Introduction
------------ ------------
Documentation is an extremely important part of any project, and it Documentation is an extremely important part of any project, and it
helps a lot if it uses consistent syntax and layout. helps a lot if it uses consistent syntax and layout.
@ -12,8 +13,10 @@ comments are extracted and organized by 'docwriter' (previously
Documentation comments follow a specific structure and format as Documentation comments follow a specific structure and format as
described below. described below.
Documentation Structure Documentation Structure
----------------------- -----------------------
The documentation is divided into multiple chapters, which contain The documentation is divided into multiple chapters, which contain
sections relevant to it. The chapter details and sections contained sections relevant to it. The chapter details and sections contained
in them are listed in `include/freetype/ftchapters.h`. Any unlisted in them are listed in `include/freetype/ftchapters.h`. Any unlisted
@ -22,8 +25,10 @@ section is added to the 'Miscellaneous' chapter.
Sections may contain sub-sections which consist of properties, Sections may contain sub-sections which consist of properties,
enumerations, and other data types. enumerations, and other data types.
Comment Blocks Comment Blocks
-------------- --------------
Documentation blocks follow a specific format: Documentation blocks follow a specific format:
/***************************** (should end on column 77) /***************************** (should end on column 77)
@ -38,8 +43,10 @@ the second asterisk to something else if you want to prevent a comment
block being handled by 'docwriter' (for example, change `/****/` to block being handled by 'docwriter' (for example, change `/****/` to
`/*#**/`). `/*#**/`).
Markup Tags Markup Tags
----------- -----------
Markup tags are used to indicate what comes next. The syntax for a Markup tags are used to indicate what comes next. The syntax for a
tag is: tag is:
@ -47,8 +54,10 @@ tag is:
An `@`, followed by the tag, and then `:`. An `@`, followed by the tag, and then `:`.
Reserved Tags Reserved Tags
------------- -------------
There are some keywords that have a special meaning to docwriter. There are some keywords that have a special meaning to docwriter.
As a convention, all keywords are written in lowercase. As a convention, all keywords are written in lowercase.
@ -63,13 +72,17 @@ As a convention, all keywords are written in lowercase.
* `values`: A list of 'values' for the tag. These values are used for * `values`: A list of 'values' for the tag. These values are used for
cross-referencing. cross-referencing.
Other Tags Other Tags
---------- ----------
Except the ones given above, any other tags will be added as a part of Except the ones given above, any other tags will be added as a part of
a subsection. All tags are lowercase by convention. a subsection. All tags are lowercase by convention.
Public Header Definitions Public Header Definitions
------------------------- -------------------------
The public headers for FreeType have their names defined in The public headers for FreeType have their names defined in
`include/freetype/config/ftheader.h`. Any new public header file must `include/freetype/config/ftheader.h`. Any new public header file must
be defined in this file, in the following format: be defined in this file, in the following format:
@ -81,14 +94,18 @@ Where `newname` is the name of the header file.
This macro is combined with the file location of a sub-section and This macro is combined with the file location of a sub-section and
printed with the object. printed with the object.
Note on code blocks captured after comments Note on code blocks captured after comments
------------------------------------------- -------------------------------------------
All non-documentation lines after a documentation comment block are All non-documentation lines after a documentation comment block are
captured to be displayed as the code for the sub-section. To stop captured to be displayed as the code for the sub-section. To stop
collection, a line with `/* */` should be added. collection, a line with `/* */` should be added.
General Formatting Conventions General Formatting Conventions
------------------------------ ------------------------------
* Use two spaces after a full stop ending a sentence. * Use two spaces after a full stop ending a sentence.
* Use appropriate uppercasing in titles. Refer * Use appropriate uppercasing in titles. Refer
@ -97,8 +114,10 @@ General Formatting Conventions
for more information. for more information.
* Do not add trailing parentheses when citing a C function. * Do not add trailing parentheses when citing a C function.
Markdown Usage Markdown Usage
-------------- --------------
All tags, except the ones that define the name and title for a block All tags, except the ones that define the name and title for a block
support markdown in them. Docwriter uses a markdown parser that support markdown in them. Docwriter uses a markdown parser that
follows rules given in John Gruber's markdown guide: follows rules given in John Gruber's markdown guide:
@ -108,8 +127,10 @@ follows rules given in John Gruber's markdown guide:
with a few exceptions and extensions, detailed below. This may also with a few exceptions and extensions, detailed below. This may also
be referred to as the **FreeType Flavored Markdown**. be referred to as the **FreeType Flavored Markdown**.
Headers Headers
------- -------
Markdown headers should not be used directly, because these are added Markdown headers should not be used directly, because these are added
based on section titles, sub-section names, and tags. However, if a based on section titles, sub-section names, and tags. However, if a
header needs to be added, note the following correspondence to HTML tags: header needs to be added, note the following correspondence to HTML tags:
@ -120,8 +141,10 @@ header needs to be added, note the following correspondence to HTML tags:
* Any header added will be visible in the Table of Contents (TOC) of * Any header added will be visible in the Table of Contents (TOC) of
the page. the page.
Emphasis Emphasis
-------- --------
* Use `_underscores_` for italics. * Use `_underscores_` for italics.
* Use `**double asterisks**` for bold. * Use `**double asterisks**` for bold.
@ -138,8 +161,10 @@ renders symbols correctly without modifications. If a symbol is
absolutely required outside of an inline code block or code sequence, absolutely required outside of an inline code block or code sequence,
escape it with a backslash (like `\*` or `\_`). escape it with a backslash (like `\*` or `\_`).
Lists Lists
----- -----
Unordered lists can be created with asterisks: Unordered lists can be created with asterisks:
* Unordered list items can use asterisks. * Unordered list items can use asterisks.
@ -168,8 +193,10 @@ More information on lists in markdown is available at
https://daringfireball.net/projects/markdown/syntax#list https://daringfireball.net/projects/markdown/syntax#list
Cross-references Cross-references
---------------- ----------------
Other sub-sections can be linked with the `@` symbol: Other sub-sections can be linked with the `@` symbol:
@description: @description:
@ -180,14 +207,18 @@ Other sub-sections can be linked with the `@` symbol:
If a field in the `values` table of another sub-section is linked, the If a field in the `values` table of another sub-section is linked, the
link leads to its parent sub-section. link leads to its parent sub-section.
Links and Images Links and Images
---------------- ----------------
All URLs are converted to links in the HTML documentation. All URLs are converted to links in the HTML documentation.
Markdown syntax for links and images are fully supported. Markdown syntax for links and images are fully supported.
Inline Code Inline Code
----------- -----------
To indicate a span of code, wrap it with backtick quotes (`` ` ``): To indicate a span of code, wrap it with backtick quotes (`` ` ``):
Use the `printf()` function. Use the `printf()` function.
@ -195,8 +226,10 @@ To indicate a span of code, wrap it with backtick quotes (`` ` ``):
Cross-references, markdown, and html styling do not work in inline code Cross-references, markdown, and html styling do not work in inline code
sequences. sequences.
Code and Syntax Highlighting Code and Syntax Highlighting
---------------------------- ----------------------------
Blocks of code are fenced by lines with three back-ticks `` ``` `` Blocks of code are fenced by lines with three back-ticks `` ``` ``
followed by the language name, if any (used for syntax highlighting), followed by the language name, if any (used for syntax highlighting),
as demonstrated in the following example. as demonstrated in the following example.
@ -216,8 +249,10 @@ larger indentation than the surrounding back-ticks.
Like inline code, markdown and html styling is *not* supported inside Like inline code, markdown and html styling is *not* supported inside
code blocks. code blocks.
Tables Tables
------ ------
Tables are used to list values, input, and other fields. The FreeType Tables are used to list values, input, and other fields. The FreeType
Flavored Markdown adopts a simple approach to tables with two columns, Flavored Markdown adopts a simple approach to tables with two columns,
or field definition tables. or field definition tables.
@ -235,8 +270,10 @@ start of another field definition, or a markup tag.
See @FT_Open_Face for a detailed description of this See @FT_Open_Face for a detailed description of this
parameter. parameter.
Non-breaking Space Non-breaking Space
------------------ ------------------
A tilde can be used to create a non-breaking space. The example A tilde can be used to create a non-breaking space. The example
The encoding value~0 is reserved. The encoding value~0 is reserved.
@ -245,6 +282,7 @@ is converted to
The encoding value 0 is reserved. The encoding value 0 is reserved.
---------------------------------------------------------------------- ----------------------------------------------------------------------
Copyright 2018 by Copyright 2018 by

4
include/freetype/tttables.h
View File

@ -79,8 +79,8 @@ FT_BEGIN_HEADER
* @description: * @description:
* A structure to model a TrueType font header table. All fields follow * A structure to model a TrueType font header table. All fields follow
* the OpenType specification. The 64-bit timestamps are stored in * the OpenType specification. The 64-bit timestamps are stored in
* two-member arrays `Created` and `Modified`, first upper then lower * two-element arrays `Created` and `Modified`, first the upper then
* 32 bits. * the lower 32~bits.
*/ */
typedef struct TT_Header_ typedef struct TT_Header_
{ {