On 17/01/2020 11:00, Alex Peshkoff via Firebird-devel wrote: > > >> And if having HTML is important, I'd suggest to write the docs in >> markdown (or maybe asciidoc) and generate HTML as part of the build >> (eg using pandoc). That is what most other opensource projects do >> these days. For good reasons: authoring and diffing is easier >> compared to HTML > > I can agree with diffing. But what about authoring...
> >> , more powerful in its output option compared to 'just' plain text, >> and readable both in source form and in rendered output. > > What a need to read HTML in source? > The changes in the API docs html cannot be reviewed. When docs are written in markdown they may be rendered to something else and also could be viewable in github. Many docs sites renders markdown in customized style and has a link to sources in github so users can correct creating pool requests in easy way. But when we talk about developers writing docs that are later translated to another technology and are not copies or in sync anymore, importance of this becomes very low. The core docs are in fact temporary docs, so why bother? We must improve the *whole* process, but of course, we have many things done and working so things are more difficult to change. Adriano Firebird-Devel mailing list, web interface at https://lists.sourceforge.net/lists/listinfo/firebird-devel
