Re: [OSGeo-Discuss] Help authoring tools
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 El 01/06/10 19:00, Daniel Ames escribió: Do any of you have a preferred open source help authoring tool? We're looking for something to document our projects on web pages - something better than wiki - and also to download and install with software. Must be cross platform, etc. I'd like to use whatever others are using in the OSGeo community for consistency... - Dan At gvSIG project we use Plone CMS and restructured text markup at gvsig.org I agree with others that sphinx is a nice environment to build but well, we use our Plone instance for more things than documenting: we have a contrib section[1], a huge group of people translating not only the website (manuals, courses, etc) but also the gvSIG GUI (Desktop and Mobile) using a new plone plugin we promoted[2], working groups management, our events[3], etc. etc. rst is a nice markup and I use it everyday with gnome text editor (gedit). There are some plugins to help editing rst, do fast previews, etc. Anyway I would recommend also to follow the other people recommendation about using sphinx, our plone instance requires to have a very skilled people and sphinx is more easy to deploy and maintain. Cheers [1] https://gvsig.org/plugins/downloads [2] http://forge.osor.eu/projects/gvsig-i18n/ [3] https://gvsig.org/web/home/community/events - -- Jorge Gaspar Sanz Salinas Ingeniero en Geodesia y Cartografía http://es.osgeo.org http://jorgesanz.net -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQEcBAEBAgAGBQJMBgWbAAoJEAOYD75lvHdBFGEIAI74vFA+dqd72GeA6+r8uKuT CXRPOklFQTy6Wn/KsR6kNuWILbm1K7hzKiV4giEcyrahZZKLElPqq47DF6/uo0rS uL4blK8fU7S13ak5anGtCytTYefgHth9TQMYomzp59rEmbmT7d4CXbi86PWKxpRI kkvYjJwgRDo3stEMcTAB1Dq2i8iFQswg4i5FoT4su27mPv+zNKvxMNzSNFXBBLeg JGZqZosRlILFse0Rshr8eMX9OsdwXHn6NXqbzBFzue3ClNQ6C3gH6rjD9XKF0hFD 6+N+yLwGJZmwZMjFWBy13SQ9lCQRNbid82DHUWhrydSOLSkNhSP45UextGgAnGM= =AwhV -END PGP SIGNATURE- ___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss
Re: [OSGeo-Discuss] Help authoring tools
For docbook WYSIWYG editing, I highly recommend the free version of XmlEditor from http://www.xmlmind.com/xmleditor/ It makes docbook almost as easy to edit as a word document, with the advantage of having structured docbook as a result. However, much as I love docbook as a format, it has limited market share and hence authors are less likely to want to write documents using it. Consequently I would advise against using docbook. On 02/06/10 05:28, Paul Ramsey wrote: PostGIS is docbook, a decision from Way Back. Docbook has served us well, and in particular has provided some unexpected benefits, in that the detailed markup have allowed documentation-driven test frameworks to be built (we can actually automatically test every documented function). That said, if I were making the decision again today I'd use RST and Sphinx, for the attractiveness of output and the human-readability of the documentation source. It's easier to update the documentation at source when you can easily visually scan it. I found I couldn't write large chunks of docbook without using a WYSIWYG editor like (now defunct) XMetaL. P. On Tue, Jun 1, 2010 at 2:15 PM, Howard Butlerhobu@gmail.com wrote: On Jun 1, 2010, at 12:34 PM, Stefan Steiniger wrote: On 06/01/2010 10:00 AM, Daniel Ames wrote: Do any of you have a preferred open source help authoring tool? We're looking for something to document our projects on web pages - something better than wiki - and also to download and install with software. Must be cross platform, etc. I'd like to use whatever others are using in the OSGeo community for consistency... - Dan Daniel, MapServer, GeoTools, OpenLayers, GeoServer, Shapely, libLAS, and GeoDjango all use Sphinxhttp://sphinx.pocoo.org/. In my opinion, Sphinx's great advantages in order of importance are: - text-like markup (docbook is too much burden on documentation writers). Restructured text is not too difficult to learn, but I wish the world would agree on a text-like markup (markdown, restructured text, wikitext, etc) - variety of output. Besides html, you can do ePub, PDF (multiple ways -- via latex or stand alone), windows compiled help, qthelp, man - pretty output - simple installation and management I know there are some sphinx skeptics from the MapServer project on this list who might chime up one way or another about its level of success within the MapServer project, but I think its implementation has help our project immensely. GDAL is still using Doxygen for its documentation generation. Howard___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss ___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss -- Cameron Shorter Geospatial Director 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 ___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss
[OSGeo-Discuss] Help authoring tools
Do any of you have a preferred open source help authoring tool? We're looking for something to document our projects on web pages - something better than wiki - and also to download and install with software. Must be cross platform, etc. I'd like to use whatever others are using in the OSGeo community for consistency... - Dan -- Daniel P. Ames, Ph.D. PE Associate Professor, Geosciences Idaho State University - Idaho Falls amesd...@isu.edu geology.isu.edu www.mapwindow.org * See you at IEMSS 2010: http://www.iemss.org/iemss2010/ * ___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss
Re: [OSGeo-Discuss] Help authoring tools
Hi Dan, PAGC has its documentation written in text files with markdown markup, which is then converted into various formats (html and PDF via LaTeX in particular) using pandoc: http://johnmacfarlane.net/pandoc/ I know gdal uses restructured text in a similar way. Dan On 06/01/2010 10:00 AM, Daniel Ames wrote: Do any of you have a preferred open source help authoring tool? We're looking for something to document our projects on web pages - something better than wiki - and also to download and install with software. Must be cross platform, etc. I'd like to use whatever others are using in the OSGeo community for consistency... - Dan -- Daniel P. Ames, Ph.D. PE Associate Professor, Geosciences Idaho State University - Idaho Falls amesd...@isu.edu mailto:amesd...@isu.edu geology.isu.edu http://geology.isu.edu www.mapwindow.org http://www.mapwindow.org * See you at IEMSS 2010: http://www.iemss.org/iemss2010/ * ___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss
Re: [OSGeo-Discuss] Help authoring tools
Hei, I would like to know some tools too that are used by others. As OpenJUMP is also lacking a help system (still...). Things that heard of are: - docbook - elml.ch (though not thought for documentation directly but it exports to several formats: pdf/html as it is xml based) - the Sextante built-in help, which is html based too (not sure how much it is tied to java and how easy it is too maintain, but it is a good start). So Daniel A. if you found something useful, pls. let me/us know. Though - you may have different options with .Net stefan Dan Putler wrote: Hi Dan, PAGC has its documentation written in text files with markdown markup, which is then converted into various formats (html and PDF via LaTeX in particular) using pandoc: http://johnmacfarlane.net/pandoc/ I know gdal uses restructured text in a similar way. Dan On 06/01/2010 10:00 AM, Daniel Ames wrote: Do any of you have a preferred open source help authoring tool? We're looking for something to document our projects on web pages - something better than wiki - and also to download and install with software. Must be cross platform, etc. I'd like to use whatever others are using in the OSGeo community for consistency... - Dan -- Daniel P. Ames, Ph.D. PE Associate Professor, Geosciences Idaho State University - Idaho Falls amesd...@isu.edu mailto:amesd...@isu.edu geology.isu.edu http://geology.isu.edu www.mapwindow.org http://www.mapwindow.org * See you at IEMSS 2010: http://www.iemss.org/iemss2010/ * ___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss ___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss
Re: [OSGeo-Discuss] Help authoring tools
On Jun 1, 2010, at 12:34 PM, Stefan Steiniger wrote: On 06/01/2010 10:00 AM, Daniel Ames wrote: Do any of you have a preferred open source help authoring tool? We're looking for something to document our projects on web pages - something better than wiki - and also to download and install with software. Must be cross platform, etc. I'd like to use whatever others are using in the OSGeo community for consistency... - Dan Daniel, MapServer, GeoTools, OpenLayers, GeoServer, Shapely, libLAS, and GeoDjango all use Sphinx http://sphinx.pocoo.org/. In my opinion, Sphinx's great advantages in order of importance are: - text-like markup (docbook is too much burden on documentation writers). Restructured text is not too difficult to learn, but I wish the world would agree on a text-like markup (markdown, restructured text, wikitext, etc) - variety of output. Besides html, you can do ePub, PDF (multiple ways -- via latex or stand alone), windows compiled help, qthelp, man - pretty output - simple installation and management I know there are some sphinx skeptics from the MapServer project on this list who might chime up one way or another about its level of success within the MapServer project, but I think its implementation has help our project immensely. GDAL is still using Doxygen for its documentation generation. Howard___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss
Re: [OSGeo-Discuss] Help authoring tools
PostGIS is docbook, a decision from Way Back. Docbook has served us well, and in particular has provided some unexpected benefits, in that the detailed markup have allowed documentation-driven test frameworks to be built (we can actually automatically test every documented function). That said, if I were making the decision again today I'd use RST and Sphinx, for the attractiveness of output and the human-readability of the documentation source. It's easier to update the documentation at source when you can easily visually scan it. I found I couldn't write large chunks of docbook without using a WYSIWYG editor like (now defunct) XMetaL. P. On Tue, Jun 1, 2010 at 2:15 PM, Howard Butler hobu@gmail.com wrote: On Jun 1, 2010, at 12:34 PM, Stefan Steiniger wrote: On 06/01/2010 10:00 AM, Daniel Ames wrote: Do any of you have a preferred open source help authoring tool? We're looking for something to document our projects on web pages - something better than wiki - and also to download and install with software. Must be cross platform, etc. I'd like to use whatever others are using in the OSGeo community for consistency... - Dan Daniel, MapServer, GeoTools, OpenLayers, GeoServer, Shapely, libLAS, and GeoDjango all use Sphinx http://sphinx.pocoo.org/. In my opinion, Sphinx's great advantages in order of importance are: - text-like markup (docbook is too much burden on documentation writers). Restructured text is not too difficult to learn, but I wish the world would agree on a text-like markup (markdown, restructured text, wikitext, etc) - variety of output. Besides html, you can do ePub, PDF (multiple ways -- via latex or stand alone), windows compiled help, qthelp, man - pretty output - simple installation and management I know there are some sphinx skeptics from the MapServer project on this list who might chime up one way or another about its level of success within the MapServer project, but I think its implementation has help our project immensely. GDAL is still using Doxygen for its documentation generation. Howard___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss ___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss
[OSGeo-Discuss] Help authoring tools (John Lindsay)
Hi Dan, For the Whitebox GAT project, I've been using html with ccs for formating and create the help files in Komodo Edit. It's quite a simple approach but find that I can create quite nice help entries in this way. I can embed graphics, equations, links to other help entries, etc. Using ccs allows me to make style changes quickly. The other nice thing about this approach is that I can very easily embed the help entry for each tool in the tool's dialog box, so the user has no excuse for not reading the help! I can also use the same files for the online version of Whitebox's help (http://www.uoguelph.ca/~hydrogeo/Whitebox/Help/MainHelp.html). Perhaps there are better solutions (with dedicated help creation programs) but this is the solution that seems to work best for me. John Lindsay, Ph.D., Assistant Professor Dept. of Geography, Univ. of Guelph Guelph, Ont. N1G 2W1 CANADA Phone: (519) 824-4120 x56074 Fax: (519) 837-2940 Email: jlind...@uoguelph.ca Department Web: www.uoguelph.ca/geography/ Personal Web: http://www.uoguelph.ca/geography/faculty/lindsay.html ___ Discuss mailing list Discuss@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/discuss
