Ubuntu: A Beginners Guide
Kyle Nitzsche
kyle.nitzsche at canonical.com
Wed Dec 23 19:43:49 UTC 2009
Kyle Nitzsche wrote:
> Kyle Nitzsche wrote:
>
>> 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.
>>
>>
> Hi Thomas:
>
> Turns out this was quite easy to implement, and I just did it. Update to
> version doctemplate - 1.3-0ubuntu0ppa4
> <https://edge.launchpad.net/%7Edoctemplate-team/+archive/ppa/+sourcepub/911031/+listing-archive-extra>(the
> latest in the ppa) to pick up profiles support.
> (I just pushed the new version and it built in the ppa, but it may take
> a few minutes to publish...)
>
> These changes add a PROFILES file to each new project's root directory.
> (This can be empty if you don't want to use profiles.)
>
> Each line of PROFILES is a profile that has three space-delimited parts:
> * --stringparam: this is required
> * profile.NAME, where NAME is the docbook profile you want to use.
> * VALUE: the profile value you need to filter source appropriately.
>
> Here's a PROFILES example:
> --stringparam profile.userlevel "student"
> --stringparam profile.os "linux"
>
> Here's sample docbook source that contains content pegged to different
> profiles through the corresponding attributes:
> <sect1 id="Testing">
> <title>Testing</title>
> <para userlevel="student">student user level</para>
> <para userlevel="instructor">instructor user level</para>
> <para os="linux">linux</para>
> <para os="win">win</para>
> </sect1>
>
> The filtered results carry through to all outputs: localized docbook,
> html, pdf.
>
> So, to create different "profiled" versions of your docs, you could
> either modify the values in the PROFILES file, or have different files
> that contain your various profile values and copy the one you want to
> use to PROFILES.
>
> Now, I'll need to update doctemplate-user-guide.
>
> Cheers,
> Kyle
>
>
>
I just implemented the same approach as with PROFILES to add a file
(FOPARAMS) that allows the user to specify parameters to pass to FOP for
po file creation.
These parameters are listed here:
http://docbook.sourceforge.net/release/xsl/current/doc/fo/
So, you just edit the FOPARAMS file (as above with PROFILES) to add the
desired params with the desired values: for example:
--stringparam toc.indent.width 72
--stringparam toc.max.depth 3
And the results show up in all generated pdfs.
Pushed change to ppa as version: 1.3-0ubuntu0ppa5
<https://edge.launchpad.net/%7Edoctemplate-team/+archive/ppa/+sourcepub/911069/+listing-archive-extra>.
Building now.
(https://edge.launchpad.net/~doctemplate-team/+archive/ppa/)
Cheers,
Kyle
>>
>> (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:
>>>>> ../doctemplate_1.3-0ubuntu0ppa4_source.changes
>>>>> 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>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>>
>>>
>>>
>>>
>>
>>
>
>
>
More information about the ubuntu-doc
mailing list