A Brief Tutorial
Cut and Paste
Some Newer Features
Modifying the DTD
Importing Word, Excel, or Other External Data
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.
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.
|-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,
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
||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
||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
||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
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
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 ™ 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
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:
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:
||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.
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
Here's the basic screen you'll see in editing the development data, with some annotations I've added in red:
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:
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:
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.
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.)
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
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
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
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:
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.
... 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
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
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.
OpenOffice.org (2.1 and 2.4)
(1.3.5) with OpenOffice.org
||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.
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:
|Bulleted lists, such as this:
into numbered lists.
into numbered lists.
|Simple tables, such as this:
|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
should be "in". So the DocBook markup has to be tweaked manually to
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:
|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:
|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.