docs/DOCGUIDE

   1 Introduction
   2 ------------
   3
   4 Documentation is an extremely important part of any project, and it
   5 helps a lot if it uses consistent syntax and layout.
   6
   7 The documentation for the FreeType library is maintained in header
   8 files in the `include/` directory in the form of code comments.  These
   9 comments are extracted and organized by 'docwriter' (previously
  10 'docmaker').  The generated docs can be viewed in the
  11 `docs/reference/site/` directory after running `make refdoc`.
  12
  13 Documentation comments follow a specific structure and format as
  14 described below.
  15
  16
  17 Documentation Structure
  18 -----------------------
  19
  20 The documentation is divided into multiple chapters, which contain
  21 sections relevant to it.  The chapter details and sections contained
  22 in them are listed in `include/freetype/ftchapters.h`.  Any unlisted
  23 section is added to the 'Miscellaneous' chapter.
  24
  25 Sections may contain sub-sections which consist of properties,
  26 enumerations, and other data types.
  27
  28
  29 Comment Blocks
  30 --------------
  31
  32 Documentation blocks follow a specific format:
  33
  34     /***************************** (should end on column 77)
  35      *
  36      *                             (1 asterisk, 1 space, then content)
  37      *
  38      */                            (end of block)
  39
  40 To make 'docwriter' recognize a comment block, there must be at least
  41 two asterisks in the first line.  As a consequence, you should change
  42 the second asterisk to something else if you want to prevent a comment
  43 block being handled by 'docwriter' (for example, change `/****/` to
  44 `/*#**/`).
  45
  46
  47 Markup Tags
  48 -----------
  49
  50 Markup tags are used to indicate what comes next.  The syntax for a
  51 tag is:
  52
  53     @foo:
  54
  55 An `@`, followed by the tag, and then `:`.
  56
  57
  58 Reserved Tags
  59 -------------
  60
  61 There are some keywords that have a special meaning to docwriter.
  62 As a convention, all keywords are written in lowercase.
  63
  64 * `chapter`: Defines a chapter.  Usually the title with underscores.
  65 * `sections`: List of sections in the chapter, in order.
  66 * `section`: Defines the start or continuation of a section.
  67 * `title`: Title for a chapter or section.  May contain spaces.
  68 * `abstract`: The abstract for a section, visible in the Table of
  69               Contents (TOC).
  70 * `description`: Detailed description of a tag (except chapters),
  71                  shown as synopsis.
  72 * `values`: A list of 'values' for the tag.  These values are used for
  73             cross-referencing.
  74
  75
  76 Other Tags
  77 ----------
  78
  79 Except the ones given above, any other tags will be added as a part of
  80 a subsection.  All tags are lowercase by convention.
  81
  82
  83 Public Header Definitions
  84 -------------------------
  85
  86 The public headers for FreeType have their names defined in
  87 `include/freetype/config/ftheader.h`.  Any new public header file must
  88 be defined in this file, in the following format:
  89
  90     #define FT_NEWNAME_H  <freetype/newname.h>
  91
  92 Where `newname` is the name of the header file.
  93
  94 This macro is combined with the file location of a sub-section and
  95 printed with the object.
  96
  97
  98 Note on code blocks captured after comments
  99 -------------------------------------------
 100
 101 All non-documentation lines after a documentation comment block are
 102 captured to be displayed as the code for the sub-section.  To stop
 103 collection, a line with `/* */` should be added.
 104
 105
 106 General Formatting Conventions
 107 ------------------------------
 108
 109 * Use two spaces after a full stop ending a sentence.
 110 * Use appropriate uppercasing in titles.  Refer
 111
 112   https://english.stackexchange.com/a/34
 113
 114   for more information.
 115 * Do not add trailing parentheses when citing a C function.
 116
 117
 118 Markdown Usage
 119 --------------
 120
 121 All tags, except the ones that define the name and title for a block
 122 support markdown in them.  Docwriter uses a markdown parser that
 123 follows rules given in John Gruber's markdown guide:
 124
 125   https://daringfireball.net/projects/markdown/syntax
 126
 127 with a few exceptions and extensions, detailed below.  This may also
 128 be referred to as the **FreeType Flavored Markdown**.
 129
 130
 131 Headers
 132 -------
 133
 134 Markdown headers should not be used directly, because these are added
 135 based on section titles, sub-section names, and tags.  However, if a
 136 header needs to be added, note the following correspondence to HTML tags:
 137
 138 * Section title on top of the page is `H1`.
 139 * Sub-section titles are `H2`.
 140 * Parts of sub-sections are `H4`.
 141 * Any header added will be visible in the Table of Contents (TOC) of
 142   the page.
 143
 144
 145 Emphasis
 146 --------
 147
 148 * Use `_underscores_` for italics.
 149 * Use `**double asterisks**` for bold.
 150
 151 Although the other notations (double underscore for bold, single
 152 asterisk for italics) are supported, it is recommended to use the
 153 above for consistency.
 154
 155 Note that there may be cases where having two asterisks or underscores
 156 in a line may lead to text being picked up as italics or bold.
 157 Although unintentional, this is correct markdown behavior.
 158
 159 For inline code, wrap the sequence with backticks (see below).  This
 160 renders symbols correctly without modifications.  If a symbol is
 161 absolutely required outside of an inline code block or code sequence,
 162 escape it with a backslash (like `\*` or `\_`).
 163
 164
 165 Lists
 166 -----
 167
 168 Unordered lists can be created with asterisks:
 169
 170     * Unordered list items can use asterisks.
 171     * Another list item.
 172
 173 Ordered lists start with numbers:
 174
 175     1. This is an ordered list item.
 176     2. Brackets after numbers won't work.
 177
 178 To continue a list over multiple paragraphs, indent them with at least
 179 four spaces.  For example:
 180
 181     1.  Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
 182         Aliquam hendrerit mi posuere lectus.  Vestibulum enim wisi,
 183         viverra nec, fringilla in, laoreet vitae, risus.
 184
 185         Donec sit amet nisl.  Aliquam semper ipsum sit amet velit.
 186         Suspendisse id sem consectetuer libero luctus adipiscing.
 187
 188     2.  This is the second list item.
 189
 190     This paragraph is not a part of the list.
 191
 192 More information on lists in markdown is available at
 193
 194   https://daringfireball.net/projects/markdown/syntax#list
 195
 196
 197 Cross-references
 198 ----------------
 199
 200 Other sub-sections can be linked with the `@` symbol:
 201
 202     @description:
 203       While FreeType's CFF driver doesn't expose API functions by
 204       itself, it is possible to control its behaviour with
 205       @FT_Property_Set and @FT_Property_Get.
 206
 207 If a field in the `values` table of another sub-section is linked, the
 208 link leads to its parent sub-section.
 209
 210
 211 Links and Images
 212 ----------------
 213
 214 All URLs are converted to links in the HTML documentation.
 215
 216 Markdown syntax for links and images are fully supported.
 217
 218
 219 Inline Code
 220 -----------
 221
 222 To indicate a span of code, wrap it with backtick quotes (`` ` ``):
 223
 224     Use the `printf()` function.
 225
 226 Cross-references, markdown, and html styling do not work in inline code
 227 sequences.
 228
 229
 230 Code and Syntax Highlighting
 231 ----------------------------
 232
 233 Blocks of code are fenced by lines with three back-ticks `` ``` ``
 234 followed by the language name, if any (used for syntax highlighting),
 235 as demonstrated in the following example.
 236
 237     ```c
 238       x = y + z;
 239       if ( zookoo == 2 )
 240       {
 241         foobar();
 242       }
 243     ```
 244
 245 Note that the indentation of the opening line and the closing line
 246 must be exactly the same.  The code sequence itself should have a
 247 larger indentation than the surrounding back-ticks.
 248
 249 Like inline code, markdown and html styling is *not* supported inside
 250 code blocks.
 251
 252
 253 Tables
 254 ------
 255
 256 Tables are used to list values, input, and other fields.  The FreeType
 257 Flavored Markdown adopts a simple approach to tables with two columns,
 258 or field definition tables.
 259
 260 Field definition names may contain alphanumeric, underscore, and the
 261 `.` characters.  This is followed by `::`.  The following lines are
 262 the second column of the table.  A field definition ends with the
 263 start of another field definition, or a markup tag.
 264
 265     @Input:
 266       pathname ::
 267         A path to the font file.
 268
 269       face_index ::
 270         See @FT_Open_Face for a detailed description of this
 271         parameter.
 272
 273
 274 Non-breaking Space
 275 ------------------
 276
 277 A tilde can be used to create a non-breaking space.  The example
 278
 279     The encoding value~0 is reserved.
 280
 281 is converted to
 282
 283     The encoding value&nbsp;0 is reserved.
 284
 285
 286 ----------------------------------------------------------------------
 287
 288 Copyright (C) 2018-2020 by
 289 Nikhil Ramakrishnan, David Turner, Robert Wilhelm, and Werner Lemberg.
 290
 291 This  file is  part of  the FreeType  project, and  may only  be used,
 292 modified,  and distributed  under the  terms of  the  FreeType project
 293 license,  LICENSE.TXT.  By  continuing to  use, modify,  or distribute
 294 this file you  indicate that you have read  the license and understand
 295 and accept it fully.
 296
 297
 298 --- end of DOCGUIDE ---