GNOME Bugzilla – Bug 779090
Switch Vala manual to DocBook version downloaded from wiki.gnome.org
Last modified: 2017-02-23 07:12:46 UTC
The version of the Vala manual in the Vala source code has not been updated in many years. The draft version of the manual was moved to wiki.gnome.org. This series of patches now uses the wiki as the source and downloads the DocBook and transforms it in to HTML and DevHelp versions. There is a very old copy of the manual online at http://www.vala-project.org/doc/vala/ This should be either removed or update with the newer version. This series of pages is a first instalment. I hope to finish this off with another set of patches that add version information, navigation icons, a single page HTML version for print and a make target for weasyprint to produce a PDF version.
Created attachment 346475 [details] [review] Rename doc/vala to doc/manual
Created attachment 346476 [details] [review] 02 - Add script to download Vala manual from GNOME wiki
Created attachment 346477 [details] [review] 03 - initial import of DocBook version of manual from GNOME wiki
Created attachment 346478 [details] [review] 04 - switch build system and add XSLT to use DocBook version
Created attachment 346480 [details] [review] 05 - remove old XML sources of manual
Why don't import from online version into sources? This makes you to download two parts in order to get a fully installed and documented version of Vala. Updates can be a few weeks before each release.
(In reply to Daniel Espinosa from comment #6) > Why don't import from online version into sources? This does import the online version into the source. That's what download-manual-from-wiki.sh does. Although that will likely become a make target. These patches are now being reviewed, so watch https://git.gnome.org/browse/vala/log/?h=wip/docbook-manual > This makes you to download two parts in order to get a fully installed and > documented version of Vala. You do a download to update the manual. If you are not updating then the build system produces the version for that release. The download script is for those who want to add to the manual. I see the source as the authoritative version of the manual. The version on the wiki is the draft version. So people can add things, but then it goes through a review process before being added to the source. This allows people to outline an idea and then for it to be polished for the source version. As an editorial policy it is probably better to omit an addition if there is doubt about its accuracy, rather than include a misleading entry in the reference manual. For example there may be a change on the wiki saying all interfaces have to inherit from Object, but that is not the case. So there needs to be discussion and patches around that issue. I'm not sure what you mean by "two parts". 'make install' will install the devhelp version of the Vala reference manual. The html folder is separate and can be copied to a web server or copied locally for offline reading. I intend to add in future a single HTML page version for printing and a PDF version as well. All from the same source - manual.xml. > Updates can be a few weeks before each release. That's really down to how many people contribute and use this tool. When a release is tagged then the reference manual should include that in its header. Once this stage of the review is complete I will submit an additional patch that includes the @VERSION@ from autoconf in the reference manual. This will show what release the manual was built from. Having a process in place is the first step in keeping the manual up to date, but it relies on people wanting to contribute.
commit 00b1ea5b3ac5168bcbcc6ce11612ccc97e967f63 Author: Alistair Thomas <astavale@yahoo.co.uk> Date: Tue Feb 21 00:02:58 2017 +0000 manual: Initial import of manual.xml from wiki.gnome.org commit b8c5ca22b4ad931f9b2ac459768831168f01dda9 Author: Alistair Thomas <astavale@yahoo.co.uk> Date: Thu Jan 19 20:57:20 2017 +0000 manual: Switch to using DocBook from wiki.gnome.org as source