Editing Google Season of Docs/Project Ideas
From BRL-CAD
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone.
Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 29: | Line 29: | ||
|} | |} | ||
--> | --> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
= Organize all existing user docs = | = Organize all existing user docs = | ||
Line 58: | Line 38: | ||
!align=center|Contacts | !align=center|Contacts | ||
|- | |- | ||
− | |width=62%|Tame the beast. BRL-CAD has more than a million words of documentation spread across hundreds of documents. Some are huge, some are small. There are books, articles, presentations, manual pages, diagrams, reference cards, and more in a variety of formats and locations. The goal of this task to to conduct a complete audit of all existing documentation, | + | |width=62%|Tame the beast. BRL-CAD has more than a million words of documentation spread across hundreds of documents. Some are huge, some are small. There are books, articles, presentations, manual pages, diagrams, reference cards, and more in a variety of formats and locations. The goal of this task to to conduct a complete audit of all existing documentation, categorize and organize documentation, make recommendations and/or facilitate with merging overlapping documentation, and present all available documentation in a new web index. |
References: | References: | ||
* see doc/ hierarchy in a Subversion checkout | * see doc/ hierarchy in a Subversion checkout | ||
Line 66: | Line 46: | ||
|width=18% align=center bgcolor=#eee|Mediawiki, Docbook XML, Subversion | |width=18% align=center bgcolor=#eee|Mediawiki, Docbook XML, Subversion | ||
− | |width=10% align=center| | + | |width=10% align=center|Medium |
|width=10% align=center bgcolor=#eee|yapp, morrison, rossberg | |width=10% align=center bgcolor=#eee|yapp, morrison, rossberg | ||
|} | |} | ||
Line 85: | Line 65: | ||
* http://brlcad.org/tmp/primitives/ | * http://brlcad.org/tmp/primitives/ | ||
|width=18% align=center bgcolor=#eee|Docbook XML, Subversion, basic reading of C/C++ | |width=18% align=center bgcolor=#eee|Docbook XML, Subversion, basic reading of C/C++ | ||
− | |width=10% align=center| | + | |width=10% align=center|Medium |
|width=10% align=center bgcolor=#eee|morrison, rossberg | |width=10% align=center bgcolor=#eee|morrison, rossberg | ||
|} | |} | ||
Line 107: | Line 87: | ||
|} | |} | ||
− | + | = Upgrade doc infrastructure = | |
− | = | ||
{| bgcolor=#fff | {| bgcolor=#fff | ||
Line 116: | Line 95: | ||
!align=center|Contacts | !align=center|Contacts | ||
|- | |- | ||
− | |width=62%|BRL-CAD has | + | |width=62%|BRL-CAD has extensive documentation infrastructure using Docbook XML whereby we "compile" them into HTML, PDF, and other formats. This approach helps ensure docs remain up-to-date, without syntax/structure errors, and allows the documentation to be composed and reused in different ways (e.g., an tutorial on some topic might get embedded as an appendix in one document or a chapter to another). That said, the underlying format is tedious to write and hard for contributors. We'd like to migrate to a newer system like [https://docusaurus.io Docusaurus] or [https://antora.org Antora], converting everything over while still retaining build system integration. |
References: | References: | ||
− | * | + | * see doc/docbook in a source checkout |
− | * | + | * http://brlcad.org/HACKING_BRL-CAD.pdf |
− | * | + | * https://docbook.org |
− | * https:// | + | * https://docusaurus.io |
− | |width=18% align=center bgcolor=#eee| | + | |width=18% align=center bgcolor=#eee|Docbook XML, Markdown, Subversion, Docusaurus |
|width=10% align=center|Hard | |width=10% align=center|Hard | ||
|width=10% align=center bgcolor=#eee|yapp, morrison, rossberg | |width=10% align=center bgcolor=#eee|yapp, morrison, rossberg | ||
|} | |} |