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

[Werner LEMBERG]

Hello Nikhil!


> I had a look at the gsoc project ideas, and am interested in
> "Convert FreeType's HTML documentation to markdown."

Thanks for your interest.

> What I understand:
>
>   *The current docmaker processes the source, extracts the required
>   data for documentation, and converts it into a readable format in
>   HTML.*
>
> What the project expects:
>
>   *Write code so that the documentation can also be generated in
>   markdown, and be converted to HTML.*
>
> Am I right?

Good question.  It probably doesn't make sense to *generate* markdown.
I consider markdown rather as an input format, and the FreeType
documentation itself (i.e., both the stuff in the C header files and
the remaining data like the tutorial) should be converted to markdown
– with extensive cross-referencing as already present in the FreeType
HTML output.

To evaluate whether `docmaker' should be retained and modified, or
whether it could be replaced with `something better' (whatever this
is) is part of the problem.  We are open to suggestions here.

> I have a few questions:
>
> 1) After this change, will the documentation be generated solely in
>    markdown and *later* be converted to other formats?

No, the documentation should rather be *written* in markdown, see
above.  Do you have another idea?

> 2) Does this require a stylized markdown, or the basics (such as
>    GFM)?

[GFM is GitHub's markdown flavour.]  This depends on the used
conversion tool.  Looking at this flavour, I don't see anything
particularly important for FreeType – for example, all code blocks are
in the C language, so there is no special need to support

  ```foo
  blabla
  ```

On the other hand, we are currently using address@hidden' for
cross-referencing, which is more convenient to type than
`[foo](#foo)'...  Maybe this can be retained?

> 3) If (1) is true, will Pandoc be used to convert the docs to html
>    for the website?

As mentioned above, this is not cast in stone, but right now I don't
see a reason to not use it.  I very much like `pandoc', and it is very
actively developed, covering an amazing bunch of output formats.  I
don't say that this is the markdown to html generator of choice, but
it seems like a good start.

> [...]  If you could also recommend any other projects that you think
> is suitable for me, I can start working on a proposal, and take your
> inputs and comments before submission.

Is there anything else besides FreeType? :-)


    Werner