Difference between revisions of "Synchronize Wiki with Docbook"
User000name (talk | contribs) (https://www.youtube.com/watch?v=4BvwpjaGZCQ - "How to Use a Raw Egg to Determine if Your Mattress is Awful - #PURPLE - YouTube") |
m (Reverted edits by User000name (talk) to last revision by Sean) |
||
| Line 1: | Line 1: | ||
BRL-CAD has more than a million words of documentation (thousands of pages) in a variety of formats. We have a long-term goal to consolidate as much as possible into the Docbook format so that it can be more directly managed by our revision control system and integrated with the source code. At the same time, we have a user-editable wiki that is really easy for users and developers alike to keep up to date. The two, however, are not immediately compatible with one another. Data is not shared or synchronized. | BRL-CAD has more than a million words of documentation (thousands of pages) in a variety of formats. We have a long-term goal to consolidate as much as possible into the Docbook format so that it can be more directly managed by our revision control system and integrated with the source code. At the same time, we have a user-editable wiki that is really easy for users and developers alike to keep up to date. The two, however, are not immediately compatible with one another. Data is not shared or synchronized. | ||
| − | The main goal of this project would be to synchronize the two so that edits to either are reflected in the other without loss of data. One of the main challenges is how to retain the more expressive Docbook markup within | + | The main goal of this project would be to synchronize the two so that edits to either are reflected in the other without loss of data. One of the main challenges is how to retain the more expressive Docbook markup within Mediawiki so that edits via the wiki are not "dumbed down" to the more simple Mediawiki syntax. |
| − | The initial thoughts on our end are to implement a | + | The initial thoughts on our end are to implement a Mediawiki extension that understands how to translate to/from the Docbook format that faithfully preserves all Docbook tagging. You're welcome to suggest another approach. |
A great starting point for this project are our existing command sets for BRL-CAD and MGED (our main geometry editor). They respectively constitute approximately 400 and 700 commands that have a page of documentation each. | A great starting point for this project are our existing command sets for BRL-CAD and MGED (our main geometry editor). They respectively constitute approximately 400 and 700 commands that have a page of documentation each. | ||
| Line 17: | Line 17: | ||
* Basic familiarity with Docbook | * Basic familiarity with Docbook | ||
| − | * Basic familiarity with | + | * Basic familiarity with Mediawiki editing and/or Mediawiki extensions |
* Familiarity with web development technologies | * Familiarity with web development technologies | ||
* Basic familiarity with a revision control system (Subversion) | * Basic familiarity with a revision control system (Subversion) | ||
Latest revision as of 17:11, 5 December 2017
BRL-CAD has more than a million words of documentation (thousands of pages) in a variety of formats. We have a long-term goal to consolidate as much as possible into the Docbook format so that it can be more directly managed by our revision control system and integrated with the source code. At the same time, we have a user-editable wiki that is really easy for users and developers alike to keep up to date. The two, however, are not immediately compatible with one another. Data is not shared or synchronized.
The main goal of this project would be to synchronize the two so that edits to either are reflected in the other without loss of data. One of the main challenges is how to retain the more expressive Docbook markup within Mediawiki so that edits via the wiki are not "dumbed down" to the more simple Mediawiki syntax.
The initial thoughts on our end are to implement a Mediawiki extension that understands how to translate to/from the Docbook format that faithfully preserves all Docbook tagging. You're welcome to suggest another approach.
A great starting point for this project are our existing command sets for BRL-CAD and MGED (our main geometry editor). They respectively constitute approximately 400 and 700 commands that have a page of documentation each.
References[edit]
- doc/docbook
Requirements[edit]
- Basic familiarity with Docbook
- Basic familiarity with Mediawiki editing and/or Mediawiki extensions
- Familiarity with web development technologies
- Basic familiarity with a revision control system (Subversion)
