[Live-demo] Documentation
Cameron Shorter
cameron.shorter at gmail.com
Fri Mar 5 10:01:44 PST 2010
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.
Juan Lucas Domínguez Rubio wrote:
> Hello,
>
> If I understood it well, you are going to make the HTML files look homogeneous without using any ODT files this time (Arramagong v3), and then prepare ODT files and some automatic conversion to HTML for Arramagong v4. Is that correct?
>
> Do you have any HTML or ODT templates?
>
> Regards,
> Juan Lucas
>
>
> --- On Fri, 3/5/10, Gaby Van Wyk <gvanwyk at openspatial.com.au> wrote:
>
>
>> From: Gaby Van Wyk <gvanwyk at openspatial.com.au>
>> Subject: RE: [Live-demo] FW: IRC meeting to discuss RC3 and final releases of the liveDVD
>> To: "Juan Lucas Domínguez Rubio" <juan_lucas_dr at yahoo.com>
>> Cc: "Cameron Shorter" <cameron.shorter at gmail.com>
>> Date: Friday, March 5, 2010, 3:38 AM
>> Hi Juan
>>
>> The idea is to try and move content around, make sure that
>> all the same type of content is available in all documents
>> at roughly the same place. I will also edit the documents
>> for language and that type of thing. Make it look like it
>> was written by the same person, almost. Will work closely
>> with the document owners, but we want to try and make it
>> familiar across the different packages. If something is
>> missing, I will liaise with the group to get that
>> information.
>>
>> The final result will remain HTML.
>>
>> I agree with your comment on images / diagrams, and I know
>> it will be ok if you added some. (Cameron - your comment
>> please...) I guess links to PDF's are OK, but long
>> term, my preference would be not to include PDF.
>>
>> Hope that answers your question.
>>
>> Gaby VanWyk
>> -----Original Message-----
>> From: Juan Lucas Domínguez Rubio [mailto:juan_lucas_dr at yahoo.com]
>>
>> Sent: Thursday, 4 March 2010 2:49 AM
>> To: live-demo at lists.osgeo.org;
>> Gaby Van Wyk
>> Subject: Re: [Live-demo] FW: IRC meeting to discuss RC3 and
>> final releases of the liveDVD
>>
>> Hello, Gaby:
>>
>> I don't understand very well what you intend to do. Have
>> you seen the current state of the docs in Arramagong v3 RC2?
>> The sh scripts automatically create an index (definitions)
>> that lets the user see the descriptions. All in HTML and
>> reasonagly homogeneous, though perhaps incomplete.
>>
>> Do you mean you are going to add the descriptions of
>> packages that have not added it yet?
>>
>> Which output format are you going to use?
>>
>> Is it a problem to have some PDF in the folder
>> /usr/local/share/package and add a hyperlink to it from the
>> package description? The OSGeo wiki says we should not add
>> images in the description, but if we are talking about GIS
>> software, I think hyperlinks to colorful PDFs must be
>> allowed, no?
>>
>>
>> Regards
>> Juan Lucas
>>
>>
>>
>> --- On Wed, 3/3/10, Gaby Van Wyk <gvanwyk at openspatial.com.au>
>> wrote:
>>
>>
>>> From: Gaby Van Wyk <gvanwyk at openspatial.com.au>
>>> Subject: [Live-demo] FW: IRC meeting to discuss RC3
>>>
>> and final releases of the liveDVD
>>
>>> To: "live-demo at lists.osgeo.org"
>>>
>> <live-demo at lists.osgeo.org>
>>
>>> Date: Wednesday, March 3, 2010, 6:56 AM
>>> Hi All
>>>
>>> In a discussion with Cameron (see e-mail trail below)
>>>
>> I
>>
>>> have volunteered to get all of the documentation
>>>
>> currently
>>
>>> available for each of the projects under the live DVD
>>>
>> into a
>>
>>> similar structure and style. This time around this
>>>
>> will be a
>>
>>> manual process, but hopefully we can automate this in
>>> future.
>>>
>>> I would appreciate any comments, tips or other ideas.
>>>
>> If
>>
>>> any of the documentation needs updating first, please
>>>
>> let me
>>
>>> know so I can leave those for last.
>>>
>>> Regards
>>>
>>> Gaby van Wyk
>>>
>>> -----Original Message-----
>>> From: Cameron Shorter [mailto:cameron.shorter at gmail.com]
>>> Sent: Wednesday, 3 March 2010 2:10 PM
>>> To: Gaby Van Wyk
>>> Subject: Re: IRC meeting to discuss RC3 and final
>>>
>> releases
>>
>>> of the liveDVD
>>>
>>> Gaby, nice talk with you and thank you for
>>>
>> volunteering to
>>
>>> look into the documentation for the LiveDVD.
>>>
>>> As promised, here are details for updating
>>>
>> documentation on
>>
>>> the liveDVD.
>>>
>>> 0. Please email the live dvd list, live-demo at lists.osgeo.org,
>>> letting people know about your intentions. You are
>>>
>> welcome
>>
>>> to forward this email if you like.
>>>
>>> 1. We have asked package maintainers to create
>>> documentation for their projects according to this
>>>
>> wiki
>>
>>> page:
>>> http://wiki.osgeo.org/wiki/Live_GIS_Build#Writing_docs
>>> Once you are complete, you will likely want to change
>>>
>> this
>>
>>> process This section also notes where you will need
>>>
>> to
>>
>>> access the description files to update.
>>>
>>> 2. The script which installs the docs onto the LiveDVD
>>>
>> is
>>
>>> at:
>>> https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk/bin/install_main_docs.sh
>>>
>>> 3. Attached is material which could be used as a basis
>>>
>> for
>>
>>> your final introductory text.
>>>
>>> 4. In order to commit your changes back into
>>>
>> subversion,
>>
>>> you will need to create an osgeo user id for yourself,
>>>
>> then
>>
>>> tell me so that I can grant you svn permission, as
>>>
>> per:
>>
>>> http://wiki.osgeo.org/wiki/Live_GIS_Disc#OSGeo_User_Id
>>>
>>> Good luck. Let me know how you are progressing.
>>>
>>> Gaby Van Wyk wrote:
>>>
>>>> Hi Cameron
>>>>
>>>> Yes I am willing to take that on.
>>>>
>>>> Ideally it would be nice to provide an
>>>>
>> application
>>
>>> that will guide people through the creation of
>>> documentation, people can concentrate of creating
>>>
>> content,
>>
>>> style will be automated afterwards. I realise that we
>>>
>> do not
>>
>>> have the time for the creation of such an application,
>>>
>> but I
>>
>>> will try to establish a document framework and an
>>>
>> Open
>>
>>> Office Template (OTT) with some guidelines. Is that
>>>
>> OK?
>>
>>>> For the future, would it be possible to find
>>>>
>> some
>>
>>> space on the OSGeo server to host an application that
>>>
>> can be
>>
>>> used for collaborated development?
>>>
>>>> Gaby
>>>>
>>>> -----Original Message-----
>>>> From: Cameron Shorter [mailto:cameron.shorter at gmail.com]
>>>> Sent: Wednesday, 3 March 2010 7:02 AM
>>>> To: Gaby Van Wyk
>>>> Subject: Re: IRC meeting to discuss RC3 and
>>>>
>> final
>>
>>> releases of the
>>>
>>>> liveDVD
>>>>
>>>> Gaby,
>>>> I wonder whether you would like to take on the
>>>>
>> task of
>>
>>> making the
>>>
>>>> LiveDVD documentation consistent between
>>>>
>> projects, and
>>
>>> any other
>>>
>>>> issues you think should be addresses, as per
>>>>
>> agenda
>>
>>> item in the
>>>
>>>> meeting this Friday morning (6am).
>>>>
>>>> Cameron Shorter wrote:
>>>>
>>>>
>>>>> I suggest we have a meeting this Th/Fr to
>>>>>
>> discuss
>>
>>> outstanding issues
>>>
>>>>> on the LiveDVD, as per wiki page below.
>>>>>
>>>>> Feel free to add items to the agenda
>>>>>
>>>>> http://wiki.osgeo.org/wiki/Live_GIS_Disc_Meeting_Minutes#Th.2FFr_4_Ma
>>>>> r_2010
>>>>>
>>>>>
>>>>> Time:
>>>>> http://timeanddate.com/worldclock/meetingdetails.html?year=2010&month
>>>>>
>>>>>
>> =3&day=4&hour=19&min=0&sec=0&p1=22&p2=240&p3=195&p4=179&p5=137
>>
>>>>> <http://timeanddate.com/worldclock/meetingdetails.html?year=2010&mont
>>>>>
>>>>>
>> h=3&day=4&hour=19&min=0&sec=0&p1=22&p2=240&p3=195&p4=179&p5=137>
>>
>>>>> Location: irc://freenode.net#foss4g
>>>>>
>>>>> Background:
>>>>>
>>>>> * According to our schedule, we are a
>>>>>
>>> few days late for our RC3
>>>
>>>>> release. I hope that we can
>>>>>
>>> the next release out this weekend,
>>>
>>>>>
>>>>> http://spreadsheets.google.com/ccc?key=0Al9zh8DjmU_RdE1SYUN3YWJ2N1NpS
>>>>> UczbW9IRWZNclE&hl=en_GB
>>>>>
>>>>>
>>>>> <http://spreadsheets.google.com/ccc?key=0Al9zh8DjmU_RdE1SYUN3YWJ2N1Np
>>>>> SUczbW9IRWZNclE&hl=en_GB>
>>>>>
>>>>>
>>>>> * And we have 12 days till the final
>>>>>
>>> release.
>>>
>>>>> * This meeting is to set out our plan
>>>>>
>>> for getting this final release
>>>
>>>>> out the door.
>>>>>
>>>>> Agenda:
>>>>>
>>>>> * Planning and documenting testing,
>>>>>
>>> as per: [Live_GIS_Disc_Testing].
>>>
>>>>> I want to have a brief test
>>>>>
>>> description for every package, and
>>>
>>>>> then track that someone has
>>>>>
>>> tested every application.
>>>
>>>>> * Decide on background image
>>>>> * Decide on menu structure, (can we
>>>>>
>>> loose the icons from the desktop?)
>>>
>>>>> * From the next release, we
>>>>>
>>> need to test creating an ISO image. Do
>>>
>>>>> we have a volunteer?
>>>>> * Documentation: I'd love it if
>>>>>
>>> someone could go through all
>>>
>>>>> documentation and make it
>>>>>
>>> consistent (without changing any
>>>
>>>>> content). If we are really
>>>>>
>>> keen, it would be good if someone could
>>>
>>>>> incorporate Jody's OpenOffice
>>>>>
>>> overview of each package, and
>>>
>>>>> incorporate this into the
>>>>>
>>> documentation build. Jody has documented
>>>
>>>>> how to start up and run most
>>>>>
>>> of the packages, using screen
>>>
>>>>> snapshots and all. I've worked
>>>>>
>>> out how we can convert these docs
>>>
>>>>> into HTML from an install
>>>>>
>>> script using abiword. If we haven't got
>>>
>>>>> time for this, it will need to
>>>>>
>>> wait until the next release.
>>>
>>>>>
>>>>>
>>>>
>>>>
>>> --
>>> 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 Osgeolive
mailing list