I was thinking from time to time to markdown, because of its simplicity, but there are more tools behind the xml docbook that are useful, like getting the list of parameters, functions ... using xsl and generate the alphabetic indexes in the wiki (which reminds me it hasn't been updated to generate the markdown wiki pages). The ability to set the section id makes it easier to know the anchor in the html pages and link direct to the section.
If the majority of the people consider is time for switching, then I can probably live with it, I am fine overall with markdown.
A variant would be to generate README.md for modules instead of simply text README, probably there are some tools already generating markdown from docbook.
Cheers, Daniel
On 28.06.25 02:04, Richard Chan via sr-dev wrote:
Great work kamailio devs in releasing 6.0.2 and the continuing work on master branch.
Wishing you a restful weekend and while you are at it, here are some ideas, probably half-baked, for your consideration.
Background:
Kamailio uses XML for documentation that is followed by an automatic task that renders to plaintext(README file) for the repo and HTML for the website
Proposal - Use Markdown for docs/
Author docs/ in Markdown - no rendering in-repo
- website will need a static site generator that can create the
internal links
Benefits
- markdown is a common mark-up tool for plaintext that has sufficient
semantic richness for kamailio
- most developers are familiar with markdown especially from Github,
other git-forges
- avoids the in-repo rendering step - most git-forges can render the
markdown file on-screen so that there is less iteration required if there are typos in xml. It is also easier for the developer to validate their docs prior to pushing to master branch
Work Required:
- evaluate and implement the static site generator
- the in-repo README generator can be slowly phased out
Regards Richard (Shih-Ping)
Kamailio - Development Mailing List -- sr-dev@lists.kamailio.org To unsubscribe send an email to sr-dev-leave@lists.kamailio.org Important: keep the mailing list in the recipients, do not reply only to the sender!