[Live-demo] Documentation

[Alex Mandel]

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.
>>
> 
>