-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Project: Offline documentation
The user manual for OpenSCAD is maintained at Wikibooks. This is a nice solution as everybody with a Wikipedia account can help improving it. The drawback is that it's only available online. The "Print Version" accessible there needs special work and duplicates part of the information.
It would be very useful if generating an offline version that could be shipped with OpenSCAD could be automated.
Wikipedia allows the export of data via a simple interface (https://en.wikipedia.org/wiki/Help:Export)
This is probably mainly intended to be the source for backups and/or for transferring data from one installation to another. There's big list of converters around, most seem to target the import into another wiki software but some will convert to other file formats already. (https://www.mediawiki.org/wiki/Alternative_parsers)
The manual export is easily done by calling https://en.wikibooks.org/wiki/Special:Export and entering "OpenSCAD_User_Manual" into the "Add pages from category". This exports all the text content into one big XML file.
The ideal option would be an automated way to convert this XML file into different formats. As first step, to make it usable as off-line documentation, the target would probably be either static HTML that could be shipped with OpenSCAD or maybe PDF.
It needs investigating if that actual programming is required, or if the existing tools are maybe already sufficient for that. So the specific tasks could be one of
-
write a script that does all the conversion and image downloading
-
write a simple script to just run various existing tools
-
go though the wiki pages of the manual and adjust some of the text so it works nicely with some existing tool
-
use a tool or write a script to scrape the HTML representation from Wikibooks
-
something else, we did not see yet...
Ideally that should run on Linux so it could be integrated into one of the automatic build servers (e.g. Travis). A manual solution that is just started now an then would also be a nice thing.
- Investigate current status of available converters
- Optional: Integrate the solution into the OpenSCAD build process
- An offline user manual that can be included in OpenSCAD releases.
- Programming language is python (or some other widely used scripting language... make a suggestion!)
Easy