Minor documentation updates and fixes.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243
diff --git a/docs/CHANGES b/docs/CHANGES
index 2b4f4d8..c90cf54 100644
--- a/docs/CHANGES
+++ b/docs/CHANGES
@@ -53,7 +53,15 @@ CHANGES BETWEEN 2.9.1 and 2.10
- `FT_Outline_New_Internal' and `FT_Outline_Done_Internal' have
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.
======================================================================
diff --git a/docs/DOCGUIDE b/docs/DOCGUIDE
index 81a354b..432531b 100644
--- a/docs/DOCGUIDE
+++ b/docs/DOCGUIDE
@@ -1,5 +1,6 @@
Introduction
------------
+
Documentation is an extremely important part of any project, and it
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
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
@@ -22,8 +25,10 @@ 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)
@@ -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
`/*#**/`).
+
Markup Tags
-----------
+
Markup tags are used to indicate what comes next. The syntax for a
tag is:
@@ -47,8 +54,10 @@ tag is:
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.
@@ -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
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:
@@ -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
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
@@ -97,8 +114,10 @@ General Formatting Conventions
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:
@@ -108,8 +127,10 @@ follows rules given in John Gruber's markdown guide:
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:
@@ -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
the page.
+
Emphasis
--------
+
* Use `_underscores_` for italics.
* 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,
escape it with a backslash (like `\*` or `\_`).
+
Lists
-----
+
Unordered lists can be created with 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
+
Cross-references
----------------
+
Other sub-sections can be linked with the `@` symbol:
@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
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.
@@ -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
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.
@@ -216,8 +249,10 @@ 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.
@@ -235,8 +270,10 @@ start of another field definition, or a markup tag.
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.
@@ -245,6 +282,7 @@ is converted to
The encoding value 0 is reserved.
+
----------------------------------------------------------------------
Copyright 2018 by
diff --git a/include/freetype/tttables.h b/include/freetype/tttables.h
index 0349164..d916e16 100644
--- a/include/freetype/tttables.h
+++ b/include/freetype/tttables.h
@@ -79,8 +79,8 @@ FT_BEGIN_HEADER
* @description:
* A structure to model a TrueType font header table. All fields follow
* the OpenType specification. The 64-bit timestamps are stored in
- * two-member arrays `Created` and `Modified`, first upper then lower
- * 32 bits.
+ * two-element arrays `Created` and `Modified`, first the upper then
+ * the lower 32~bits.
*/
typedef struct TT_Header_
{