--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ueda/doc/bom_model.txt	Mon Jul 20 00:24:37 2015 +0000
@@ -0,0 +1,131 @@
+Bill of Materials (BOM) handling in uEDA
+
+There are a number of reasons why one may want to have a BOM for a board design:
+
+* To have a list of all components outside of schematic drawing files
+* To have a list of PCB land patterns for pre-layout (see prelayout.txt)
+* For purchasing or other part procurement
+* For handing to assemblers (those who populate the parts on the board)
+* For quick reference
+
+Although one is often tempted to get away with keeping the "BOM" information in
+his head, a formal BOM is a good thing to have.
+
+OK, so we are going to have a BOM.  But what exactly is the BOM in precise
+terms, and what is its format?  uEDA provides several different facilities for
+BOM handling.
+
+The MCL
+
+Whether or not you are interested in any of the other BOM formats, you have to
+have the MCL.  It is a critical part of the design source code in the uEDA flow
+model.  It's a human-created and human-edited text file described in great
+detail in mcldoc.txt.
+
+Having a simple and intuitive text-based format, MCL can be readily viewed and
+printed.  As it contains the complete information about all components in the
+design, i.e., all BOM information, it is in itself a type of BOM.  It is in a
+way "the ultimate BOM".  There are, however, a few situations in which other
+BOM formats are desirable.
+
+Procurement BOM
+
+You write the MCL for your design.  For each component you enter all the
+attributes that you may need for procurent: manufacturer,
+manufacturer_part_number, vendor, vendor_part_number, etc.  But now it's
+actually time to order the parts.  What quantity of what part numbers do you
+order?  All necessary information is in the MCL, but it isn't at all obvious
+for filling out order forms.  One really needs a distilled BOM for procurement.
+
+The ueda-mkbom utility generates a procurement-oriented BOM from the MCL.
+First it reads the MCL and makes note of all components that have been reduced
+to parts.  (Components that haven't been reduced to parts are ignored, though
+the user can request that a warning be issued.  You need to reduce all
+components to parts for this function to be useful, see mcldoc.txt for the
+details.)  All multiple instances of each part are tallied together.
+Finally, output is emitted which is centered around parts with a quantity for
+each, rather than around reference designators.  (A list of refdes'ed components
+using each part can optionally be emitted.)  Each entry is given a heading and
+usually some comment lines based on part attributes from the MCL which are
+deemed relevant to the procurement BOM.  See mcldoc.txt for the details.
+
+One can generate procurement BOMs for different population options, see below.
+
+The procurement BOM generated by ueda-mkbom is plain text formatted on the
+assumption of 80 columns of fixed character spacing.  It is thus suitable for
+both online viewing and printing.
+
+Short BOM
+
+For purposes other than procurement of parts, component reference designators
+do matter, and a BOM organised and sorted by the component refdes is the right
+format.  MCL is such a format, and oftentimes it serves quite well.
+
+Sometimes however, it is desirable to have a "short BOM" that is ordered by
+the component refdes like the MCL, but follows a tabular format with one line
+per component and with columns corresponding to a few attributes deemed most
+useful.
+
+The ueda-shortbom utility generates such a "short BOM" with 4 columns: refdes,
+manufacturer, part number and description.  The manufacturer and description
+columns are taken from the identically named MCL attributes; the part number
+column is taken from the manufacturer_part_number= attribute if one is defined,
+otherwise the device= attribute is used instead.  If neither attribute is
+defined, the string "unknown" is substituted.  The same holds for the
+manufacturer column.  The description column is left blank if no description=
+attribute is defined.
+
+The intent is that the MCL would be used directly only by the board designer
+himself, who would of course be intimately familiar with the UNIX environment,
+the workings of uEDA and its file formats, and the way his particular MCL is
+structured, whereas the short BOM would be given to lab technicians and others
+who are not UNIX-based intellectual creators.
+
+ueda-shortbom can generate plain text output that is directly usable for viewing
+and printing in a fixed character spacing environment, but it usually ends up
+needing more than 80 characters per line and thus a pain to work with.
+ueda-shortbom can also produce output with columns separated by ASCII tab
+characters irrespective of field widths; such output is useful for post-
+processing.  UNIX tbl(1) and troff(1) can be used to produce a very pretty
+hard copy (PostScript) version of the short BOM.
+
+Assembly BOM
+
+An assembly BOM is exactly the same as the short BOM described above, but has
+one difference: if a component is to be socketed, the information put in the
+corresponding columns of the assembly BOM is that for the socket part, rather
+than for the component to be pushed into the socket.  The assembly BOM is thus
+exactly what you need to give to those who will be stuffing parts on your board
+and running it through the reflow oven.
+
+An assembly BOM is generated by the ueda-shortbom utility with the -a option.
+Since one would need to generate different assembly BOMs for different
+population options (assuming that the document is intended for those who will
+follow it blindly), ueda-shortbom supports population options as well.
+See the ueda-shortbom(1) man page for details.
+
+If your design uses no socketed parts and no population options, the short BOM
+and the assembly BOM would be identical.
+
+Population options
+
+uEDA supports designs with population options, i.e., ones in which some
+components may or may not be populated as a manufacturing option.  They are
+described in this document because the BOM is really the only part of the uEDA
+flow for which population options matter.  The PCB obviously has to have
+footprints for all components that may ever be populated on it and the
+schematics normally show the interconnections for all possible components as
+well.  The BOM is the only part that is made in multiple versions for different
+population options.
+
+In order to support population options, each component in the design (i.e., in
+the MCL) is assigned to a numbered population group.  Population groups are
+identified by integers and a component is assigned to a given population group
+via the population_option= attribute in the MCL.  Components without this
+attribute are assigned to population group 0, the default.
+
+When generating a BOM for a given population option, specify the list of
+population groups to be included (see ueda-mkbom(1) and ueda-shortbom(1)).
+The default population option consists of population group 0, i.e., running
+ueda-mkbom or ueda-shortbom without any options counts only those components
+which do not have a population_option= attribute.