1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
|
Title: Consider porting devdocs to markdown
Author: rodarima
Created: Mon, 18 Dec 2023 22:19:31 +0000
State: closed
The *devdocs* provide very detailed explanations of algorithms, design ideas and other topics and should be easily reachable. They are currently written in Doxygen .doc format, which is nice to link with the API-like documentation but they require a place to live compiled in HTML (or other formats). They cannot be easily read as-is.
On the other hand, GitHub can render Markdown including Math directly from the repository. This increases quite a lot the accessibility from others to the detailed explanations without leaving the repository.
I did some tests with *dw-line-breaking.doc* and they seem to render quite nicely:
The blame is also not very much affected:
Which preserves the original authors.
Here is the [permalink](https://github.com/rodarima/dillo/blob/a60881f18a291c31ffc68e46901ad32bfce42268/devdoc/dw-line-breaking.md)
--%--
From: rodarima
Date: Mon, 18 Dec 2023 23:17:08 +0000
However, this makes the devdocs unable to be opened in dillo itself, which would be quite sad. Here is the same document rendered in dillo using Doxygen (take a closer look at the 77 HTML errors in the bottom right):
--%--
From: rodarima
Date: Sat, 09 Mar 2024 18:54:38 +0000
For now this is being rendered at https://dillo-browser.github.io/doxygen/index.html from the Doxygen with a new theme. Even if we rewrite the standalone pages in Markdown, there is still a lot of information attached to the source code classes and namespaces that is better represented as-is. It also includes cross references which Doxygen handles gracefully.
Here are some examples:
- https://dillo-browser.github.io/doxygen/classdw_1_1Image.html#details
- https://dillo-browser.github.io/doxygen/classdw_1_1Table.html#details
- https://dillo-browser.github.io/doxygen/namespacedw_1_1core_1_1style.html#a65610d57c89e5bee02e4e539fdc989de
Apart from that, Doxygen also allows pages to be written in Markdown, including from the source code itself.
The math formulas are currently rendered as images by LaTeX, but Doxygen also allows the usage of MathJax, which renders them in the browser with Javascript. Here is an example with `USE_MATHJAX = YES`:
Which is very similar to the quality of GitHub and Markdown.
However, the reason they are not shown very well is that the size of the images is too small, so it may be doable to fix it in Doxygen.
For now there is no need to switch to Markdown or other formats, so I'll close this.
|
