Hello, In case you didn't know, in RC4 there are lots of bad links like this:
file:///usr/.../live-dvd/docs/http://grass.osgeo.org instead of http://grass.osgeo.org Regards, Juan Lucas --- On Mon, 3/8/10, Cameron Shorter <[email protected]> wrote: > From: Cameron Shorter <[email protected]> > Subject: Re: [Live-demo] Documentation > To: "Hamish" <[email protected]> > Cc: [email protected] > Date: Monday, March 8, 2010, 9:50 PM > Hamish, > Some delayed responses to your thoughts below: > > Hamish wrote: > > Cameron wrote: > > > >> However, it seems that the formatting doesn't come > out very well. > >> This may need some tweaking. > >> > > > > > > Abiword is a neat tool*, but formatting issues are > fundamentally always going to > > be the case unless a structured document format is > used. Choice of traditional > > word processor isn't going to make any difference. > > > I agree, we do need to be strict about ensuring that the > template we use > focuses on content, not styling, and that styling is > applied after content. > > If you want an editor which does the right thing, but > is still somewhat familiar > > to openoffice/Words users, then LyX is it. > > > I would love to agree with you, and went as far as writing > a document > processing tool for docbook formatted documents > (http://generguide.sf.com) but later conceded that in > order to engage > the majority of users, you need to accept that 95% of users > use MS Word. > So we need to accept that people will create docs in MS > Word, and then > work out a processing chain for creating documentation from > MS Word. (I > think we can sometimes move people to Open Office from MS > Word, but > moving to LyX is too much of a jump). > > I should point out that we have huge potential to migrate > the greater > community to OSGeo if we can attract Educators to make use > of the > LiveDVD. Educators will write training material based upon > the LiveDVD > if we make it easy for them, and they are by and large > familar and > committed to MS Word. > > [*] tip o'the day: What abiword does for format > conversions on the command line, > > Inkscape also does for SVG to EPS graphics needs. very > handy! > > > > > > For a flat-ASCII format, upon reflection Mediawiki > markup will be a better choice > > than reStructured Text (which is nice, but perhaps > yet-another thing to learn). > > > I'm happy to encourage the use of MediaWiki for the > development of some > of the docs. In particular, the docs which will primarilly > be edited by > geeks. > > But what might work even better is the use of Google Docs > to develop our > word based docs. Advantages are: > * Docs can be downloaded as Open Office, Word, HTML or PDF > * Docs can be edited online in the familar Word like > format > * Images can be embedded > * Very low technical barrier of entry > * Google Docs tracks verion control for us > * We don't need to worry about taking up too much disk > space > > > Asking people to learn Wiki markup should not be so > great a request**, we could > > primarily use our mediawiki instance as the docs > home. Mediawiki allows > > Special:Export which outputs it as simple XML which > can then be fed to a wide > > assortment of filters to PDF, html, etc. Also, by > adding "&printable=yes" to the > > wiki page URL you get a "printer friendly" version > with the side panels etc > > stripped away; so in that way the install_docs.sh > script could pull the HTML > > version directly from the web. (as has already started > to happen) For offline > > users it would be nice to ship copies of the wiki "how > to install" pages on-disc > > too. > > > > printer friendly version example: > > > >http://wiki.osgeo.org/index.php?title=Live_GIS_Disc_Quick_Start&printable=yes > > > > I imagine there are some more simple wiki controls > lurking which will keep the > > hyperlinks unexpanded, etc., and just show the main > document frame in pretty- > > form. If not, we could write a HTML page template that > simply added a header > > and footer and floated a frame containing the > printable html version mid-page. > > > > > > as for mediawiki->PDF, well 178 hits, pick one: > > http://www.mediawiki.org/w/index.php?title=Special%3ASearch&search=pdf&go=Go > > > > this one in particular looks nice: > > http://www.mediawiki.org/wiki/Extension:PDF_Writer > > > > example output using Wikipedia's entry for "Solar > system": > > http://upload.wikimedia.org/wikipedia/commons/9/93/Solar_system_final.pdf > > > > > > > > [**] educators will have at least used wikipedia so it > shouldn't be that scary > > an interface for them. also as educators IMO they > should be willing to learn this > > tech so they can teach it/with it. it's not like we'd > be asking them to use vi. Wiki > > editing is a highly-reusable skill, and also adds to > our helper pool for the > > administrative wiki side of the project. ;) > > > > > > > >> Hamish raised concerns about storing binary files > in svn. > >> How serious is this concern. > >> > > > > - once something is checked into SVN, it never leaves. > So binary files which > > change frequently chew up vast amounts of SVN server > space even if the trunk > > file is not that big. Even minor typo fixes could mean > an entire new copy of > > the file needs to be permanently added to the DB. For > text files AFAIU > > internally it stores version diffs, and branches and > tag clones are entirely > > virtual. So SVN is highly efficient for text files, > but a bloated mess for > > binary files. > > Currently the .odt files are so tiny that the DB bloat > factor isn't an issue. > > Once annotated screenshots begin to be added to them > it gets bad though. > > > > - using binary files pretty much completely kills any > efficient peer review, > > which in turn also harms group collaboration. (typos, > bug fixes, minor updates, > > etc don't flow in from the casual bystanders checking > out the diffs in svn > > or the trac's timeline) > > > > > > > >> I think our primary requirement is that we make > documentation writing > >> (which includes images) easy to create, which > means we need to move > >> away from using HTML as our source format. > >> > > > > I am all for low barriers to entry, but I don't want > to believe that <b> > > for bold and <p> for paragraph break is really > that hard for the average > > voter to pick up. The trick is to just get people to > try :). IMO fear of > > the unknown is a bigger hurdle than the learning curve > in this situation. > > ... and of course the world would be a better place if > everyone went through > > the 15 minute LyX tutorial as it doesn't take long to > see how amazing it is. :-) > > > > > > but for today's vote wrt long-term strategy I'll get > behind Wikimedia + > > Extension:PDF_Writer and whatever > &printable=yes+frame, Htmlbook, or simple > > sed script brute-chop method gives us nice HTML. > > > > > > Hamish > > > > > > > > > > > > > -- > Cameron Shorter > Geospatial Solutions Manager > Tel: +61 (0)2 8570 5050 > Mob: +61 (0)419 142 254 > > Think Globally, Fix Locally > Geospatial Solutions enhanced with Open Standards and Open > Source > http://www.lisasoft.com > > _______________________________________________ > Live-demo mailing list > [email protected] > http://lists.osgeo.org/mailman/listinfo/live-demo > http://wiki.osgeo.org/wiki/Live_GIS_Disc > _______________________________________________ Live-demo mailing list [email protected] http://lists.osgeo.org/mailman/listinfo/live-demo http://wiki.osgeo.org/wiki/Live_GIS_Disc
