Ubuntu: A Beginners Guide

[Kyle Nitzsche]

Thomas R. Jones wrote:
> 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.
>   
Thank you for pointing this out. It looks straightforward to implement. 
Perhaps I'll have time to look at this over the holidays.
 
(Naturally, this sort of thing is supported intrinsically through the 
xml/xslt framework (transform an xml file to include just the bits you 
want...) But I see that docbook provides a standardized approach (using 
attributes and corresponding xslt params/sheets) that covers a 
reasonable range of useful profiles/conditions: arch audience condition 
conformance lang os revision revisionflag role security status userlevel 
vendor wordsize.

One note: one might be tempted to use lang for translations, which, I 
think, is a mistake, One should use single-sourced English xml and let 
the translations live in po files, else the translated content could 
diverge and source files become excessively complicated.

By the way Thomas, please share any and all comments with me about 
doctemplate, including usage issues/deficiencies. And please also feel 
free to file bugs in lp.net/doctemplate.

Cheers,
Kyle

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