Re: [ft-devel] Questions related to current Documentation (and changes)

[Werner LEMBERG]

> What you're trying to say is that this project also involves
> *manual* conversion of the current tutorials etc. to markdown?

Well, for testing purposes you have to check whether everything's
working, no?  So at least *some* part of the documentation should be
converted – maybe you can even use pandoc for that since I took great
care to have meaningful HTML :-) It is not necessary to handle
everything, since this is a dull job without technical merits.[*]

> Also (please correct me if I'm wrong) , the current docs is
> generated [...] with `make refdoc`, right?

Correct.

> This currently generates HTML files as output documentation from
> [...] docmaker, and changing this so that the output is in Markdown
> is also in the scope of this project?

Yes.  I believe that `docmaker' or maybe something new can be
simplified: Instead of extracting the documentation and converting it
to HTML (and resolving cross references) it would be sufficient to
extract the documentation (and resolving cross references).  The
conversion from markdown to HTML should be done by an external tool.

To summarize: The project consists of

(1) updating `docmaker' to emit markdown but still resolving cross
    references;

(2) updating `make refdoc' so that it handle (1) and emits
    ready-to-view HTML (which will become part of the distribution
    tarball);

(3) converting the remaining HTML documentation of FreeType 2 (in the
    repository https://cgit.freedesktop.org/freetype/freetype-web) to
    markdown – at least partially for testing purposes; and

(4) providing an HTML framework and CSS stylesheets (or whatever is
    necessary) so that the documentation in markdown format can be
    converted to static HTML with a call to `make' or something
    similar, taking away the burden to generate and/or adjust the site
    navigation of www.freetype.org.

Note that the markdown stuff created by (1) will be simply copied and
committed into the `freetype-web' repository, and it should also be
part of www.freetype.org (as it currently already is).


    Werner


[*] Guess who will be doing this dull job :-/