freetype-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [ft-devel] Markdown Documentation in header files


From: Ankit Dhankhar
Subject: Re: [ft-devel] Markdown Documentation in header files
Date: Wed, 2 May 2018 05:12:25 +0530


(1)
There are two formats for markup tags:

<Section> and @Section

                     

I suggest replacing these with a single format that is easy to write.

That sounds nice, as it will make 'docmaker' to handle less cases, as of now two are being supported .
 

(2)
I have previously discussed (with Werner) about whether to retain the current markup tags.
I believe these should be selectively retained, because this (a) makes it easy to differentiate
between sections, and (b) this may prove useful in the future if there is an additional requirement.

(3)
For each section of a comment block, currently there is only a starting tag, like <Section>.
I suggest adding an ending tag like </Section> so that anything between these tags can be
directly parsed as markdown.

Agree, with the fact it will provide more freedom of having discontinuous blocks the same section.
And no more comment symbols like "/*  */" or "*" in each line.

 
(4)
Code blocks in comments are currently wrapped in curly brackets. This can be either replaced
with the triple backticks (```) in the documentation itself, or this replacement can be handled by
the modified docmaker depending on the requirement of the to-html converter.

But the application of previous point sounds better for this like
<code>
...
some code
...
</code>
 
That can also be directly parsed as markdown.Even GFM highlights for code block according
to language mention with initial backticks like
```c
code
```
will be highlighted differently than
```
code
```
untill (```) are replaced by (```c) by docmaker itself.



Ankit


reply via email to

[Prev in Thread] Current Thread [Next in Thread]