Ubuntu: A Beginners Guide
Thomas R. Jones
thomas.jones at maitreyasecurity.com
Wed Dec 23 21:13:27 UTC 2009
On Wed, 2009-12-23 at 14:43 -0500, 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
Awesome! Great job kyle.
I will pull your doctemplate system and run it through some QA of my own
docs generated for Novell/openSUSE. I have some 8,000+ proprietary xml
sources to test against. All validate to Docbook 5.4. So we should be
able to get a good idea to any regression issues. Would you prefer
off-list or through bugtracker?
Thanks for your quick work. Greatly appreciated.
Cheers,
Thomas
> >
> >
> >
> 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