* I sometimes put `meta' comments into square brackets. [Like this.]
Such comments (in the FreeType headers) should not become links.
Text inside one square bracket will not become a link. This requires
another line specifying the URL to be a qualified link:
Lorem ipsum dolor sit amet, [consectetur] adipiscing elit.
Even something like `[hello][world]' won't become a link
without a `[world]: <URL>' line.
* I'm not a big fan of having the links at separate places. This
means that my preferred solution is `[...](...)' in the header
files. The other solutions should be used for special cases only
(like tables that would become badly formatted in the header files
otherwise).
The plan is to retain address@hidden' in the header files, and change this
to [Foo](bar.md#Foo) in the markdown files. The converter
(MkDocs, for example) can handle the linking when converting
to HTML.
I have made this clearer in the draft.
* Regarding the table format, I would like to re-format all entries of
the form
@Input:
pathname :: A path to the font file.
face_index :: See @FT_Open_Face for a detailed description of this
parameter.
to
@Input:
pathname ::
A path to the font file.
face_index ::
See @FT_Open_Face for a detailed description of this
parameter.
so that we avoid the vertical alignment of `::', making it easier to
add new fields.
OK, will take note of this.