You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Is your feature request related to a problem? Please describe.
The manual is typographically beautiful and self-contained, but it is lagging behind the code development. The main reason for that is that it is complicated to introduce small version-controlled changes due to the used .docx format.
Some features in the master version are currently not properly described in the manual. Hence, it is impossible to make a release, even if the code is otherwise sufficiently tested.
Describe the solution you'd like
I see two options:
LaTeX . It will allow to keep all the beauty (especially, formulae). Building of PDF can probably be put inside Github Actions to be fully automatic. Thus the final manual itself (as a single file) and all references to it will stay intact.
Markdown. This will allow easier hierarchic extension of the manual. And it is more convenient to be browsed online, if combined with Github Pages (see Title (landing) page #243). However, the latter is also a drawback, since browsing the files directly in GitHub or some local copy would be inferior. It may be possible to automatically build PDF out of a tree of .md files, but the result will necessarily be less beautiful.
Both can probably be implemented semi-automatically with modern tools. So the fist task is to study them and choose the most suitable one.
Since that is related to Github Pages, we should study, how they are stored (probably, in separate repository). This may conflict with atomistic approach (documentation together with code) that we want to achieve for all new features.
Additional context
This will greatly improve the collaborative development, since everything (including all documentation changes) related to any feature (or change, in general) can (and must) be combined into a single pull request. And it will make rapid releases possible with the further goal to have many minor versions and not so much major.
Is your feature request related to a problem? Please describe.
The manual is typographically beautiful and self-contained, but it is lagging behind the code development. The main reason for that is that it is complicated to introduce small version-controlled changes due to the used
.docxformat.Some features in the master version are currently not properly described in the manual. Hence, it is impossible to make a release, even if the code is otherwise sufficiently tested.
Describe the solution you'd like
I see two options:
LaTeX . It will allow to keep all the beauty (especially, formulae). Building of PDF can probably be put inside Github Actions to be fully automatic. Thus the final manual itself (as a single file) and all references to it will stay intact.
Markdown. This will allow easier hierarchic extension of the manual. And it is more convenient to be browsed online, if combined with Github Pages (see Title (landing) page #243). However, the latter is also a drawback, since browsing the files directly in GitHub or some local copy would be inferior. It may be possible to automatically build PDF out of a tree of
.mdfiles, but the result will necessarily be less beautiful.Both can probably be implemented semi-automatically with modern tools. So the fist task is to study them and choose the most suitable one.
Since that is related to Github Pages, we should study, how they are stored (probably, in separate repository). This may conflict with atomistic approach (documentation together with code) that we want to achieve for all new features.
Additional context
This will greatly improve the collaborative development, since everything (including all documentation changes) related to any feature (or change, in general) can (and must) be combined into a single pull request. And it will make rapid releases possible with the further goal to have many minor versions and not so much major.