Opened 14 years ago

Closed 14 years ago

#537 closed defect (fixed)

Documentation not up-to-date

Reported by: pka Owned by: live-demo@…
Priority: critical Milestone:
Component: OSGeoLive Keywords: 3.0
Cc:

Description

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

Change history (11)

comment:1 by pka, 14 years ago

Keywords: 3.0 added
Priority: normalcritical

comment:2 by hamish, 14 years ago

Resolution: fixed
Status: newclosed

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

comment:3 by pka, 14 years ago

Resolution: fixed
Status: closedreopened

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.

comment:4 by camerons, 14 years ago

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)

comment:5 by camerons, 14 years ago

Resolution: fixed
Status: reopenedclosed

in reply to:  4 ; comment:6 by hamish, 14 years ago

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

in reply to:  6 comment:7 by jmays, 14 years ago

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.

comment:8 by camerons, 14 years ago

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

comment:9 by camerons, 14 years ago

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.

comment:10 by pka, 14 years ago

Resolution: fixed
Status: closedreopened

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

comment:11 by wildintellect, 14 years ago

Resolution: fixed
Status: reopenedclosed

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

Note: See TracTickets for help on using tickets.