[Live-demo] Documentation

Juan Lucas Domínguez Rubio juan_lucas_dr at yahoo.com
Thu Mar 11 07:15:39 EST 2010


Ok,
Is it enough with this?

- open the ODT with OpenOffice
- Select the link and click on the add/edit link button
- fix the target URL
- save file

Is there any special thing we should do so that the ODT->HTML converter works? Which version of OpenOffice should we use?

Regards,


--- On Thu, 3/11/10, Cameron Shorter <cameron.shorter at gmail.com> wrote:

> From: Cameron Shorter <cameron.shorter at gmail.com>
> Subject: Re: [Live-demo] Documentation
> To: "Juan Lucas Domínguez Rubio" <juan_lucas_dr at yahoo.com>
> Cc: "Hamish" <hamish_b at yahoo.com>, live-demo at lists.osgeo.org
> Date: Thursday, March 11, 2010, 12:41 PM
> Juan,
> Yes you are right. It seems that some of the .odt files
> were created with correct links and some without.
> 
> Feel free to correct the links if you have time.
> To check to see if you have made link updates correctly,
> you can run:
> bin/install_main_docs.sh
> 
> Juan Lucas Domínguez Rubio wrote:
> > 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 <cameron.shorter at gmail.com>
> wrote:
> > 
> >   
> >> From: Cameron Shorter <cameron.shorter at gmail.com>
> >> Subject: Re: [Live-demo] Documentation
> >> To: "Hamish" <hamish_b at yahoo.com>
> >> Cc: live-demo at lists.osgeo.org
> >> 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
> >> Live-demo at lists.osgeo.org
> >> http://lists.osgeo.org/mailman/listinfo/live-demo
> >> http://wiki.osgeo.org/wiki/Live_GIS_Disc
> >> 
> >>     
> > 
> > 
> >         
> 
> 
> -- Cameron Shorter
> Geospatial Systems Architect
> 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
> 
> 


      


More information about the Live-demo mailing list