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

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!

-- 
Daniel-Constantin Mierla (@ asipto.com)
twitter.com/miconda -- linkedin.com/in/miconda
Kamailio Consultancy, Training and Development Services -- asipto.com