Stef's Blog

NOW AVAILABLE: Conary:QuickReference, a quick reference to software maintenance tasks on Conary-based systems (target audience: system administrators)

When I arrived at rPath three months ago, the document used to introduce a system administrator to software installation and system maintenance for Conary-based systems was a document called Conary Day-to-Day. Ed Bailey composed that and published the document in the form of a PDF and some HTML pages posted at rpath.com. The information was old, though, and there was a need for both an up-to-date version of this information as well as a "wiki-fied" version of it. I created an issue to handle this after seeing that a handful of the requested "how-to" documents (which we are calling "HOWTO" at the end of the page titles at wiki.rpath.com) could be covered by this effort. Additionally, this document would fall in as part of a hierarchy of documents used to educate new users about Conary, installing and maintaining Conary-based systems, packaging software with Conary, and developing software appliances.

I always get excited when a new opportunity arises to both aggregate and enhance existing documents. I worked through the order presented in Conary Day-to-Day, breaking the sections down in the same way. Almost every section could be covered by a small HOWTO, and I created each small HOWTO as needed with appropriate titles to be found in wiki searches. The small HOWTOs were transcluded into broader HOWTOs, creating a tree structure of transclusion that ultimately resulted in Conary:QuickReference. I really like how this project came together, and I appreciate every subject-matter expert (SME) and reviewer who helped ensure the content was up-to-date and accurate and the examples were fairly meaningful.

One additional thing I wanted to note about this effort was the trick used to gather the Conary screen output that typically includes several messages overwritten on the same line as an update progresses. Ed was able to find what he had used before: using stty ocrnl -onlcr previous to a command to ensure all the overwritten output is written on separate lines, and using stty sane to turn off this feature. The output is a little messy because of the spaces and being all in one paragraph (making the "sane" part rather indicative of its use), but it was easy to go through and put each message on its own line. This output was coupled with the actual command line appearance to demonstrate Conary output.

My current challenge is to go to a higher level and get some useful documents published in the wiki covering the Conary concepts for those not familiar with its features. This is like a step back from both the New Package Tutorial and the Conary:QuickReference and will serve as and extended and up-to-date wiki form of Michael K. Johnson's early Conary documents (currently available from rpath.com): the An Introduction to the Conary Software Provisioning System and the Repository-Based System Management Using Conary. After I finish the clean-up on the new document (which is my current task) and have SME review from the Conary team and other rPath folks, I plan to publish this document at Conary:Concepts. I'm excited that we will be able to point new Conary users here to answer many early questions and to establish basic understanding.