Re: [ft-devel] Markdown documentation features

[Werner LEMBERG]

> I have written a feature draft (conversion) for the documentation in
> markdown. It is available on my repository's wiki
> <https://github.com/nikramakrishnan/freetype-docs/wiki/Feature-Draft-of-the-FreeType-Markdown-Documentation>.

Very nice!  I agree with all your conclusions.  Some comments.

* I sometimes put `meta' comments into square brackets.  [Like this.]
  Such comments (in the FreeType headers) should not become links.

* 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).

* 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.


    Werner