Introduction

Do178Builder is a program that
allows developers of airborne software
to do two things:

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

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.

-x=MaxSizeX
-y=MaxSizeY

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.

--no-resize-workaround

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.

-o

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.

-s=IpAddress

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.

-l=PortNumber

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.

-f=FontSize[,FontSize2]

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.

--DO-254

07/02/06 and later.

Works with DO-254 rather than
DO-178B.

--no-forward-trace

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.

--no-productname

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 NameYour
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.

--no-trace

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.

--combine-srd-sdd

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:

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.

--x412
--x42
--x43
--x44
--x45

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.

--batch

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:

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

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.

--combine-plans=Acronym

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:

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:

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

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:

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:

CiteTitle. Used for indicating the title of a work
you're citing -- usually rendered in italics. For example, "This
is specified in the <CiteTitle>Software Coding
Standards</CiteTitle>."

Command. A command typed at the keyboard.
For
example, "Next, use the <Command>DIR</Command>
command." This is the same as the A tool-button.

Function. Indicates the name of a function --
usually rendered in a fixed-width font. For example, "Use the
<Function>strlen</Function> to compute the length of a
string." Though it's a bit of a perversion, I generally use this
for all program code, and not just function names: "The
code fragment <Function>x = sin(y) + 1</Function> should do
what you want." This is the same as the {...} tool-button. See
also ProgramListing.

KeyCap. Text printed on a keyboard key, as in "hit
the <KeyCap>Ctrl</KeyCap> key."

Option. Indicates an option for a software
command. For example, "Type <Command>ls
<Option>--help</Option></Command> to find out how to
use the <Command>ls</Command> command." (Makes you think
twice, doesn't it? I think I'd leave it out!)

Optional. Indicates optional data, as in a command
that had either one or two arguments: "The syntax is
<Command>MyFunction InputFile
<Optional>OutputFile</Optional></Command>."
(Again, yikes! You won't find me doing this.)

ProgramListing. This is similar to Function,
but instead of being used inline for a function name, it can be used
for a large block of code that spans multiple lines. Typically, a
fixed-width font will be used to preserve all of the whitespace and
spacial relationships like indentation. This is also provided as
a tool-button.

Images

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:

From system requirements to high-level software requirements.

From low-level software requirements to source-code components,
or from software test cases to source-code components.

(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.

inline graphics (see the newer
features below for an easy way to use graphics)

footnotes

math

special characters

links

etc.

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:

A

B

C

D

E

F

G

H

I

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

Here is a fake "PSAC" document
demoing some of the things you can do with raw DocBook commands, and
here is the Do178BuilderXML 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.)

Inserting <?hard-pagebreak?>
will produce a page break at the point of insertion. Using this
kind of directive is contrary to the philosophy of DocBook, but
sometimes it's pretty desirable. This doesn't work everywhere,
such as in the middle of a paragraph, nor between items of an itemized
list or an ordered list. However, you should be able to insert
page breaks before or after paragraphs.

Using the tag <long-string>
allows long strings (such as long filenames) without embedded spaces to
be rendered in a more visually-appealing way in some cases. The
problem is that such strings may force some very peculiar
formatting, or even run off the edge of the page. What <long-string>
does is to make it possible for the formatter to insert a line-break at
any point in the string, and thus allow it to be split up into multiple
lines. Usage is <long-string
str="AnyLongString"></long-string>,
which unfortunately doesn't allow you to use any additional markup within the string.

Using the tag <long-ulink>
in place of the normal DocBook
tag <ulink> may
make long URLs associated with hyperlinks more visually
appealing. The problem with a URL which is very long is similar
to the problem of any other string which is very long. DocBook commands such as <ulink
href="http://www.google.com">search engine</ulink> are
rendered in PDF or RTF as "search engine
[http://www.google.com]". This particular example presents no
problem, but if the URL was very long then it could overflow the
printable area, so <long-ulink>
essentially applies <long-string>
to the URL. Note that this applies only to the URL
("http://www.google.com"), and not to the hyperlink ("search
engine"). If it is the hyperlink that is very long, then you need
to separately use <long-string>
on it. For example: <long-ulink
href="AnyLongURL"><long-string
str="AnyLongHyperlink"></long-string></long-ulink>
. By the way, <long-ulink>
has the side effect of coloring the hyperlink blue as is usual in a
browser, whereas <ulink>
does not do so.

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.

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:

Modifying the "DTD"

The various data sections, subsections, and data items appearing in the
outline dataset have been chosen to fulfill three objectives:

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;

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

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.

Since Do178Builder
outputs (by default) outputs documents into
directories that are named according to the build-date, different
versions of the DO-178B documents will generally be saved in different
but easily locatable directories. Unless, of course, two
significant document versions have been built on the same day. :-)

Do178Builder helpfully
creates a file called Sections.log at the
same time it outputs the DO-178B (SGML) documents. Sections.log
provides a map of each section in each DO-178B document to the original
section in the Do178Builder
XML database. It also provides a CRC
of the text for each section. Therefore, a simple `diff' (in
Linux, or `fc' in Win32) of the Sections.log files for two different
document versions provides a complete list of all changed sections,
referenced both to the XML project database and to the DO-178B SGML
files.

In many ways, the simplest technique for doing change tracking is
simply to `diff' the SGML files (such as PSAC.sgml) with a side-by-side
diff viewer. What I do, for example, is this:

I view the differences between the latest SGML files and those
from the last released or approved SGML files, using the side-by-side
diff viewer fldiff. (Other similar
utilities such as xdiff, xxdiff, or kompare work also, but I just happen
to like fldiff better. fldiff can show you not only which
lines of the file have changed, but also which parts of the lines,
which is very handy. Also, it can compare against files that have
been stored in cvs.
Also, it has the capability of adjusting the text size, which is very
handy if you are reviewing the changes as a group rather than as an
individual. On the other hand, it only compares one file at a
time, whereas a utility like kompare
can do a whole directory of files at once.)

From what I see in fldiff,
I then run Adobe Acrobat and highlight the changes within the PDFs of
the new documents I'm trying to get reviewed. This is much less
time-consuming than it sounds, and is very handy in helping reviewers
who just want to see the changes rather than to read the entire
documents.

(Yes, I know it would be useful to have an automated tool for
doing this, but I simply haven't done it. Volunteers?)

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".

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 2.2.1.1 of the PSAC and SAS,
and section 2.1 of the SDD document.

Importing Word, Excel, or Other External
Data

Introduction

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:

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.

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.

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.

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.

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.]

Make sure that the ooo2dbk
program is available in your PATH, and that it is marked as an
executable file.

To prepare your text, begin by following steps 1 and 2 under the
heading "Pure OpenOffice.org Method" above.

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.

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 correctDocBook 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.

Issue

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:

First

Second

Third

Preserves.

Preserves.

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

A

B

C

D

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 DocBookmarkup 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.

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.