Editing Project - Documentation
Jump to navigation
Jump to search
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 4: | Line 4: | ||
[[File:SeasonofDocs Logo SecondaryGrey 300ppi.png|right|200px|link=https://g.co/seasonofdocs]] | [[File:SeasonofDocs Logo SecondaryGrey 300ppi.png|right|200px|link=https://g.co/seasonofdocs]] | ||
* GNU Octave | * GNU Octave applies for the [https://g.co/seasonofdocs Google Season of Docs (GSoD)] 2020. Potential participation will be announced on '''May 11, 2020 at 12:00 UTC'''. Discuss about your ideas and application with us by using Octave's | ||
** [https://lists.gnu.org/mailman/listinfo/octave-maintainers <code>maintainers@octave.org</code>] mailing list (please [https://en.wikipedia.org/wiki/Posting_style#Bottom-posting bottom post]!) | |||
** | ** [http://webchat.freenode.net?channels=octave <code>#octave</code> IRC channel] in Freenode | ||
** [ | |||
== Existing Documentation == | == Existing Documentation == | ||
:''For a comprehensive list see [[Publications about Octave]].'' | :''For a comprehensive list see [[Publications about Octave]].'' | ||
* [https://www.gnu.org/software/texinfo/ Texinfo] user | * [https://www.gnu.org/software/texinfo/ Texinfo] user documentation for the [https://octave.org/doc/interpreter/ Octave interpreter]. | ||
* [[Doxygen]] documentation for the internal C++ classes and external API. | * [[Doxygen]] documentation for the internal C++ classes and external API. | ||
Line 30: | Line 25: | ||
'''Description''' | '''Description''' | ||
The documentation for the interpreter is presumably the oldest, long grown documentation of the GNU Octave project. It is mostly written in [https://www.gnu.org/software/texinfo/ Texinfo] and strongly interleaved in the [[Building | Octave build process]], i.e., it is necessary to build Octave from source to generate included figures. Additionally, large portions of the Texinfo source are auto generated to stay close to the source code | The documentation for the interpreter is presumably the oldest, long grown documentation of the GNU Octave project. It is mostly written in [https://www.gnu.org/software/texinfo/ Texinfo] and strongly interleaved in the [[Building | Octave build process]], i.e., it is necessary to build Octave from source to generate included figures. Additionally, large portions of the Texinfo source are auto generated to stay close to the source code to avoid stale documentation. A special type of this auto generation are the so-called [[Help text | "docstrings"]], which are extracted from both C++ files and Octave's own script files (m-files). | ||
The resulting Texinfo sources are translated to Info, PDF, PostScript, and HTML, whereas the HTML is further processed to match the [https://doc.qt.io/qt-5/qthelp-framework.html QT Help Framework], which is displayed in | The resulting Texinfo sources are translated to Info, PDF, PostScript, and HTML, whereas the HTML is further processed to match the [https://doc.qt.io/qt-5/qthelp-framework.html QT Help Framework], which is displayed in Octave. | ||
'''Improvements''' | '''Improvements''' | ||
* Check for inconsistencies in the manual, e.g., outdated descriptions, awkwardly ordered information, ... | * Check for inconsistencies in the manual, e.g., outdated descriptions, awkwardly ordered information, ... | ||
* More examples and demo files for using each Octave command. | * More examples and demo files for using each Octave command. | ||
Line 46: | Line 40: | ||
'''Long term goals / highly controversial within the community''' | '''Long term goals / highly controversial within the community''' | ||
* Syntax, structure, and | * Syntax, structure, and readability of Texinfo is a burden for some developers and newcomers. Consider replacement by | ||
** [https://commonmark.org/ CommonMark/Markdown] | ** [https://commonmark.org/ CommonMark/Markdown] | ||
** [https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html reStructuredText] / [https://www.sphinx-doc.org/ Sphinx] | ** [https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html reStructuredText] / [https://www.sphinx-doc.org/ Sphinx] | ||
Line 64: | Line 58: | ||
=== Octave's internal documentation === | === Octave's internal documentation === | ||
Add more Doxygen comments. | |||
'''Resources''' | '''Resources''' | ||
Line 105: | Line 71: | ||
: [[User:siko1056 | Kai]] | : [[User:siko1056 | Kai]] | ||
== | === Octave's wiki === | ||
Flesh out this wiki. | |||
[[Category:Project Ideas]] | [[Category:Project Ideas]] |