Documentation not up-to-date

[pka]

Documentation in 3.0rc seems to be generated on 20/02/10. There are many changes since then in SVN.

[hamish]

documentation (and everything else) is added to the ISO at build time. the next RC build will automatically incorporate any changes since the previous build was run (which was last weekend).

html files are stored on-disc instead of on-line so that mobile users without an internet connection (or in a locked-down lab) can still read it.

Hamish

[pka]

Version 3.0rc4 (VM):

Documentation in /usr/local/share/livedvd-docs (Help link on desktop) is still much older than /usr/local/share/gisvm/doc. E.g. spatialite is still missing.

[camerons]

I've added files for osgearth.odt and spatialite.odt. I've corrected ossim definition.html which pointed to the wrong location.

Issue now closed. (post 3.0rc4 release)

[hamish]

Replying to camerons:

I've corrected ossim definition.html which pointed to the wrong location.

spatialite had the same problem.

This a very good example where by using an ascii-based doc format I could check all ~ 31 projects for this error within about 30 seconds of seeing the diff in the trac log. It is simply not an efficient use of my time to hunt through all wysiwyg files and almost impossible to do a detailed heuristic search and replace while preserving formatting. And without the diff I would not have known what to look for ... at most I could maintain the 3-5 projects I am most interested in without wasting an hour on it.

This is a matter for the future, but I'm even more convinced now that keeping basic getting-started docs in text-based masters is the only way to go, with project supplied PDFs for full docs and tutorials (e.g. see existing QGIS, GMT, and MB-System manuals/tutorials/cookbooks). The team could offer to accept docs in whatever format and convert to PDF or html as needed, but that takes at least one volunteer willing to do it. .RTF may be another compromise option.

Hamish

ps- if someone could explain to me how to fix the hyperlinks in grass_description.odt I'd appreciate it. The ones in the .html version in svn are correct.

pps- QGIS installs the following 2 pdfs. Are they the most recent?

qgis-1.0.0_a-gentle-gis-introduction_en.pdf
qgis-1.3.0_user_guide_en.pdf

[jmays]

Replying to hamish:

ps- if someone could explain to me how to fix the hyperlinks in grass_description.odt I'd appreciate it. The ones in the .html version in svn are correct.

I applied the necessary changes for links in grass documentation in r3364.

[camerons]

There seems to be a glitch in abiword in the otd->html conversion process for hyperlinks.

​http://osgeo.org is converted (incorrectly) to something like ​file:///home/cshorter/trunk/doc/descriptions/http%3a//grass.osgeo.org

​http://osgeo.org/ is correctly converted to ​http://osgeo.org/

​http://osgeo.org/file.html is also correctly converted to ​http://osgeo.org/file.html

Solution:

• All domain names need to have either a trailing / or a /file or /dir/file

[camerons]

Further to my last comment, on looking at the html generated, I've discovered that

"​http://kettle.pentaho.org" is converted to "http%3akettle.pentaho.org"

I have now gone through and fixed all the .odt files to use correct link terms.

[pka]

rc5 (VM): spatialite and osgearth HTML documentation is now completely missing in /usr/local/share/livedvd-docs (Help link on desktop)

[wildintellect]

We should probably not keep a separate list that installs docs vs the list the installs apps. Note in main.sh that this is a TODO. This ticket should be resolved with changeset:3423