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

[Nikhil Ramakrishnan]

Hi,

Thanks for the reply.

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

Also (please correct me if I'm wrong) , the current docs is generated at root/docs/reference/ with `make refdoc`, right? This currently generates HTML files as output documentation from the code at root/src/tools/docmaker, and changing this so that the output is in Markdown is also in the scope of this project?

Regards,

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

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

--

Nikhil Ramakrishnan.