[Live-demo] Documentation

[Cameron Shorter]

I've gone through and fixed the .odt docs again (had formatting errors 
on most).
The CSS formatting is still really bad, but we have enough content for 
Alex to start the 3.0rc3 build in 8 hours or so.

Hamish, you have raised points in an email which I'd like to address in 
more detail that I can address before I go to bed tonight.

Alex Mandel wrote:
> I'm really confused. I just opened some of those odt files that are in
> svn and they simply contain html text. I fail to see the advantage over
> regular html. This actually just seems to add a layer of complexity and
> obscurity. Did I miss something?
>
> I vote for 1 screenshot max, and project logo. If projects want more
> documentation than that they are welcome to bundle it in their install
> script in html or pdf and link to it from the general docs page.
>
> Alex
>
> Cameron Shorter wrote:
>   
>> Ok,
>> I'm getting very excited by the power of abiword to automatically
>> convert docs.
>>
>> * The document build process now creates HTML documentation from ODF for
>> all package description files.
>> * I have also converted all doc/xxx_description.html files to
>> doc/xxx_description.odt
>> * So from now on, we can create our documentation using Open Office (or
>> abiword), and we can now include images in the documentation.
>>
>> Gaby, Juan, and others,
>> What level of documentation enhancements would you like to add?
>> Options I see are:
>> 1. Add 1 screen snapshot for each application.
>>
>> 2. Add a series of screen snapshots showing how to run the application.
>> (This will take time to do for all 35 applications, but if someone has
>> the time to create these docs this coming week, then it would be an
>> excellent addition to the DVD)
>>
>>
>>
>> Cameron Shorter wrote:
>>     
>>> We hope to convert all docs to ODT for 3.0, but are not sure we will
>>> have time to get it all converted in time. Maybe you could help.
>>>
>>> Gaby, do you have a template that Juan could use?
>>>
>>> Juan, for the moment, if you are helping, just copy HTML text word for
>>> word into ODT format. Do not apply any fancy style information like
>>> changing font size, just use standard heading, italic structures etc.
>>> (Same as the HTML)
>>>
>>> for filenames, use the same naming convention as before,
>>> Eg, for mapserver, copy:
>>> https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk/doc/descriptions/mapserver_description.html
>>>
>>> to
>>> https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk/doc/descriptions/mapserver_description.odt
>>>
>>>
>>> We can change all the files automatically using:
>>> abiword --to odt mapserver_description.html
>>>
>>> However, it seems that the formatting doesn't come out very well. This
>>> may need some tweaking.
>>>
>>> Hamish raised concerns about storing binary files in svn.
>>> How serious is this concern.
>>> 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.
>>>
>>>       
>>     
>
> _______________________________________________
> 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