Birds Project
User Guide
Bird Man, a painting by artist Lynn Rothan


Command-Line Options
A Brief Tutorial
Cut and Paste
Additional Markup
External Traceability
Fancier Features
Some Newer Features
Modifying the DTD
Importing Word, Excel, or Other External Data


Do178Builder is a program that allows developers of airborne software to do two things:
  1. It is an editor that stores software development data such as requirements and design decisions in a hierarchical outline structure that is hopefully natural to use; and
  2. It converts the development data to DO-178B and (as of 20060702) DO-254 certification documentation on demand.
The idea is that Do178Builder would be used throughout the development effort, from beginning to end, thus helping to enforce the kind of development regimen envisaged by RTCA/DO-178B or RTCA/DO-254.  In other words, it's not expected that you simply do the whole software development effort and then shove the data into Do178Builder afterward.   For a pre-existing development effort, of course, you'd have to do it that way.

Development data is stored in an XML dataset, which is both human-friendly and machine-readable, so there is little worry in using Do178Builder that your data will be trapped in some unrecoverable format (if you should decide later that Do178Builder isn't useful for you).  There is presently no DTD as such for Do178Builder's XML files, if that's important for you, but there is a master XML file called ".template.xml" (or ".template254.xml for DO-254) which is stored in the same directory as the Do178Builder executable, and defines the XML format used.  Refer also to the developer page for more details.

At various points in the development effort, particularly near the beginning and at the end, it is useful to create DO-178B  or DO-254 documents from the development dataset.  These certification documents are created in DocBook format, and then you may use various freely available utilities (not provided by Do178Builder itself) to convert your DocBook DO-178B documents to HTML, to RTF, to Postscript, to PDF, or to various other formats.  These conversions are associated with stylesheets, so that you have a significant level of control over the conversions which are performed.

Note that the descriptions below were almost all written prior to the time Do178Builder supported DO-254.  Therefore, the descriptions continually refer to software, as in "software high-level requirements" or "software test cases".  However, they refer almost equally to hardware development and DO-254.  For example, wherever you see "software high-level requirements", you can simply read it as "hardware requirements" if you like.

Command-Line Options

The command-line syntax for Do178Builder is
Do178Builder -s=IpAddress [options] [XMLfilename]
Non-Win32 versions 04/26/2004 and later want you to run Alberto Bertogli's Open Lock Daemon (OLD), v0.14 or later (http://users.auriga.wearlab.de/~alb/old/).  The OLD server requires a *NIX system on which to run, and you need to set the appropriate -s switch for Do178Builder (see below) in order to use it, or -l=0 in order to bypass it.  What OLD does is to allow you to lock Do178Builder databases, to prevent simultaneous editing of the database by different users, so while you can bypass it, you're looking for trouble.

The allowed command-line options are listed in the table below.  If the XML project file is not specified on the command line, it has to be loaded interactively using Do178Builder's menu.  Only existing XML files can be specified on the command line.  Also, the full pathname must be used, as in "/home/rburkey/libBirds.xml", even if the "-p" command-line switch is used.
Switch Version available Description
-c All When Do178Builder starts, it displays a splash screen explaining that the program is available under the GNU General Public License.  When the -c command-line switch is used, this splash screen is eliminated.
-h (or --help or -?) All Causes Do178Builder to display a list of options and then to quit.
-p=DirectoryName All By default, Do178Builder expects to find your project files in the current directory.  The -p switch allows you to specify a different directory, which is useful (for example) in setting up a desktop icon for Do178Builder.  The project directory will contain not only your project's XML dataset, but also any graphic images used by the XML dataset.  Also, it is where output files are stored when the DO-178B documents are built.
08/07/03 and later
By default, Do178Builder's editor dialog window does not expand beyond 1280×1024 pixels.  The -x and -y command-line switches allow these defaults to be changed (either larger or smaller).  The expansion limit is to overcome a mysterious problem in the Linux version of Do178Builder in which (on some platforms) expanding the editing window past a certain size causes intermittent crashes thereafter.  Refer to bug report #37.
07/06/06 and later
Turns off the 1280×1024 resizing enforcement mentioned above.  It gives something much cleaner and prettier, but the program will still spontaneously exit on some platforms if you turn this off.
11/10/03 and later.
For versions of Do178Builder prior to 11/10/03, the act of building the output (SGML) documents caused the creation of a directory named after the XML project file for storage of those documents, thusly:  ProjectName.documents.  In later versions, the output directory also includes a date-stamp, thusly:  ProjectName-YYYYMMDD.documents.  The advantage of the latter approach is that it is much easier to retain specific versions of the output DO-178B documents, and to track changes in them.  However, the earlier behavior (output directory without the date-stamp) can be restored by using the -o command-line switch.
04/26/04 and later.
The IP address or network name of the computer on which the server for file-locking is running.  The server is Alberto Bertogli's Open Lock Daemon ("old").  By default, the server is "localhost".  However, if you have multiple developers potentially accessing the same databases on a network, you'll want a single server running, and you'll want this same server to be used by all of the developers.   Even if there is only a single developer, if you have no lock-server it is still possible to become confused and to simultaneously open two instances of Do178Builder, operating on the same database.  Since Do178Builder is not a true database system, this situation can result in you overwriting your own or other developers' changes.  File-locking was not available for Win32 with Do178Builder versions before 2005-07-05, but is available since then.
04/26/04 and later.
The port-number used for accessing the Open Lock Daemon ("old", see above).   By default, 2626.  You can bypass the the lock-server completely with -l=0, but it is dangerous to do so unless "old" simply won't run.  The lock server runs only from a Linux box, regardless of whether the Linux or Windows version of Do178Builder is used.
06/21/05 and later.
The default font-size used by Do178Builder is 10-point (or perhaps 10-pixel).  But this is too small for many of us who are weak and feeble enough --- i.e., old enough --- to have been badgered into doing DO-178B work.  The -f switch can be used to basically select any font size, but the practical limits (it seems to me) are -f=10 to -f=20.  All of the screenshots below were with -f=10.   FontSize is used for the editing pane, whereas the optional FontSize2 is used for the hierarchical display of titles.
07/02/06 and later.
Works with DO-254 rather than DO-178B.
01/25/08 and later
By default, when documents are built, both backward and forward traceability references are added to the documents.  For example, the SDD traces to the SRD, but the SRD also traces to the SDD.  Forward traceability is problematic in the minds of some DERs for a couple of reasons:  a) One of the documents doesn't exist yet, so how can you know that the trace references are correct?  And, b) forward traceability is usually one-to-several (e.g., any given section in the SDD traces to a single section of the SRD, but any given SRD section of the SRD probably traces to several SDD sections, so how can you know that the trace is complete?  For this reason, you may want to simply eliminate forward trace references.  The "--no-forward-trace" command-line switch accomplishes this. 

Of course, having done so, you'll have to do something else to satisfy DO-178B's traceability objectives.  I'd suggest checking out the Do178Builder-utility program.  It doesn't address the DER concerns mentioned above, but it does produce something much more similar to what people are used to seeing, and therefore may reduce the probability that such concerns are raised.
03/08/08 and later
By default, the DocBook output produced by Do178Builder encapsulates your product name in the DocBook tags <productname></productname> on the title page and in page headers.  This is a perfectly proper thing for it to do.  One side-effect of that is that with some common style-sheets the product name is followed by a ™ symbol.  For example, your title page might read:

Your Company Name
Your Product™
Software Requirements Data

If that's what you want, then fine!  But I personally have worked on some documents where instead it's an annoyance; besides it's easy enough to add &trade; manually wherever you want the trademark symbol.  While the automatic addition of the trademark symbol could probably be changed in the stylesheet—and indeed, that's philosophically the way it's supposed to be done in DocBook—I've elected to provide the alternate approach of using the --no-productname switch.  With this switch, Do178Builder simply omits the <productname></productname> tags from the output, and hence any problematic ™ symbols are thereby also omitted.

... On the other hand, with some DocBook converters, the <productname> tags seem mandatory, while other converters seem more tolerant.  So your mileage may vary.
01/25/08 and later Some DERs simply spit up on the whole approach Do178Builder takes to traceability and insist on having a separate traceability matrix.  If that's the case, you can completely turn off trace references with this command-line switch.  For help with creating separate traceability matrices, the Do178Builder-utility program may be of assistance.
01/25/08 and later If you do use the "--no-trace" command-line switch mentioned above, or even if you don't, you may be able to simplify your traceability problems by producing a single combined  requirements&design document rather than separate requirements and design documents.  Making sure your requirements are "verifiable" may also be simplified by this approach. 

DO-178B explicitly mentions that you might be able to combine the SRD and SDD, I think.  But you will have to give some thought to your life-cycle processes if you do that, since a shorter form of the document (with requirements only) would be created by your requirements process and a longer form of it (with both requiremens and design data) would be created by your design process.  My suggestion in this regard would be that on the first pass through the requirements process you create a simple SRD document, but once you get to the design process or to subsequent iterations of the requirements process you produce a combined SRD/SDD document.

At any rate, by default the SRD and SDD documents are separate, but with the "--combine-srd-sdd" command-line switch the two are automatically merged into a single document when the output SGML is created.  In other words, by default you get SRD.sgml and SDD.sgml when you build the documents, but with this command-line switch you instead get SRD-SDD.sgml.  (There is no effect whatever on your XML.)  This same effect can be accomplished also by editing the document framework, but this makes much more simple to do and to undo, and you have to do some manual tweaking of the sgml that's produced in order to fix the document title and page headers.

The effect of this switch is not completely automatic, since the project template may cause some duplication of document sections which you need to manually tweak a little bit.  (For example, there will be both an SRD Modification History section and an SDD Modification History section in the resulting document, so you'd probably like to manually delete one of them and rename the other to "SRD/SDD Modification History" or something of that nature.)  Nevertheless, it is much more convenient to use this command-line switch than to modify the project template.

Another manual adjustment you probably need to make is in that part of the project template where document number and revision information is normally specified:

Project Overall Information
Document Version
PSAC Identification
SRD Identification
SDD Identification
SVCP Identification

You must rename "SRD Identification" to "SRD/SDD Identification", or else when you create your SRD/SDD document it will be lacking this identifying information on the title page.
01/27/08 and later
By default, Do178Builder outputs files in DocBook v3.1 SGML format when you build documents.  However, v3.1 is rather out-of-date now.  Moreover, most people now apparently choose to use DocBook XML rather than DocBook SGML.  Neither of these is much of a problem if you are running DocBook tools on a Linux platform, since the older versions of DocBook have not disappeared there.  But it is somewhat problematic if you wish to run the tools on a Windows platform, since Windows has come to the party rather late and only support for later versions of DocBook is readily available.  I should just let you suffer for refusing to install Linux—after all, it's free!—but rather than doing so, I've chosen to help you out instead.

As you may have guessed, the command-line switches "--x412", "--x42", "--x43", "--x44", and "--x45" switches cause the Do178Builder to output DocBook v4.1.2, v4.2, v4.3, v4.4, and v4.5 XML documents, respectively.  It is perhaps worth noting that these v4.x documents differ among themselves only in that they identify themselves as having different versions, but are not different in any other way.

One subtle aspect of these command-line switches is the question of what happens if your project already contains DocBook v3.1 commands you've inserted  manually using the "<docbook>...</docbook>" construct.  DocBook v3.1 and v4.x are not entirely compatible, nor are DocBook SGML and XML, so these manually-inserted commands may or may not need to be modified in some way to work properly.  Do178Builder will automatically fix some of the most-common conversion problems for you, namely:
  • Element names need to be all lower-case (such as '<emphasis>') in XML, whereas SGML allows mixed-case (such as '<Emphasis>').
  • Attribute values must be quoted in XML (such as '<colspec colwidth="0.5in"/>'), whereas in SGML they don't have to be unless they contain spaces (such as '<colspec colwidth=0.5in>').
  • Also, the "colspec" element needs closure in XML (which is the reason for the '/' before the closing '>' above), whereas in SGML it does not.
  • Symbols '&' or '<' in a <programlisting> need to be changed to changed to "&amp;" or "&lt;" in XML, although they usually work without conversion in SGML.
For me, these conversions seem to provide a 100% fix.  But if you've been more sophisticated with your manually-inserted DocBook commands than I have, you could easily have inserted code that is beyond Do178Builder's meager repair abilities and has to be fixed manually.

Since v4.x XML support is so new, it is reasonable to wonder if the end result (i.e., the PDF files which are ultimately desired) of using v3.1 SGML differs from v4.x XML.  PDFs produced using the two methods are almost the same size, and don't seem to differ visually—for example, the pagination seems the same—but determining how two PDF files differ is rather difficult.  If RTF files are created rather than PDF, an automated comparison can be performed by bringing the RTF files into Microsoft Word or Open Office, and using the built-in document-comparison tools of those programs.  I've done this with a pretty complex real SRD/SDD document in Open Office, and what I find is that the two differ only in the whitespace associated with the "<programlisting>" element.  However, the whitespace difference seems to be only in the RTF files, and cannot be seen in the PDF files.
01/31/09 and later
When this command-line switch is used, Do178Builder simply loads the specified database, creates the SGML or XML DocBook output files, and then exits.  No GUI is presented, and all prompts are bypassed.  There are a couple of reasons one may wish to do so:
  1. If you have developed scripts or other methods to directly import data such as requirements or software configuration directly into the Do178Builder database format, it might be convenient to be able to build documents in an automated fashion without having to contend with a GUI; or
  2. You might not like the Do178Builder GUI, and might want to replace it with a different GUI whilst still retaining the basic concept of document generation from a hierarchical database.  For example, I've thought that a nice WYSIWYG Do178Builder-like GUI could be created as an add-on for OpenOffice.
But obviously these are pretty specialized purposes, and no normal software-development environment is going to have them.
02/03/09 and later
When this command-line switch is used, all of the plan documents are combined and a single plan document is produced.  The resulting document can be identified as any one of the plans.  So for example, if "--combine-plans=SDP" is used, then the PSAC, SDP, SVP, SQAP, and SCMP will all be combined and identified simply as the SDP.  Similarly, if "--DO-254 --combine-plans=PHAC" is used, then the PHAC, HDP, HVVP, HPAP, and HCMP will all be combined and identified as the PHAC.  Acronym must be one of the 10 acronyms mentioned above, and it must be an appropriate one vis-a-vis DO-254 vs. DO-178B.

The reason I wanted this option is that I found myself producing a simplified software-development procedure for Level E projects, and wanted to roughly following the pattern of higher-level projects but at the same time didn't want the complexity of having a multiplicity of documents where having just one was sufficient.  This could have been done by manually going through and checking the appropriate document boxes in the GUI, but that was just too darned much work.

A Brief Tutorial

Run Do178Builder from the *NIX or Windows command line, or create a desktop icon for it.  (In the latter case, you probably want to use the -p command-line switch described above).  Do178Builder expects to find the file ".template.xml" (notice the leading '.')  or ".template254.xml" (for DO-254) in the same directory that holds the Do178Builder executable program.  If it does not, it will present you with a file dialog requesting you to find the file.  In *NIX, filenames with a leading dot are hidden and don't show up in directory listings.  So make sure you activate the "hidden files" option in the file dialog, or else you won't be able to see .template.xml.

Once Do178Builder is running, use the File/Open or File/New menu option to open an existing XML  project or to create a new one.  (In some versions of Do178Builder the File/New function hasn't been implemented.  This is fixed in later versions.)  In airborne-software development, large portions of the development data tend to be reused from project to project, because quite a lot of the development data relates to standards, development processes, SQA, SCM, and so on, rather than to technical detail.  Therefore, it's seldom useful to create a completely new project (except for the very first time).  It's much more useful to start a new project by opening an existing one and using File/SaveAs.  You may find that deleting unwanted technical detail is easier than recreating program-management or software-engineering detail.

... On the other hand, by copying an existing project, you may be missing out on improvements that have been made to the templates (.template.xml or .template254.xml).  I guess there's no perfect approach. ...

Here's the basic screen you'll see in editing the development data, with some annotations I've added in red:

Main editing screen, with annotations

The levels of the outline view can be expanded or collapsed by clicking the little +/- boxes next to their names.  By looking at the right-hand side of the screen, you see the DO-178B documents to which the selected item (left column) or section (right column) are relevant.  (A section applies to a given DO-178B document if -- when fully expanded -- any of its data items apply.)  So you can tell at a glance whether any given item in the outline view is relevant at any given point in the development effort.

For example:  in beginning a project, it's usually true that only those items that contribute to the PSAC document are important.  So, you can contract and ignore all of the outline items that don't contribute to the PSAC.  In the next development phase, after the PSAC exists, you might want to develop only your standards (the SDS, the SCS, and the SRS), and so you might contract and ignore all data items not applicable to those documents.  Etc.

One of the more valuable features is the "hint" area at the bottom of the screen, since it tells you what's "supposed" to go into each data item.  Take these hints with a grain of salt, though, since I wrote them and they're limited to my understanding.  Given the nature of DO-178B, unfortunately, my understanding is sometimes inadequate.  I'd really love to hear from anyone knowledgeable who can suggest improvements to the hint area.  It would have been ideal to be able to quote extensively from DO-178B in the hint area, but given the copyrighted nature of the material this does not seem a likely prospect in the near future.

The quirky little areas "Applicability by DO-178B SW level" and "Control Category by DO-178B SW level" actually do reproduce information rather closely from DO-178B, at least from the standpoint of the weird iconic symbols.  Here's how those symbols are interpreted:

Don't care -- optional
Must satisfy this requirement
Must satisfy this requirement with independence
Control Category 1
Control Category 2

In the example shown above, the "Software Level and Means of Compliance" data item appears (in the PSAC and SAS) in all software levels from A-E.  For software levels A-D, it is in "Control Category 1".  Actually, you're not required to have a SAS in software level E, but you're going to get one anyhow if you use Do178Builder.

If you look at the hot-buttons above the outline-data area, you'll find some additional functionality related to adding or deleting outline items:

How to add line items.

In this example, a new data item was added.  Now, Do178Builder is not a general-purpose outline editor.  It only lets you add data items if such a data items are allowed at the cursor position.  Usually, unless you've deleted items, there are no allowed additions, and the insertion button will be greyed out.  Sometimes, though, a sequence of items of a similar type may be allowed, and Do178Builder may not know in advance how many of them there are, or what their titles are.  The example shown is typical.  There are a certain number of "system functions" that need to be specified, and you can have as many (or as few) of these "system functions" as you like.  The system functions in this example are "Boot Loader:  Relocation to RAM", "Boot Loader:  Program Selection", "TBD Title of a System Function" (the new item just added), etc.  Do178Builder has added not only the new data item, but also all of its sub-items.  (Actually, some versions of Do178Builder have a bug that prevents the sub-items from being added, and in this case you have to just keep adding sub-items until it doesn't let you add any more of them.  This is fixed in later versions.)  You can't see these, because the item isn't expanded, but you can tell by the + symbol that they're there.

Notice, by the way, that several section headings have changed from black to blue.  Every time you edit an item in Do178Builder it and all of its parent outline items turn blue, so that you can easily see where changes have been made.  However, these color-markings will disappear the next time you load the file.

The hot-button next to the insertion hot-button is similar, except that it adds a new sub-item to a section.  The "delete" hot-button next to that allows menu items (and their sub-items) to be removed.  Of course, the "save" hot-button, which looks like a floppy disk, allows the dataset to be saved at any time.  And not least, the search and search-again hot-buttons (finally functional as of 2006-07-03).

So, you've input a lot of data into the outline, and now want to create DO-178B documents from it.  How do we do it?  Exit from the editing screen by hitting the X in the corner.  (You can always get back to the editing screen later by using the Edit menu from Do178Builder's main menu.)  Use the Tools/BuildDocuments option from the Do178Builder main menu.  What this will do is to create a new sub-directory with the same name as your XML project file (but ending in ".documents") and an added date-stamp, and to place a series of SGML files (or XML files, if you've used the "--x45" switch), which are the DocBook files representing the various DO-178B documents, into the sub-directory.  For example, the output directory might be called "MyProject-20031110.documents" to indicate that it belongs with MyProject.xml and was created on 10 November 2003.  The output  is created essentially instantaneously.

In my case, for example, the project directory is /home/rburkey/Projects/birds/test, and the project is called "libBirds".  (In the screenshot below, the output directory is called simply "libBirds.documents" rather than "libBirds-20020216.documents", because I've used the "-o" command-line switch.)

What do you do with the DocBook SGML or XML now that you have it?  Well, there are several options, covered on my DocBook page.  Basically, at least on *NIX systems, there are freely available (and free!) utilities which you can used to convert these files to RTF (which can be loaded into Microsoft Word or other word processing programs), to Postscript (for direct printing), to PDF (for viewing or printing with Adobe Acrobat Reader), to HTML, etc.  These are really options for you to explore yourself, though I'd be happy to hear about anything you discover.


Cut-and-paste should be possible in the editing box, but not presently in the outline area.  The conventions used depend on the platform you're using. 

In Linux, in general, the methods for cut-and-paste are not so standardized as in Win32.  Any or all of the Linux cut-and-paste methods work in Do178Builder with about the same chance of success as in any other Linux program.  (Just for reference, Ctrl-C/Ctrl-V sometimes works in Linux.  Other times, highlighting an area of text and then clicking the middle mouse button where you want the text inserted sometimes works.  There may be other methods as well.)

Additional Markup

(Note:  Not all of the markup tool-buttons shown are present in all versions of Do178Builder.)

Above the data-editing area in Do178Builder are several controls that can be used to enhance the output text:

Markup hotbuttons

It's important to understand that Do178Builder is not and cannot be a WYSIWYG editor as long as it aims to create DocBook SGML files.  (WYSIWYG = "What You See Is What You Get.")  Perhaps one day it will be a little more WYSIWYG than it is now, but it can never be completely WYSIWYG.  The reason for this is that it outputs DO-178B documents in DocBook-based SGML, and the markup in DocBook is content-oriented rather than appearance-oriented.  Consider the previous sentence, for example.  When I wrote that sentence, I told the HTML-editing program that I wanted the words "content" and "appearance" to be in italics, and consequently they appeared in italics.  In DocBook you couldn't do this, because DocBook knows nothing about italics, and nothing about the appearance of the document.  In DocBook, you would have told it that "content" and "appearance" were emphasized.  But "emphasized" does not equate to "italicized"; it might be italicized, or it might be boldface, or it might be underlined, or it might be a different color.  All of these options are determined not within the DocBook files, but within the "style sheet" used to convert the DocBook files to other types of files.  Indeed, different file types might have different style-sheets, so "emphasized" text might be very different in a target RTF document than in a target PDF document.

Well, how would text be emphasized in DocBook?  This is done with an <Emphasis> tag and an </Emphasis> closing tag.  For example, <Emphasis>this phrase</Emphasis> would be emphasized.

This was just a trivial example, of course, but there are many other kinds of markups for enhancing the output text, and the same comments apply to all of them.  Obviously, I don't expect you to go out and research all of the possible DocBook markup tags and memorize them, and and we can't provide tool-buttons for every conceivable markup.   However, Do178Builder makes a subset of DocBook markup tags available to you, and you can choose the desired kind of markup from a drop-down list.  After choosing the type of markup from the drop-down list, you use the mouse to select an area of text, and then apply the markup to that text by hitting the hot-button marked with M. Only text in the editing area can be marked; section titles cannot be marked.

By default, Do178Builder presents you with a "novice" list of possible markups, which is a very short list designed to contain what I think are the most important choices that can be handled with simple DocBook tags, but with few enough choices to avoid confusion.  (Many desirable features cannot be handled by the simple addition of surrounding tags, and therefore don't appear on the drop-down list; refer to Fancier Features, below.)  On the "expert" setting, a much longer list of markup choices is available.   Now keep in mind that all of this enhanced markup is optional as far as Do178Builder is concerned, and you can either use it or not, as pleases you.  But, it's available if you need it. 

Here is the "novice" list, as of 02/16/2002.  (If you want to use the "expert" list, I'd suggest learning more about the DocBook DTD.)

The meanings of many of these are obvious, but here are some of the less obvious ones:


Do178Builder allows you to include images (such as a graphic for an illustration) in your dataset, and hence in your documents.  At present, it does not allow easy inclusion of arbitrary images, or easy inclusion of images at specific locations, but merely of certain images typical of DO-178B documents.  (But see "Fancier Features" and "Some Newer Features" below.)  These include org charts and software-development process flowcharts.  Each potential image has its own entry in the dataset outline, so it will be obvious how they're included.

However, there's a certain subtlety in graphics usage that has to do with the target document types to which the DocBook-format files output from Do178Builder are eventually converted.  In other words, the different utilities that convert the DocBook files to different target formats expect to see different types of graphic files.  For HTML conversion, GIF or JPG might be desirable.  For Postscript conversion, EPS files might be desirable.  For RTF conversion, EPS files might be usable, but BMP files might be best.  (And so on.)  This isn't really a problem for you if you are interested in targeting only one type of output document.  If you are targeting several different document formats, you may need to prepare the same graphic in several different formats.

More detail about working around this problem in Linux can be found here, or in Windows here.

External Traceability

(Note that Do178Builder's native traceability functionality has been augmented in versions 20080317 and later by a separate utility program known as Do178Builder-utility.)

In versions of Do178Builder after  04/15/04, an additional hot-button not present in the screenshots above is available, the "tr" hot-button.  This hot-button adds the non-DocBook tags <trace> and </trace> to the highlighted text.  This markup is used to manually add traceability references so that they appear in the same manner as traceability references automatically generated by Do178Builder.

Without assistance, Do178Builder is able to add traceability references from high-level software requirements to low-level software requirements, and from low-level software requirements to software test cases.  (Prior to version 2006-07-02, Do178Builder did not support automatic traceability from high-level requirements to test cases, but later versions do support this.  In other words, you have an option as to whether to add your test cases at the high-level requirements, the low-level requirements, or both, but Do178Builder will supply the proper traceability in any case.)  However, additional traceability may be needed, as follows:
(Note that, in DO-178B-speak, a software source-code file is referred to as a "software component".)  Do178Builder cannot add these latter references on its own, because the system requirements and the source-code components are external documents or files that don't exist within the framework of the Do178Builder database.  Therefore, references to them must be added manually.  One could, of course, simply add these references as plain-text.  But they look a little prettier if marked with <trace>, because they then appear in the same visual format as the references inserted by Do178Builder itself.

While Do178Builder will allow you to add <trace> markup anywhere, the only such markup which actually has any effect is that which appears at the beginning of a high-level requirement, low-level requirement, or test case.  The text between the <trace></trace> tags is discarded in other contexts.

See also the newer features below.

Fancier Features

DocBook supports many features that are much fancier than any of those listed above, such as:
Indeed, DocBook has so many features you might want to add to your documents that I can't even really conveniently list them here.  While it would be convenient if Do178Builder directly supported everything DocBook supports --- maybe even in a WSIWYG way --- this is simply not going to happen.  As of 03/26/04, though, Do178Builder does indirectly support all of DocBook's features, by allowing you to simply include DocBook code directly into your text, encapsulated by the <DocBook> tag.  Of course, to take advantage of this, you have to actually know DocBook, or at least have the energy to research the DocBook features you need.  Get DocBook: The Definitive Guide, by Normal Walsh and Leonard Muellner, and keep it by your side.  (Or, if you only want to look up a feature or two, peruse the online copy at www.oreilly.com).

As an example, suppose that you wanted to add a table that looked like this to one of your DO-178B documents:


Here's what what encapsulated DocBook code for producing a table like this in Do178Builder might look like:

<tgroup cols=3 align=center>

Here is a fake "PSAC" document demoing some of the things you can do with raw DocBook commands, and here is the Do178Builder XML file from which the PSAC was generated.  (If for some reason you want to actually play with this file, better download its graphics as well:  star_butterfly.jpg and Hatter.jpg.)

When documents are generated, everything between <DocBook> and </DocBook> is just inserted unchanged into the DocBook-SGML documents that are created by Do178Builder, except that some normalization is automatically done to try and make sure that any DocBook v3.1 SGML commands you've added can work with DocBook v4.5 XML.   But Do178Builder's ability to perform such normalization is limited.  Obviously, there is a great potential in this feature for creating illegal DocBook files, so you must have a greater readiness to debug DocBook problems if you avail yourself of this feature.

If you are using DocBook XML, and if you are using the XMLmind XSL-FO Converter program to convert those files to printable form, then the customized stylesheets I give you for this purpose also happen to provide some extensions to DocBook that give you a few features that could come in handy from time to time.  (Note that all of the markup mentioned below needs to be within <docbook> tags.)
These DocBook extensions are not available to you if you are using some other method (such as the db2pdf program) for converting DocBook to printable form.

Some Newer Features

Here is a newer screenshot which illustrates some features (20060702 and later) that weren't present when the descriptions and screenshots above were created.

Click to enlarge

In addition to the features in the screenshot (which I hope are reasonably self-explanatory (except, perhaps, for the traceability feature, which is described in an earlier section), there is a feature available from Tools on the main menu.  This feature, "pruning", allows you to remove all items from your database that don't pertain to the a selected assurance level.  For example, if you were working at assurance level C, you could prune away all of the items that pertained just to levels A and B.

And as of 20080323, some still newer features:

Screenshot of 20080323 features.

Modifying the "DTD"

The various data sections, subsections, and data items appearing in the outline dataset have been chosen to fulfill three objectives:
  1. To present the various data items to you, the developer, in a reasonably logical way that approximates the natural order in which you need to address those items;
  2. To produce DO-178B documents which can be compared item-by-item to RTCA/DO-178B itself.  In other words, to address all of the questions asked by DO-178B in the same order as DO-178B asks them.  Note that there's no necessity to do this, but it makes things a little easier on those individuals verifying compliance, and hence makes certification a little cheaper; and
  3. To automatially create traceability references from requirements to design, and from design to verification.
These goals, I think, have largely been met.  There are a few ways in which data items could appear more naturally in the data outline, and a few places where ordering in the output DO-178B documents differs from that in RTCA/DO-178B, but overall it's a good compromise.

... That is to say, it's a good compromise if you're just starting up a DO-178B program.  You may not consider it a good compromise if you already have strong ideas (or legacy documents, or company policies) that constrain your DO-178B documents differently.  In other words, if you're an old-hand at DO-178B.

Within certain limits, it's possible to change the ordering of data items within the data outline or output DO-178B documents, to modify default section titles, to modify the hints, etc.  This is done by modifying the Do178Builder XML DTD.

I am speaking figuratively here, because there's no actual DTD.  Instead, there's a file called ".template.xml", stored in the same directory as the Do178Builder executable, and this file acts in place of a DTD.  It contains all of the hints, default titles, section ordering, etc.  In fact, it is exactly like a fully populated Do178Builder project that's empty of data.  So by editing this file, you can effect various changes to the input and output formats.

By the way, I don't personally recommend changing .template.xml, since it renders your datasets incompatible with the as-distributed Do178Builder system, and therefore may keep you from taking advantage of future improvements.  Submitting changes to me, so that they can be implemented in a more controlled fashion, may be a better alternative for now.

But if you're insistent on doing so, the easiest way to do so is to take advantage of the Options/ModifyFramework selection from Do178Builder's main menu.  When activated, Do178Builder allows you to edit not merely project data, but also to edit many other things, such as the hints and the applicable documents.  These changes would be saved along with your document.  So typically, you'd activate Options/ModifyFramework, and then open (and edit) .template.xml itself.  Probably you should read and thoroughly understand the developer page before doing so.

Change Tracking

Great News!

For a long time, I've considered the lack of built-in change tracking the Achilles' heel of Do178Builder.  By "change tracking", I mean the ability to produce documents in which the changes from the previously-approved or previously-reviewed versions can be seen easily.  No programmer or DER likes to get a 100-page document that was previously approved, but for which the changes aren't obvious at a glance.  Do178Builder doesn't have the capability to do change-tracking directly, and the methods I knew about up to now for doing it indirectly (as in the "Some Additional Information" section below) haven't really that great.

But I've finally hit upon an indirect method for doing change tracking that works magnificently, is almost automatic (or at least very easy), and seems to me like a 100% solution to the problem.  There are two methods:

OpenOffice Method

  • To use this method, you're going to need to have Open Office 2.0 or higher.  In case you don't know, Open Office is a free near-clone of Microsoft Office, available both for Windows and for Linux.  You can get it at www.openoffice.org.
  • Suppose you want to compare two versions of a document you've built with Do178Builder, say (for concreteness) the 2005-01-25 version and the 2005-12-15 version of the SVCP document from a project you're calling "MyProject".  As has been explained above, the DocBook-formatted SVCP.sgml documents created by Do178Builder will have been stored in the directories called "MyProject-20050125.documents" and "MyProject-20051215.documents".
  • If you have bought into my mindset, you will normally have processed SVCP.sgml using the utility db2pdf, in order to produce SVCP.pdf, which is what you have been reviewing and approving.  Alternatively, though, you could process SVCP.sgml with the utility db2rtf, producing the file SVCP.rtf.  SVCP.rtf has the advantage of being compatible with word processors.
  • At the present writing (06/26/2006), OpenOffice has the problem that when you load RTF (or DOC) files with linked rather than embedded graphics, the URL of the graphics will be messed up and so the graphics just show up as tiny dots.  So you need to process the RTF files you've created by loading them in OpenOffice, finding all of the graphics, and correcting the URLs.  Save the files in native OpenOffice format (SXW for version 1 or ODT for version 2), or else the graphics will get messed up again the next time you load the files.
  • Load the later of the two document versions, "MyProject-20051215.documents/SVCP" (.SXW or .ODT) into the Open Office word processor.
  • Use the Open Office menu function Edit/CompareDocuments and, from the dialog that appears, select the earlier of the two document versions, "MyProject-20050125.documents/SVCP" (.SXW or .ODT). 
  • Like magic, Open Office will show all of the changes between the two revisions as markup to the new revision:  new text is underlined, old text is struck out, and a change bar appears in the margin.
  • What you do from here is up to you:  you can export the document to PDF (another great feature of Open Office!), save it in MS Word format, print it, etc.

MS-Word Method

Sadly, the MS-Word method is a little easier, because Word doesn't mess up the graphics as I described above, and so you don't have to correct them.  Basically, just follow the same steps, without correcting the graphics, but use MS-Word instead.  MS-Word's document-compare feature is under Tools/TrackChanges.

Some Additional Information

The explanation below is largely obsoleted by the information in the box above, but it might prove helpful to somebody, so I'm retaining it ...

While Do178Builder does not really integrate change-tracking or revision control of your DO-178B documentation, versions 11/10/2003 and later have some features that may help you with document revision control.
Sections.log is simply an ASCII file with one line for each heading in the Do178Builder XML project-file.  A line in the Sections.log file begins with a decimal number, which is depth in the project hierarchy.  It is followed by a variable number of fields which give the section numbers in the various DO-178B documents, such as "PSAC=2.1" or  "SAS=3.1".  Next, there is a field giving a 32-bit CRC for the heading's text field, in hexadecimal, such as "CRC=0xABCD0123".  Finally, there is the name of the heading, such as "NAME=System Functions". 

Here is a short excerpt from a Sections.log file:

1 PSAC=2 SAS=2 CRC=0x00000000 NAME=System Overview
2 PSAC=2.1 SCI=2 SAS=2.1 CRC=0x270AF770 NAME=Overview of the System
2 PSAC=2.2 SRD=2 SVCP=2 SAS=2.2 CRC=0x00000000 NAME=System Functions
3 PSAC=2.2.1 SRD=2.1 DD=2 SAS=2.2.1 CRC=0x00000000 NAME=TBD Title of a system function
4 PSAC= DD=2.1 SAS= CRC=0x270AF770 NAME=Description
4 PSAC= SRD=2.1.1 DD=2.2 SAS= CRC=0x270AF770 NAME=Hardware-Software Allocation

As is probably obvious, "System Overview" is a top-level heading appearing as sections 2 in both the PSAC and SAS.  "Overview of the System" and "System Functions" are sub-headings of "System Overview".  "TBD Title of a system function" is a sub-heading of "System Functions".  And so on.  If a `diff' showed that the "Description" field (which I've thoughtfully done in green) had changed, you would know immediately not only where to find this change in the Do178Builder project database (namely, under System Overview/System Functions/TBD Title of a system function/Description), but also that the change affected section of the PSAC and SAS, and section 2.1 of the SDD document.

Importing Word, Excel, or Other External Data


After people find out that documents output by Do178Builder can be converted to Microsoft Word format, the most frequent question I'm asked is "how can I convert Microsoft Word documents into Do178Builder format"?  The short answer is, "You can't!"  It doesn't take much reflection to see why this is so:  Microsoft Word is a program that's suited to adjusting the appearance of a single document, while Do178Builder is a program suited to managing the content of a set of closely interrelated documents.  There's not much overlap between the two and specifically, each of the two programs discards a lot of data needed by the other.  Therefore, data is only interchangeable between the two in a very limited sense.  You will never be able to exchange documents between the two at will.

With that said, I've recently realized that there actually is a technique for interchanging such data in a much more convenient way than I ever thought possible, and that's what I'll tell you about here.

Traditionally, the advice I've given people who want to bring Word data into Do178Builder is simply to cut-and-paste it.  In other words, open up the document containing the source data in Word (or OpenOffice or any other word processor or text editor), copy  the data you want into the clipboard with ctrl-C, and then paste it into Do178Builder with ctrl-V.  This technique works and has always been available, but has a disadvantage.  The disadvantage is that if the source material contains any formatting (such as tables, lists, italics, etc.), that formatting will be lost after copying.  That's not too important if the only effect is that you lose italics here and there, but if the effect is that a 10-page long table comes out in a mish-mash then it's pretty important.

Well, I now realize that through the magic of open-source software, it's possible to do a lot better than that.  You still have to cut-and-paste, but you can do it without losing all your formatting!  The reason this is possible is that there is readily-available open-source software which can convert Word-formatted data into reasonable if not perfect DocBook, and such DocBook-formatted data can be cut-and-pasted into Do178Builder.  

In fact, I know now of two separate methods of accomplishing this, and there may be others as well.  I'll describe both, and then give a short comparison between the two.

Pure OpenOffice.org Method

It turns out that OpenOffice.org Writer can output word-processing data in DocBook format.  So here's a rundown of the basic steps you need to follow, in either Linux or in Windows:
  1. You may want to get an up-to-date version from www.openoffice.org.  Even the 1.x series was able to to output DocBook (if the appropriate extra filters were installed), but considering that the conversion isn't flawless (and has been getting better over time), I'm sure that newer is better.  For example, version 2.4 does a slightly better job than version 2.1.
  2. Open your source document in OpenOffice.org Writer.  A large number of word-processing formats are accepted by this program, including MS Word, Word Perfect, and so forth.  Indeed, you can cut-and-paste spreadsheet data into the program, turning that data into tables, so you can effectively work with MS Excel data as well.
  3. Use Save-as to save your source document, choosing "DocBook (*.xml)" as the output format.
  4. Open the DocBook XML file just created in a text editor program such as MS Wordpad.  My personal preference is the KATE text editor found on KDE-based Linux systems.
  5. Within the text editor, locate the tables, itemized lists, or whatever fancy stuff you're interested in, and paste it into Do178Builder, putting the whole mess between <docbook>...</docbook> tags as described above.  Some editors (such as KATE) allow you to view the XML in a treelike structure in which you can contract the levels that don't interest you, and this is a great help is figure out what portions you need to copy.  But realize that the document structure—how the documents are divided into sections—must be controlled by Do178Builder, so with any given cut-and-paste you should only paste material from within a single document section.

ooo2dbk Method, with OpenOffice.org

There is a separate method involving a program known as ooo2dbk, which was based on work originally done by Eric Bellot.  (I have not tried Bellot's program, which is known as OOo2sDbk and is still available.  However, ooo2dbk appears to me to be easier to set up, and supposedly has extensions that Bellot's program does not.  If anyone wants to try ooo2sdbk for themselves and let me know, I'd be happy to hear about it.  All of the documentation is in French.)    It is apparently possible to run ooo2dbk in Windows, but it's frankly a mystery to my how you'd be expected to do so, and consequently I don't care to offer any advice on that subject.  So the description here assumes that you are using Linux.
  1. First, download and install ooo2dbk.  [My guess is that installation is probably easy in Debian and Ubuntu, which I haven't tried but it's not that easy on other platforms.  Not that it's really difficult, or even time-consuming, but may not be pleasant for you if you're not an old hand at this kind of thing.  Firstly, this seems to be a project that lacks any central website—as far as I can see—so there's no obvious place from which to download it, which is why I've given you no link for it.  But if you simply google for "ooo2dbk", you can locate both rpm and Debian packages for running it in Linux.  I personally used the rpm package, and even that gave me problems since the rpm I was using hardcoded the usage of Python 2.3, which is neither the most current version of Python, nor the one installed on my computer.  I was actually using Python 2.4, and to make it work I had to use the command "sudo ln --symbolic /usr/lib/python2.4 /usr/lib/python2.3" prior to installing the rpm package, to fool the installation script into thinking that Python 2.4 was really Python 2.3.  That trick will probably work on any version of Python >2.3, and if you google it you can find tips on making it work for Python <2.3.]
  2. Make sure that the ooo2dbk program is available in your PATH, and that it is marked as an executable file.
  3. To prepare your text, begin by following steps 1 and 2 under the heading "Pure OpenOffice.org Method" above.
  4. Use Save-as to save your source document from OpenOffice, choosing "OpenOffice.org 1.0 Text Document (.sxw)" as the output format.
  5. Use ooo2dbk to convert your OpenOffice .sxw file to a DocBook .xml file.  For the sake of argument, if your document was called "test.sxw", you could use the command "ooo2dbk --article --dbkfile=test.xml test.sxw ".  Alternatively, you could use "--book" instead of "--article", but I doubt that it matters much.
  6. Import into Do178Builder by following steps 4 and 5 under the heading "Pure OpenOffice.org Method" above.

Pros and Cons

Now, neither of these two techniques is totally without its frustrations.  The main frustration is that anything you put between <docbook>...</docbook> tags has to consist of correct DocBook commands that are consistent with the version of DocBook you happen to be using (i.e., DocBook-SGML 3.1 or DocBook-XML 4.x), and the DocBook XML output by the methods described above is not always correct or consistent with our purposes.  Another (lesser) frustration is that plain text which you could perfectly well have pasted directly from the word processor without any problem at all will be enclosed in <para>...</para> tags if you paste it from the DocBook XML, forcing you either to manually remove those tags or else to artificially enclose plain text within <docbook>...</docbook> tags when they aren't really needed.  So you may have tweak the results a little.  In fact, I've made a number of adjustments to Do178Builder just for the purpose of working around such difficulties, and (I imagine) will continue to do so. 

Nevertheless, the procedure works amazingly well in spite of these little quirks, and can be a great time-saver if you need to incorporate data supplied by someone else or convert legacy documentation into a Do178Builder environment, and is certainly far superior to manually converting a large quantity of data.

Here's a brief comparison between the two techniques, as well as a list of some of the shortcomings I've observed in them.  Realize this is not an exhaustive list, but simply my observations after recent conversion of a relatively complex document that was full of tables and lists into Do178Builder format.

Pure OpenOffice.org (2.1 and 2.4)
ooo2dbk (1.3.5) with OpenOffice.org
Overall comparison
Easier to install and use, particularly on Windows
Noticeably (but not overwhelmingly) superior results.
Emphasis (italics or boldface)
Discards, so that the resulting text is simply normal like this sentence. Preserves.
Fixed-width fonts (such as this), typically used in software documentation for code fragments.
Discards, so that the resulting text is simply normal like this sentence.
Discards, so that the resulting text is simply normal like this sentence.
Numbered lists, such as this:
  1. First
  2. Second
  3. Third
Bulleted lists, such as this:
  • First
  • Second
  • Third
Turns into numbered lists.
Turns into numbered lists.
Simple tables, such as this:
Col 1
Col 2
Preserves pretty well, except always indicates that the number of columns is 3, which means the number of columns always has to be tweaked in the DocBook markup afterward.

Preserves pretty well, except that it indicates the width of the columns in "inch", which is not a legal unit—it should be "in".  So the DocBook markup has to be tweaked manually to fix this.

Also, lots of markup like "<?border-left 0.0007inch solid #000000?>" is inserted to control the table borders, and this kind of markup could conceivably give your DocBook parser problems.  Or at least, it seems strange to me.
Tables with merged horizontal cells, such as this:
Col 1
Col 2

Preserves, subject to the "simple table" frustrations mentioned above.
Preserves, subject to the "simple table" frustrations mentioned above.
Tables with merged vertical cells, such as this:
Col 1
Col 2

Messes them up.  OpenOffice 2.1 messes it up very badly, so that manually repairing the DocBook is somewhat frustrating.  OpenOffice 2.4 messes it up in a way that's relatively simple and painless to repair manually.
Messes them up, but in a way that's relatively simple and painless to repair manually.

This page was last modified by Ron Burkey on 2009-02-03. Contact the Birds Project.