261 lines
8.4 KiB
Plaintext
261 lines
8.4 KiB
Plaintext
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 2018 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 ---
|