| 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-2020 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 --- |