xref: /xsrc/external/mit/freetype/dist/docs/DOCGUIDE

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&nbsp;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 ---