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

[Nikhil Ramakrishnan]

Hey,

Sorry for the late reply, I was traveling.

I think I'll start working on a proposal for this! Is there a specific format required by FreeType? What are the things you would suggest to include in the proposal? I will try to get a draft ready ASAP and send it across before I submit on the GSoC website (is that okay?).

Regards,

On 24 February 2018 at 20:41, Werner LEMBERG <address@hidden> wrote:

> 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 :-/

--

Nikhil Ramakrishnan.