[Live-demo] Documentation
Cameron Shorter
cameron.shorter at gmail.com
Thu Mar 11 12:05:27 PST 2010
The conversion process uses abiword, so I suggest you do steps below for
one package, with either Open Office or AbiWord, then try the conversion
process with abiword and verify it works, then repeat for the rest of
the docs with a problem. You can test using the following:
abiword --to x.html ossim_description.odt
Juan Lucas Domínguez Rubio wrote:
> 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
>>
>>
>>
>
>
>
>
--
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 Osgeolive
mailing list