Ubuntu: A Beginners Guide
Kyle Nitzsche
kyle.nitzsche at canonical.com
Wed Dec 23 21:16:02 UTC 2009
Kyle Nitzsche wrote:
> 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/)
>
>
Lastly ;):
I added a fop customization layer: simply put any fop parameters (see
http://docbook.sourceforge.net/release/xsl/current/doc/fo/)
into the lib/fop-customization.xsl file and they are applied to all
generated pdfs.
Can be used in addition to FOPARAMS (mentioned above) for more
complicated params that require nested xml, like:
http://docbook.sourceforge.net/release/xsl/current/doc/fo/list.item.spacing.html
<xsl:attribute-set name="list.item.spacing">
<xsl:attribute name="space-before.optimum">1em</xsl:attribute>
<xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
<xsl:attribute name="space-before.maximum">1.2em</xsl:attribute>
</xsl:attribute-set>
doctemplate version 1.3-0ubuntu0ppa6 in the ppa has this.
Cheers and happy holidays,
Kyle
> 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.doctemplate_1.3-0ubuntu0ppa6_source.changes
>>>>>
>>>>> 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