Ubuntu: A Beginners Guide

[Thomas R. Jones]

On Wed, 2009-12-23 at 10:02 -0500, Kyle Nitzsche wrote:
> Hi Benjamin,
> 
> Instead of OpenOffice as the source format, you might consider 
> single-sourced docbook. When set up properly this allows:
> 
>  * true single sourcing (content is never duplicated, even for translations)
>  * easy localization (translations and images - for example screenshots)
>  * conversion to multiple localized output formats (html, pdf, docbook) 
> with a single command

Kyle et al

I was not aware of this doctemplate project and had been working on a
custom build toolkit based on the Novdoc system(Novell Documentation
Team) that I am familiar with. Thats what i get for not asking around i
suppose. :(

Have you considered implementing Docbook profiling in your project as
well as the transformations? This mechanism is a great addition for
standard documentation authors. It allows for contiguous Docbook
authoring of a topic for various skill levels. 

For instance, two paras can be authored. One for the "general public";
the other for "developers". A simple argument addition to the build
process and the resulting document is built for a specific type of user.

This allows the documentation to be easily tailored for a wide range of
users in a single source.

If you have not considered this mechanism; I would greatly encourage you
to research this functionality. I would be more than willing to help
with integration.

Cheers.
Thomas Jones
> 
> There's a project that makes all this easy: 
> http://launchpad.net/doctemplate.
> 
> That project has a PPA that allows you to install the doctemplate 
> package:  https://edge.launchpad.net/~doctemplate-team/+archive/ppa
> Just add that to your System > Administration > Software Sources then 
> install doctemplate with:
>  * "sudo apt-get update"
>  * "sudo apt-get install doctemplate"
> 
> Once doctemplate is installed:
>  * you create a new docbook article or book in the current directory 
> with a single command ("doctemplate_setup_article" or 
> "doctemplate_setup_book")
>  * docbook content that is ready to edit, modify and build is created
>  * you generate localized pdf, html, docbook, with a single command 
> ("make_pdf" "make_html" "make_docbook")
>  * translations are in po files that can be updated from source with a 
> single command, and localized outputs always use the po files. po files 
> can be translated in Launchpad or using many other  available  
> tools/websites.
> 
> The guiding design/development principle for doctemplate is: make it 
> easy for writers to write by handling the techy bits.
> 
> Docbook does have a handful of tags the writer needs to know. They are 
> well-documented on the web, for example: 
> http://www.docbook.org/tdg/en/html/article.html.
> 
> You can edit the docbook files in various applications, including text 
> editors like gedit. The bluefish package provides some pretty good 
> docbook specific functions.
> 
> I am currently finalizing the short documentation for doctemplate: 
> https://edge.launchpad.net/doctemplate-user-guide
> 
> Get the docs this way:
> (you have to have the "bzr" package installed.)
> 
> 'bzr branch lp:doctemplate-user-guide"
> 
> Then, in the root directory, run "./make_html"
> 
> Then display the English version with: "firefox build/html/en/index.html"
> 
> (or, to make a pdf, run "./make_pdf" and display it with "evince 
> build/pdf/en/doctemplate-doc.pdf".)
> 
> (or to make localized docbook, run "./make_docbook" and display it in 
> yelp with "yelp build/xml/en/doctemplate-doc.xml")
> 
> (The doctemplate-user-guide is also written using the doctemplate approach.)
>  
> Cheers,
> Kyle
> 
> 
> 
> 
> 
> Benjamin Humphrey wrote:
> > Hello everyone,
> >
> > Recently I started up a project to write a manual for Ubuntu that is 
> > both informative and easy to follow. My goal is around 50-75 pages, 
> > and perhaps having two different versions - one in-depth guide that 
> > covers pretty much everything, and one 10 page Quick Start guide, 
> > which, in the future, could be shipped with the Ubuntu CDs.
> >
> > I began writing it myself, but after deliberation and advice from 
> > other users, it would be better to make it a community effort. The 
> > idea is to have the first release ready for Lucid, and then a refresh 
> > every 6 months to coincide with a new Ubuntu version. Eventually, I 
> > hope it becomes the first point of reference for any Ubuntu newcomers.
> >
> > We need contributors, and I thought the best place to start would be 
> > the documentation team.
> >
> > I was talking with Jono Bacon tonight and he suggested the ideal way 
> > to go about testing/feedback/contributions for the manual is via 
> > Launchpad. He is really excited about the idea and is interested to 
> > see how it pans out – so am I.
> >
> > Therefore, I’ve just created a Launchpad team for the Beginners Manual:
> >
> > https://launchpad.net/~ubuntu-manual 
> > <https://launchpad.net/%7Eubuntu-manual>
> >
> > I’ll set up a bzr tomorrow and upload the .odt and .pdf of what I have 
> > so far (about 3 rough chapters), feel free to download it and start 
> > contributing. Perhaps the best way to do it would be to pick a chapter 
> > that you feel confident in and write something on it – doesn’t have to 
> > be big, just a rough draft and I can add extra stuff when I get there.
> >
> > I will also try to be on #ubuntu-doc tomorrow for any questions.
> >
> >
> > If anyone knows anything about LaTeX could they let me know too.
> >
> > --
> > Regards,
> >
> > Benjamin Humphrey
> > humphreybc
> >
> > humphreybc at gmail.com <mailto:humphreybc at gmail.com>
> > www.interesting.co.nz <http://www.interesting.co.nz>
> > www.benjaminhumphreyphotography.com 
> > <http://www.benjaminhumphreyphotography.com>
> >
> 
>