[Journal] My Thoughts On An OSGeo Documentation Tool Chain
(Long Message)
Dan Putler
dan.putler at sauder.ubc.ca
Fri Jun 27 14:28:17 EDT 2008
Has anyone looked at OSGeo journal/document preparation using LyX rather
than dealing with the straight LaTeX? This would give ease of use very
similar to a word processor (OO.o or MS Word?), but with the power and
portability of LaTeX.
Dan
On Fri, 2008-06-27 at 11:05 -0700, Sunburned Surveyor wrote:
> I want to share some of my thoughts about OSGeo the process and
> formats we will use for OSGeo documentation. This includes OSGeo
> educational material, but a lot of it might also apply to the OSGeo
> Journal.
>
> Disclaimer: I am not a desktop publishing expert, nor am I a
> professional author. I don't intend to speak as an authority on this
> matter, but hope to offer some modest opinions and suggestions. I'm
> approaching this from the perspective of a new author that would like
> to be involved in the production of OSGeo documentation.
>
> It looks like there are three (3) main "tool chains" to produce and
> manage technical documentation. There's the word processor tool chain,
> the LaTex tool chain, and professional desktop publishing tool chain.
> Let me share with you my thoughts on the advantages and disadvantages
> of each, and then I'll make a suggestion on how to move forward.
>
>
> Word Processor Tool Chain Advantages:
> Familiar to most authors.
> Easy styling.
> Comes with spell check. :]
> Export to PDF typically supported.
>
> Word Processor Tool Chain Disadvantages:
> Limited control of layout.
> Layout of graphics can be awkward.
> Limited support for mathematical formulas.
> Mixes style and content.
> Not exactly easy to search and index.
> Export to other formats is limited.
>
> LaTex Processor Tool Chain Advantages:
> Familiar authors in the science and academic communities.
> Great support for mathematical formulas.
> Automated PDF generation.
> Export to other formats is supported.
>
> LaTex Processor Tool Chain Disadvantages:
> The learning curve is very steep.
> Freely available training material for authors is limited.
> Installation of a complete LaTex system is a major chore.
> Mixes style and content.
> Not exactly easy to search and index.
>
> Docbook Tool Chain Advantages:
> Supported by existing XML tools.
> Easy to search and index.
> Format is extendable and can be customized for OSGeo needs without
> much effort.
> Easy to learn. (I got up and running with Docbook in about a day.)
> Clear separation of content and style.
>
> Docbook Tool Chain Disadvantages
> Requires the end-user know XSLT or CSS to produce documentation in
> a "human friendly" form.
> No open source Docbook specific editor. (XML editors could be used.)
>
> Professional Desktop Publishing Tool Chain Advantages:
> Great control over layout, document appearance, and inclusion of graphics.
> Production of "professional" and user friendly documents possible.
> Easy to learn.
> Supported by user-friendly open source tools.
>
> Professional Desktop Publishing Tool Chain Disadvantages:
> Limited support for mathematical formulas.
> Mixes style and content.
> Not exactly easy to search and index.
> Export to other formats is limited.
>
> I believe our choice of tool chain (or tool chains) will really depend
> on our goals.
>
> If we want to produce professional and user-friendly documents
> suitable for printing and offline viewing then the desktop publishing
> tool chain would likely be the best choice.
>
> If we want to produce documentation that can be easily searched and
> cataloged, and also used to produce online documentation for a serious
> web presence, then I think Docbook would likely be the best choice.
>
> If we want to embrace authors from the science or academic communities
> then LaTex seems to be the logical choice.
>
> If we want ultimate ease of use for new authors, a word processor is a
> good option.
>
> What is our goal with OSGeo documentation? Do we have a different goal
> for the Journal and the education material?
>
> There are tool chain combinations that would also work well. For
> example, you could have most authors work in their favorite word
> processor and then have a dedicated team of OSGeo volunteers that
> cataloged the documentation and converted it to LaTex, Docbook, or PDF
> using one of the other tool chains.
>
> I'd personally like to see us explore the use of Docbook as our main
> input format. I've been really impressed with what it can do.
>
> I could write a simple GUI that used something like JDOM to convert
> Docbook to HTML. We could then come up with a CSS file to support a
> professional and "OSGeo" branded HTML layout. We could have one for
> use online, allowing a great Journal web presence, and one for
> printing. Once it was set in place, I think this system would work
> well.
>
> I must admit that I have been really frustrated with LaTex, and I
> don't plan on investing the resources needed to learn it. That doesn't
> mean that we shouldn't use it as a group. If we do use it as our main
> tool chain, we should consider what framework we will use to support
> "non-latex" authors.
>
> I know I've likely opened a can of worms, but I hope the discussion
> will help move us forward. I'm willing to begin work on a Docbook tool
> chain for OSGeo immediately if that is how we decide to move forward.
>
> I'd also like to know what we might be doing in the area of search and
> catalogs for OSGeo material and web presence. Perhaps we set up some
> informal teams to tackle these two (2) issues and explore solutions?
>
> I know that most major newspapers and magazines are concentrating on a
> heavy web presence. I think it makes sense to do so for the OSGeo
> Journal, and I think a Docbook tool chain could help get us there.
>
> I look forward to hearing other's comments.
>
> Landon
> _______________________________________________
> newsletter mailing list
> newsletter at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/newsletter
--
Dan Putler
Sauder School of Business
University of British Columbia
More information about the newsletter
mailing list