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