--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ueda/doc/overview.txt	Mon Jul 20 00:24:37 2015 +0000
@@ -0,0 +1,117 @@
+Welcome to uEDA, an EDA suite for UNIX!
+(for board level design)
+
+The uEDA project has been inspired by gEDA (http://geda.seul.org/) and intends
+to do for the UNIX culture what gEDA has done for the GNU/Linux culture.
+
+First a disclaimer is in order.  Different people write Free Software based on
+different motivations.  Like most Free Software written by Michael Sokolov,
+uEDA is based on the "scratching a personal itch" development model.  In other
+words, I have written the software to satisfy my own internal need, and I
+don't really care if you like it or not.  Please keep this observation in mind
+as you discover that it lacks some feature you need or want, or that its flow
+is not to your liking.  I have written it to satisfy *my* needs.  I could have
+written it for myself and never released it, but I believe in sharing and
+letting others have what I have (though whether they like it or not is not my
+concern).  So there you have it.
+
+uEDA has been written by a hard-core UNIX programmer (as in real UNIX in 4
+capitals running on Big Iron, not the cheap modern crap), and is designed to
+allow one to design hardware using not only a UNIX host environment, but also
+the intellectual creation flow model associated with the UNIX culture, one that
+revolves around the concepts of source code files, generated files and
+Makefiles.  I won't explain these concepts here; if they are foreign to you,
+uEDA is not for you.
+
+Note my choice of words: "the intellectual creation flow model" of the UNIX
+culture, rather than "the UNIX programming model".  I fully acknowledge that
+hardware engineering is very different from SW eng, and uEDA does not try to
+"make hardware like software".  However, the UNIX culture's intellectual
+creation flow model has already been extended many times to various intellectual
+products other than software.  Consider for example an author writing a book in
+troff.  The troff source files take the place of C source code, PostScript or
+other typesetter files for the print house take the place of the executable
+binary, and a Makefile is used to drive the flow.  The author edits the book
+source files with vi and regenerates the generated files on each iteration by
+running 'make'.  It isn't software, but the intellectual creation flow is
+virtually identical.  uEDA applies the same model to hardware design.
+
+So what is the source code for hardware, and what is the final product that
+should be generated by 'make all'?  Well, the ultimate final product is the
+physical board which you can hold in your hand, but the most "final" product
+that can be made on a computer would be a set of gerber files for PCB
+fabrication, a bill of materials (BOM) for the purchasing or other procurement
+of parts, and a set of assembly instructions to be handed to the assembly line
+workers who populate the parts on the board.  The starting source code would
+be the schematic design.
+
+The ultimate UNIX-model EDA suite would thus be one that can generate all final
+manufacturing files from the schematic source code with a single 'make' command.
+uEDA is almost there, except for the layout step.
+
+The problem is that even with the best EDA technology PCB layout still involves
+considerable human effort, and is thus not something that can be done by a batch
+program that works from stdin to stdout.  Therefore, the PCB layout file is
+subject to human editing and is not just an intermediate file between schematics
+and gerbers like a .o file in the software compilation flow.
+
+The uEDA solution is to view the job of designing a board as two separate
+intellectual creation jobs, each with its own UNIX-model Makefile-driven flow.
+These two jobs are the design and the layout.  uEDA addresses the design.  The
+uEDA suite does not really get involved in the layout, but is designed with the
+assumption that the layout will be done with the free & open source PCB program
+(http://pcb.sourceforge.net/).  The two are connected by the "pre-layout" step
+described in prelayout.txt.
+
+(Note that such separation of the design and layout jobs is additionally
+ supported by the fact that in many engineering companies these jobs are done
+ by different people.)
+
+In the design phase addressed by uEDA, the source code is the set of schematic
+sources and the Master Component List (MCL), a human-edited text file documented
+in mcldoc.txt.  The products that can be generated from these sources with a
+Makefile are:
+
+* Printable schematics (PostScript or PDF) for documentation;
+* A set of "pre-layout materials" for handing to the PCB layout person;
+* Bill of Materials (BOM) in different formats for part procurement, for
+  assembly and for quick reference.
+
+In the layout phase the .pcb that is both read and written by the PCB GUI is the
+source code, and pcb can be invoked from the command line without the GUI to
+generate gerbers, PostScript prints of the layout and other product files from
+it; those generations can be codified in a Makefile, once again creating the
+traditional UNIX flow.
+
+Design source code structure
+
+The source code for a board design in uEDA consists of 3 major parts:
+
+* Information about all components on the board;
+* Electrical interconnect information: how these components are interconnected
+  with nets;
+* Graphical information used to construct PostScript prints of the schematic
+  sheets.
+
+The core philosophy of uEDA is that these 3 kinds of information should be kept
+as orthogonal as possible.  Component information is stored in the Master
+Component List (MCL) documented in mcldoc.txt, whereas the interconnect and
+graphical schematic information is stored in the schematic sheets (.usch files)
+documented in uschemlang.txt.  Although the electrical interconnect and
+graphical information are stored together, the uschem language is designed to
+provide a high degree of orthogonality between the two.  Schematic sheets can
+be either graphical or non-graphical.
+
+Further reading:
+
+bom_model.txt	Describes the uEDA approach to BOM handling
+drc.txt		Describes the means for helping ensure a match between the
+		actual electrical interconnect and the graphical representation
+graphsyms.txt	Information about graphical symbols used on schematic sheets
+mcldoc.txt	Master Component List document
+netlisting.txt	Describes uEDA's handling of netlist information
+prelayout.txt	Describes what I mean by "pre-layout"
+psfeatures.txt	Describes the features available in the PostScript prints of
+		schematic sheets made with uschem-print(1)
+uschemlang.txt	uschem language document
+*.1		Man pages for all uEDA utilities