Author Archives: Erwin Lansing

New funded project: Documentation Project Infrastructure Enhancements

The Foundation is pleased to announce that Gábor Kövesdán has completed a funded project to improve the infrastructure behind the documentation project. Here is how Gabor describes the project.

Our documentation infrastructure uses very old and discontinued standards and tools. The work on modernising it has already started but still not yet completed. After discussions, we agreed that the migration of the toolchain had to be done in several smaller milestones for better quality assurance. The first major step changed the syntax to a more XML-like one but still allowed some SGML constructs. This is what we currently use in head. The second step is nearing completion and it will upgrade documentation from DocBook 4.2 to DocBook 4.5 and at the same time migrate to proper XML tools. A significant exception to this is PDF rendering, which will still use Jade and DSSSL stylesheets. DSSSL is an old and dead standard, which will not evolve any more. The only available open source DSSSL processors are Jade and OpenJade. Their development is also discontinued. This means a serious technology and vendor lock-in for the documentation project. The aim of this proposal is to eliminate this technology and vendor lock-in.

The following deliverables are provided as a result of the project:
  1. A DocBook 5.0 tree of the documentation. The basic set is available in projects/db5 but still the converter has to be run on a fresh checkout. The converter can be obtained from user/gabor/db5 and it has a README, which explains how it works. The converted sources are not checked in because in this way merges are easier and adjustments of conversion parameters is still possible. These are flexible until the moment when we merge this to head.
  2. A FOP-based rendering toolchain. This gives high quality output and after some last touches it will be print quality. I18N support is really good, all languages can be rendered in high quality. In particular, Xin Li (delphij@) confirmed that the Simplified Chinese is output is very close to print quality. A full PDF build can be found here: http://kovesdan.org/files/fop/
  3. A dblatex-based rendering toolchain. This toolchain is more limited. Its customization is more difficult and non-Latin text is not wrapped properly. Also, it fails with programlistings in tables so it cannot build the whole documentation set. This is a limitation that is explicitly listed in the dblatex documentation. This is a Java-free solution and is probably good enough to render release notes. In most cases, it is still better than the current PDF rendering but it does not give us full support and such a high quality as FOP. Some sample documents can be found here: http://kovesdan.org/files/dblatex/
During this work, I have discovered some things that are not related to the rendering itself but should be addressed before the print edition of Handbook:
  1. Indexterms are misused. They are not placed to the correct location, which may result in incorrect page number references. Also, there are outdated entries. Besides, some best practices should be consulted and applied to our docs. For example, should we index company names and brands or just technical terms? And which ones? And what are the conventions for secondary indexterms? I think they are a bit abused as well. And probably we should avoid third and further levels. We need to standardize this a bit and document it in fdp-primer. For such a huge manual as the Handbook, it is very important to have a good and usable index.
  2. Sectioning has too many levels. It is recommended to limit them to 3 or 4 when it is really necessary. In DocBook terms, it means using only sect2 and sect3 but not sect4. There are several places where such appear.
  3. Markup is sometimes overused. There are plenty of admonitions (warning, notes, ...), some of them in lists, tables in examples and tables in admonitions and such. These are meant to facilitate reading but when abused they are just confusing and overwhelming.

Vendor Summit at EuroBSDCon 2013


For the third year in a row, we’ll be organizing a Vendor Summit during the Developer Summit prior to the EuroBSDCon conference, this year in Malta on September 26 and 27. In previous years, we’ve had a number of presentations by companies, like NETASQ, pfSense and Netflix, on how they successfully built their products and services on top of FreeBSD, and how contributing code back to the community actually can save them money in the long term by reducing internal maintenance costs.
This year, I’d like to change to focus more towards an open discussion between vendors and other large consumers, not only so you can learn from each other, but also so the FreeBSD community can learn more on how their product is used. We’ve long heard that binary packages were the Achilles heal of FreeBSD. Are we on the right track with PKGNG? Java-support is another issue, but is there anything else you are missing that maybe some other company may have an existing solution for they may be able to contribute, but hadn’t thought about anyone else was looking for? Or maybe you have an problem that’s too big for one company to fix, but can be fixed if some of you together fund a project to do so. The FreeBSD Foundation might be able to help.
This is an invitation-only event, please contact me at [email protected] if you would like to attend. If you have anything to present or any topic you would like to discuss, please contact me as well. This will be an informal event, but we welcome a few short presentations.

FreeBSD portmgr thank you to the FreeBSD Foundation

The FreeBSD Ports Management Team wrote a thank you note to the Foundation for providing travel grants to several developers who therefore were able to attend the very successful Ports Working Group session.

We would like to publicly thank the FreeBSD Foundation for granting Baptiste Daroussin and Julien Laffaye a travel grant to travel to BSDCan 2011 for the Ports and Packages Working Group held at in Ottawa last week. The working group itself was a huge success and a number of improvements with regard to automated binary package creation and distribution to ease upgrade procedures for our users were discussed and will hopefully be implemented over the next few months.

None of these improvements, however, would be possible without a long overdue rewrite of the package tools provided by FreeBSD. Over last few years, a number of attempts were made to enhance the current tools, but none have been as all-compassing as the PKGNG project by Baptiste and Julien. The presentation given by Baptiste at the packages summit and summariszed at the DevSummit track of BSDCan showed a comprehensive new tool that can completely replace the current tools, and provide a clear migration path from the old to the new tool. It also provides a large number of new features while keeping the old ones and is a lot more flexible to be able to add more features later. As you may have heard, Baptiste has also joined the ports management team as a result of his efforts.

Thanks again to the Foundation for sponsoring Baptiste, Julien, Simon Nielsen (Deputy Security Officer) and Thomas Abthorpe (Ports Management Team) who all were instrumental into making the ports working group such a success.

FreeBSD portmgr thank you to the FreeBSD Foundation

The FreeBSD Ports Management Team wrote a thank you note to the Foundation for providing travel grants to several developers who therefore were able to attend the very successful Ports Working Group session.

We would like to publicly thank the FreeBSD Foundation for granting Baptiste Daroussin and Julien Laffaye a travel grant to travel to BSDCan 2011 for the Ports and Packages Working Group held at in Ottawa last week. The working group itself was a huge success and a number of improvements with regard to automated binary package creation and distribution to ease upgrade procedures for our users were discussed and will hopefully be implemented over the next few months.

None of these improvements, however, would be possible without a long overdue rewrite of the package tools provided by FreeBSD. Over last few years, a number of attempts were made to enhance the current tools, but none have been as all-compassing as the PKGNG project by Baptiste and Julien. The presentation given by Baptiste at the packages summit and summariszed at the DevSummit track of BSDCan showed a comprehensive new tool that can completely replace the current tools, and provide a clear migration path from the old to the new tool. It also provides a large number of new features while keeping the old ones and is a lot more flexible to be able to add more features later. As you may have heard, Baptiste has also joined the ports management team as a result of his efforts.

Thanks again to the Foundation for sponsoring Baptiste, Julien, Simon Nielsen (Deputy Security Officer) and Thomas Abthorpe (Ports Management Team) who all were instrumental into making the ports working group such a success.