Documentation status report, part 2
Been meaning to provide a follow-up to the last documentation report for a few days now, as well as a couple other news items.
Gentoo in the press
LWN ran an article on Linux distributions for PowerPC machines. Gentoo gets the top mention.
Package maintenance
I had the treecleaner team remove a package I maintain, WhaawMP. I hadn’t used it in a long time and was no longer interested in maintaining it. Upstream seemed to be dead, and there were several user interface bugs and crashers in daily use. Also, I didn’t want to put in the work on trying to make the ebuild comply with the stupid Python3 stabilization forced on all our users. Thanks to Jeremy for punting it. If you’re looking for a lightweight video player alternative, please read the comment I left on the bug. bug 315067
Documentation status
Now, down to the docs work I’ve done, mostly on the 21st and 22nd, after the last status report. The biggest news is that I finished rewriting the handbooks for the autobuilds. In two days, I did four architecture handbooks. I put in some long hours, but it felt good to finally have them all done.
Handbook updates
- Sparc: updated the handbook for the autobuilds. Also fixed the kernel config “conditionals” by adding in version strings to the handbook index code, so that the latest stable version magically appears in the guide. Truly XSL is an awesome thing. The former GDP lead once said that writing for the handbook is almost like programming it. The code is designed to take variables, drop them in place for given conditions, and to test for those conditions depending on the presence of other variables (which we call “keys”), which architecture you’re viewing, etc, and then drop those variables in to the rendered page. Once the XSL framework is in place, though, maintaining the GuideXML in the handbooks is much easier. We just drop the newest variable for LiveCD ISO size into the appropriate arch index, and it shows up as “115 MB” in that handbook. You can see some of our keys and how we use them.
- PPC: updated handbook for the autobuilds. bug 260403, bug 292726, bug 234310
- PPC: fixed the abstracts in the index. There was a lot of abstracts in the toplevel index. Abstracts are supposed to be in each chapter, so that the index just picks them up and includes them in the rendered page. Our XSL is frickin’ amazing.
- PPC: removed the warning and kernel config for voluntary preemption. I asked the PPC team if this old warning was still valid, and it turns out that the preempt code in the kernel actually works okay. Thanks to Joe for investigating.
- PPC64: updated handbook for the autobuilds. bug 260403, bug 292726, bug 234310
- MIPS: updated handbook. MIPS still doesn’t have weekly stages or LiveCDs. Because MIPS media dates back to 2008, there are some things I can’t fix in the handbook, like using
eselectfor profile management. If it’s not in the stages or CDs, I can’t document it. The profiles in particular have been significantly reworked for 10.0, and like everything else, will require some heavy rewrites in the handbook. The team is aware of how ancient their releases are, and are working to put out new media for more recent MIPS chips. bug 260403, bug 292726, bug 234310 - AMD64: fixed a broken link to the AMD64 FAQ
Desktop doc updates
- Xfce guide: updated the
firefoxpackage name. I was watching #gentoo-commits and happened to notice that nirbheek changed the name frommozilla-firefoxto justfirefox.
Other doc updates
- OpenRC migration: added a note on kernel module variables and how OpenRC assigns priority. bug 269349
- vpnc guide: updated the kernel configuration and adjusted the GuideXML to match coding standards. Thanks to tanderson for reporting via IRC. Also changed the text on vpnc overwriting
/etc/resolv.conf. Old versions didn’t overwrite it, but recent releases do. bug 330345 - Optimization guide: I updated the GCC documentation links to point at the 4.4 series, since it’s been stable for awhile now. The links were pointing to the old 4.3 series.
Project page updates
Website updates
- Where: removed the last reference to 2008.0 media, as the handbooks have all been switched to the autobuilds. Only HPPA still referred to the 2008.0 LiveCD, since that’s the last available release. That information has been in the HPPA handbooks for a long time.
- Contact: added another note saying that PR does not provide user support. We’ve been getting a lot of emails asking us for support, so I’ve been adding notes to our project page and the toplevel contact page.
- Lists: updated the list of mailing lists with information on closed and inactive list. Thanks to Jeremy for the patch. bug 291860
Documentation status report
I've been smashing documentation bugs left and right since getting back from vacation, as well as searching out old documents and project pages and fixing 'em up.
Most of the updates have been to the installation & Portage handbooks, but there are many changes to the other documentation, including the desktop guides for graphics cards, and my Xfce guide. There's even a new doc on Logcheck, written by one of our developers.
Here's a brief summary of what I've done in the last week:
New documentation:
- Logcheck guide: Thanks to phajdan.jr. bug 322223
Handbook updates:
- Change ccache recommendation; it's really only for developers: bug 327945
- Use layman rather than gensync for working with Portage overlays: bug 305047
- Add another note on IA32 emulation in the kernel for (non-)multilib users: bug 326691
- Fix file verification process for the Alpha, AMD64, ARM, HPPA, IA64, and x86 handbooks: bug 283402. This was an old one: when we went to the weekly media autobuilds, Release Engineering signed the files with a new GPG key, and changed how the files were signed. All the handbooks need to be updated, as they still have the old keys and instructions from the previous release.
- Update installation instructions for the autobuilds. Completed Alpha, AMD64, ARM, HPPA, IA64, and x86: bug 283402, bug 292726, bug 260403. Still need to do PPC, PPC64, Sparc, and possibly MIPS, if they have sufficiently recent media.
- Use -march=core2 for recent Intel EM64T chips, rather than the old -march=nocona. Fix MCE section of kernel config. Add new Atom processor type: bug 323381
- Update Grub documentation links. Upstream removed all grub legacy instructions in favor of grub2, which won't be stable any time soon. Fixed the handbooks and other docs to use the offsite Grub Wiki: bug 328679
- Fix a missing fstab. Gave ARM the same generic fstab example as the other arches: bug 328095
- category/package move for
chkrootkit
Desktop doc updates:
- Xfce guide: Change USE flags for opera; no longer needs qt-static. bug 328087
- nVidia guide: Use new driver installation methods. Add links to xorg-server guide to get X configured before dealing with nVidia-specific issues. Update kernel and module info. bug 307481
- ATI FAQ: General cleanups. Add R800 (Evergreen) info. Remove old GATOS project text. Update Catalyst availability section.
Other doc updates:
- FAQ: Update Grub documentation link. Update gcc -march info for x86 and AMD64. Fix internal GuideXML code. bug 328679
- Quickinstall guides (x86, LVM2+RAID): Fix ccache recommendation. bug 327945
- LDAP guide: use more recent 2.3 configuration file shipped with the ebuild. bug 325497
- SHOUTcast guide: Miscellaneous typo fixes. bug 323401
- IPv6 guide: update
net-dns/totdinfo now that it's stable. Fix GuideXML and minor text issues throughout. bug 326771. This doc presents an ongoing problem, because it recommends a package it shouldn't. I sent an email to the gentoo-dev mailing list asking for help with this one. - AMD64 FAQ: Update Flash installation info. Adobe decided to drop 64-bit versions (again) beginning in version 10.1, and our developers had to mask 10.0 for security reasons. This means that there is no Adobe Flash for non-multilib profile users. And nspluginwrapper is (once again) too unstable, so 32-bit Flash with a 64-bit browser is not recommended. Probably will have to install
firefox-binor some other 32-bit browser. Stupid Adobe. - UTF-8 guide: Fix wrong category for the Xfce terminal, leftover from when it was moved out of xfce-extra. bug 328977
- Fix metadoc index for retired developers and add logcheck guide entry
Project page updates:
- Overlays userguide: Extensive GuideXML, grammar, etc. rewrites to make the guide more readable and more helpful. Add more instructions for things like keywording packages per the Portage handbook. Add SCM homepage links. This series of updates was prompted by bug 305047, the gensync to layman change.
- GUIs: Update retired developers
- PR: Add note stating that PR does not offer user support, and list available support resources. Hopefully this will cut down on the amount of support requests the PR team receives in our inbox every month.
Website updates:
- IRC: Add the Qt project channel, #gentoo-qt. bug 328665
One of my fellow developers, jkt, has been helping out a bit in the last couple of weeks, closing bug 301840 and bug 325885. This was especially important when I was on vacation and then out sick. I'm always happy when someone besides me steps up and gets our docs into shape. Thanks, Jan!
So that's about it. There are still plenty of open documentation bugs, but the list has shrunk significantly. My biggest project now is to finish the rest of the handbooks for the weekly autobuild instructions. The rest of our open bugs will require just as many hours and days to fix, as large portions of our handbooks and guides will need to be rewritten. Hopefully I can at least get the autobuild updates done in the next few days.
Final exams, diplom thesis and thunar-volman
I guess it’s time for an update.
This week I passed the last of four final exams in computer science and human-computer interaction at my university. Not only am I pleased that nine months of learning are over; I am also blessed with excellent grades. And while my understand of good grades is similar to that of money (nice to have it but nothing to focus on and/or brag with), I have to admit that this time I’m at least a little proud of myself. Five years at the university are slowly coming to an end, the first friends are leaving town and it will soon be time to take the next big step in life.
I cannot leave this city before writing another thesis, however. Thus, I am currently looking for a Diplom thesis at the university or at companies related to open source technologies. If you happen work for such a company with interesting thesis ideas or opportunities, please let me know. The thesis is supposed to take about 6 months, ideally starting early in September. After that it’s time to pack my stuff and look for an employer. I’m hoping for a position in open source software development. Areas I’m particularly interested in include Linux, mobile computing, desktop-related technologies as well as renewable energy, environment protection and open government. I’m here to make a difference.
On to something else. A few weeks ago I was offered sponsoring in order to work on thunar-volman for a few days. I accepted the offer, so for the entire next week from 2010-07-19 to 2010-07-26 (including the weekend) I’ll do some sponsored work on porting Thunar and thunar-volman to udev and GIO! The goal is to finish all major features (storage devices, cameras etc.).
Yesterday I did some warm-up hacking on tumbler to verify that if I’m still up to the task. The results: a new ffmpegthumbnailer-based video thumbnailer plugin (written by Lionel Le Folgoc), a new PDF/PostScript thumbnailer plugin based on poppler-glib and a new tumbler release (0.1.2). The master branch contains another commit adding arbitrary URI support to the PDF/PostScript thumbnailer but for that you’ll have to wait until the next release.
That’s it for now, I’ll be a lot more active next week. Take care everyone!
Don’t produce Gzipped tarballs
A quick note so I can delete it from my desktop. In order to produce only a Bzip2 tarball with the Autotools, specially when running make distcheck, set the automake init call with these parameters:AM_INIT_AUTOMAKE([no-dist-gzip dist-bzip2])
By the way I wonder if it's worth dumping bzip2 against xz.
