Ubuntu: A Beginners Guide
jan Meijer
jan at familie-meijer.nl
Sat Jan 2 17:14:06 UTC 2010
Thomas/Kyle
Nice discussion you guys have, but...
A real pity you guys don't stick to the topic:
Doing so leaves the originator of the topic with his request for
co-operation on a new set of documentation!
Please start a new topic when there is one!
@ Benjamin: I am afraid I have little to no time left to assist,
although my fingers are itching to.
Some suggestions:
* Make it clear whether or not you stick to Ubuntu Desktop or
include Ubuntu Server as well.
* Scan the internet for equivalent projects: there may be many books
already out there. If you are confident your idea is much better
than that: Start summarizing the better parts of it and
communicate (through this mailing list perhaps) what the actual
content will be. Think before you jump!
Jan Meijer
Kyle Nitzsche wrote:
> 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