diff --git a/doc/xschem_man/tutorial_xschem_libraries.html b/doc/xschem_man/tutorial_xschem_libraries.html index 3cd19c88..92c9b9fa 100644 --- a/doc/xschem_man/tutorial_xschem_libraries.html +++ b/doc/xschem_man/tutorial_xschem_libraries.html @@ -19,7 +19,7 @@ p{padding: 15px 30px 10px;}

TUTORIAL: Manage XSCHEM design / symbol libraries

- There are 2 ways to describe symbols in xschem,
+ There are various ways to describe symbol locations in xschem,

In the first approach a 'npn.sym' symbol placed in a schematic will be @@ -47,6 +53,22 @@ p{padding: 15px 30px 10px;} examples, any dir name is allowed for xschem_library/ and devices/)

+

+ In the third approach 'npn.sym' or some other dir/symbol.sym will be searched in all + path elements listed in XSCHEM_LIBRARY_PATH, by appending the symbol reference to each path element + until a file is found. the first match is used. This is the reason you should put the deepest directories first + in XSCHEM_LIBRARY_PATH. If /a/b/c/dir/symbol.sym is inserted in the design and + XSCHEM_LIBRARY_PATH contains + the following definitions:
+ set XSCHEM_LIBRARY_PATH /a/b/c /a/b /a
+ the symbol reference will be just dir/symbol.sym, since appending the symbol reference to the first path an + existing file is found. + If the following definition for XSCHEM_LIBRARY_PATH is given instead:
+ set XSCHEM_LIBRARY_PATH /a /a/b/ /a/b/c
+ then the symbol reference will be /b/c/dir/symbol.sym since the first path component was found in + the absolute path of the inserted symbol and the only matching prefix is removed from the relative symbol reference that will + be saved in the schematic. +

The first approach is preferred by pcb hobbysts, people working on small designs. @@ -56,10 +78,18 @@ p{padding: 15px 30px 10px;} or 'libgroup/libname/symname.sym' (2 level directory specification in symbol references) instead of just 'symname.sym'

-

- In any case the real path of the symbol reference is obtained by prepending - the XSCHEM_LIBRARY_PATH paths to the symbol reference until the resulting file is found in - the machine filesystem. +

+ SYMBOL LOOKUP (ie when loading a schematic):
+ The absolute path of the symbol reference is obtained by appending + the symbol reference to the XSCHEM_LIBRARY_PATH paths in the order they are listed until the resulting file is found in + the machine filesystem. The first match is used.
+ SYMBOL INSERTION (ie when drawing a schematic and inserting a component):
+ The relative symbol reference that is saved in the schematic file is obtained by removing the first occurrence + of a matching path prefix + from the ones listed in XSCHEM_LIBRARY_PATH in the order they are listed. The first matching prefix + is used to determine the relative symbol reference. This is the reason deepest path elements must be + listed first in XSCHEM_LIBRARY_PATH if you want the shortest possible symbol relative reference to saved in + the schematic file.