Re: Roadmap to Euphoria 4.2
- Posted by ghaberek (admin) Sep 04, 2019
- 1298 views
If we expect people to help, we need to use a format that everyone can use. Both to view, and to create the docs.
Which means a standard format, with help viewers available for the various platforms, and help creators available for the various platforms which can create platform-agnostic help files.
We already have a toolchain for creating docs: creole and eudoc. The problem is, nobody's touched the code in years, and creole support is getting harder and harder to find. Markdown seems to have that format war.
Preferably a program to create help files which can be installed without downloading a huge toolchain with the attendant learning curve, if there's a choice.
I've found most "generic" documentation generators, like Doxygen, are only generic to curly-brace languages. And most other popular languages have their own generator, like Sphinx for Python.
Suggestions?
Move to markdown. Parse docs into an intermediate format, like EDS or SQLite. Have pluggable output generators, and default to HTML.
Oh, by they way "Why isn't it written in Euphoria/Phix?" is sure to be one of the first questions someone asks.
It is likely this will continue to be written in Euphoria.
ll that being said, I don't think it's time to move to a new documentation system. Let's focus on the correctness of what we've got now, and revisit that after a release.
-Greg
