kicad-developers team mailing list archive

[hauptmech <hauptmech@xxxxxxxxx>]

Attached

On 24/06/18 02:46, Wayne Stambaugh wrote:
> Hey hauptmech
>
> For the most part I'm fine with these changes.  I think that the first
> two paragraphs (sentences) in the "Schematic Symbol Libraries" section
> of the version upgrade document could be merged into a single paragraph
> since they are related.
>
> If no one else objects to these changes, please create a merge request
> and I'll merge them into my repo and push them upstream today or tomorrow.
>
> Thanks for the help.
>
> Cheers,
>
> Wayne
>
> On 06/23/2018 12:15 AM, hauptmech wrote:
> > Hi Wayne,
> >
> > Really awesome that you are creating this documentation!
> >
> > A couple thoughts:
> > * No one reads documentation unless they have to. Usually after stabbing
> > in the dark for a while.
> > * If one has to read documentation, one wants it short and to the point.
> > * Whatever basic knowledge you want the reader to have about how kicad
> > works, they won't have it.
> >
> > With that in mind I did a little example editing with the following goals:
> >
> > * Link to any info that is a requirement for understanding this
> > document. If you can't find any existing documentation to link to,
> > that's a good clue that we need to fill in more info locally.
> > * Leave out as many extra words as possible.
> >
> > https://github.com/hauptmech/kicad-doc/blob/master/src/kicad/kicad_upgrading_from_v4_to_v5.adoc
> >
> > https://github.com/hauptmech/kicad-doc/blob/master/src/eeschema/eeschema_symbol_library_table.adoc
> >
> >
> > It's not formatted as a patch because I only edited a few paragraphs,
> > and in those I rewrote things completely as an example of the above.
> >
> >
> >
> >
> > On 23/06/18 04:10, Wayne Stambaugh wrote:
> > > I pushed the v5 upgrade document to my personal repo[1] on git hub.  I
> > > made it part of the KiCad documentation but I don't have a strong
> > > opinion about where to add it.  This just seemed like the most logic
> > > place.  Please review it when you get a chance.  If you find any issues
> > > let me know, send me a patch, or submit a pull request against my doc
> > > repo.  Keep in mind that this document is only to detail the changes
> > > that will effect project compatibility with older versions of kicad and
> > > the perils of symbol remapping.  Thanks in advance for the help.
> > >
> > > Cheers,
> > >
> > > Wayne
> > >
> > > [1]:
> > > https://github.com/stambaughw/kicad-doc/blob/master/src/kicad/kicad_upgrading_from_v4_to_v5.adoc
> > >
> > >
> > > _______________________________________________
> > > Mailing list: https://launchpad.net/~kicad-developers
> > > Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> > > Unsubscribe : https://launchpad.net/~kicad-developers
> > > More help   : https://help.launchpad.net/ListHelp
> >
> >
> > _______________________________________________
> > Mailing list: https://launchpad.net/~kicad-developers
> > Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> > Unsubscribe : https://launchpad.net/~kicad-developers
> > More help   : https://help.launchpad.net/ListHelp
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp


>From 870401845b1bb785dcb7b3ff3d40bec185921ac4 Mon Sep 17 00:00:00 2001
From: Hauptmech <hauptmech@xxxxxxxxx>
Date: Sat, 23 Jun 2018 13:36:38 +1200
Subject: [PATCH] Simplify language and add some background info the reader may
 lack.
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="------------2.17.0"

This is a multi-part message in MIME format.
--------------2.17.0
Content-Type: text/plain; charset=UTF-8; format=fixed
Content-Transfer-Encoding: 8bit

---
 .../eeschema_symbol_library_table.adoc        | 22 +++---
 src/kicad/kicad_upgrading_from_v4_to_v5.adoc  | 73 ++++++++++---------
 2 files changed, 47 insertions(+), 48 deletions(-)


--------------2.17.0
Content-Type: text/x-patch; name="0001-Simplify-language-and-add-some-background-info-the-r.patch"
Content-Transfer-Encoding: 8bit
Content-Disposition: attachment; filename="0001-Simplify-language-and-add-some-background-info-the-r.patch"

diff --git a/src/eeschema/eeschema_symbol_library_table.adoc b/src/eeschema/eeschema_symbol_library_table.adoc
index fc60bb42..18a3a753 100644
--- a/src/eeschema/eeschema_symbol_library_table.adoc
+++ b/src/eeschema/eeschema_symbol_library_table.adoc
@@ -1,14 +1,17 @@
 == Manage Symbol Libraries
 
-Symbol libraries need to be made available in order to create schematics.
-The manner in which this is accomplished varies according to the version
-of KiCad being used.
+Symbol libraries hold collections of symbols used when creating schematics. Each symbol
+in a schematic is uniquely identified by a full name that is composed of a library nickname
+and a symbol name. An example is `Audio:AD1853`.
 
 === Symbol Library Table
 
-As of November 2017, Eeschema uses a new library management tool based on
-*_symbol library tables_* which is identical in design to the footprint
-library table used in CvPcb and Pcbnew.
+The symbol library table holds a list of all library files KiCad knows about.
+The symbol library table is constructed from the global symbol library table
+file and the project specific symbol library table file.
+
+When a symbol is loaded, Eeschema uses the library nickname, `Audio` in our example, to lookup
+the library location in the symbol library table.
 
 The image below shows the symbol library table editing dialog which
 can be opened by invoking the ``Manage Symbol Library Tables'' entry
@@ -16,13 +19,6 @@ in the ``Preferences'' menu.
 
 image::images/en/options_symbol_lib.png[scaledwidth="80%",alt="sym lib table dlg"]
 
-The symbol library table is used to map a symbol library of any supported
-library type to a library nickname. *This nickname is used to look up
-symbols* instead of the previous method which depended on library search
-path ordering. This allows Eeschema to access symbols with the same name in
-different libraries by ensuring that the correct symbol is loaded from the
-appropriate library.
-
 ==== Global Symbol Library Table
 
 The global symbol library table contains the list of libraries that are
diff --git a/src/kicad/kicad_upgrading_from_v4_to_v5.adoc b/src/kicad/kicad_upgrading_from_v4_to_v5.adoc
index cc0929a2..5c716e03 100644
--- a/src/kicad/kicad_upgrading_from_v4_to_v5.adoc
+++ b/src/kicad/kicad_upgrading_from_v4_to_v5.adoc
@@ -26,25 +26,32 @@ possible path when upgrading to version 5 of KiCad.
 Schematic symbol libraries are no longer accessed using a symbol
 (referred to as components in version 4) look up list.  Symbol
 libraries are now managed by a symbol library table that behaves
-similarly to the footprint library table.
-This represents a significant change in the way symbol libraries
-are defined and accessed.
-
-This change resolves the problems created by
-symbol library ordering in Eeschema.  It also provides some new
-features such as platform independence and lazy library loading.
-KiCad users should be familiar with the design and concept so this
-is not a tutorial on how to configure your symbol library table.
-It is important information that you need to properly convert
-your existing schematics to use the symbol library table.
+similarly to the footprint library table.  This change is a significant
+improvement, but some schematics may need manual intervention when being
+converted to version 5.
+
+In previous versions, KiCad used a list of library files to search when
+locating symbols in the eeschema file. When locating a symbol, each path
+would be searched and the first library that held the symbol name
+would be used.
+
+From v5, KiCad symbol names are prefixed with a nickname, and a
+link:../eeschema/eeschema_symbol_library_table.adoc[lookup table matching
+nicknames to library paths] is used to locate the library which holds the
+symbol. The table is called the 'symbol library table' and built from config
+files stored in the system configuration directory and the project directory.
+
+To ugrade a KiCad project from v4 to v5, nicknames for all of the library
+files need to be created and then schematic symbol names need to be prefixed
+with the correct nickname.
+
 
 === Global Symbol Library Table.
-The first time you start version 5 of Eeschema and there is no
-global symbol library defined in the KiCad user configuration,
-Eeschema will prompt you to create a new global symbol library.
-If you do not understand why you would want to use a custom global
-symbol library table, choose the default global symbol library
-option.
+Eeschema v5 will automatically create a global symbol table when
+first started. You will be given a chance to skip this and create
+your own global symbol table by hand. You only need to do this if
+don't use KiCad symbol libraries at all. Otherwise it is easier to
+modify the automatically generated global symbol table.
 
 [NOTE]
 If you track the
@@ -55,13 +62,8 @@ library table up to date.
 
 === Symbol Library Table Mapping
 
-Much like the conversion over to the footprint library table, there
-will be issues and a learning curve.  Hopefully, familiarity with
-the footprint library table will minimize the learning curve.  The
-biggest issues will be with existing projects and users with custom
-symbol library configurations.  Some of these issues will be mitigated
-by a new symbol library table remapping feature.  This feature will
-be executed whenever a schematic is opened that has not been remapped.
+Automatic remapping of symbols will be executed whenever a
+schematic is opened that has not been remapped.
 There are a few steps you should take ahead of time in order for the
 remapping to be the most effective.
 
@@ -77,8 +79,8 @@ links.
 
 [WARNING]
 Remapped schematics will not be compatible with older versions of
-KiCad.  Make sure to back up project schematic and project files
-before remapping a schematic in case things go wrong. +
+KiCad.  The Remap Symbols dialog will make a backup of your schematic
+files and you should do the same if you remap manually. +
 
 1. If possible, keep version 4 of KiCad installed on your system unless
    you have never used any of the symbol libraries distributed with KiCad.
@@ -90,8 +92,10 @@ before remapping a schematic in case things go wrong. +
    will end up with broken symbol links in your schematic.  You can test
    this by left clicking on a symbol in the schematic and verifying
    that the symbol is not being loaded from the cache library.  If a
-   symbol is being loaded from the cache library, you are already skating
-   on thin ice.
+   symbol is being loaded from the cache library, Eeschema cannot find
+   your part in the system or project symbol libraries. If you need a
+   cached part to be available to other projects on your system, you will
+   need to integrate it into a system or project library manually.
 
 3. If symbol recovery is required during the remapping process, do not
    dismiss it.  Failure to recover symbols will result in broken symbol
@@ -132,13 +136,12 @@ before the symbol is mapped to this new, rescue library.
 
 === Symbol Names and Symbol Library Nickname Limitations
 
-Symbol naming now follows the same convention as footprint naming with
-one exception, spaces are not allowed in library nicknames or symbol
-names.  The colon ':' character cannot be used in symbol library nicknames
-or symbol names and forward slash '/' character is not allowed in symbol
-names.  Existing symbols containing these characters will cause issues
-with broken symbol links in schematics.  Fix any symbol names that contain
-these characters symbols that violate these naming restrictions.
+Symbol names may not contain `<SPACE>, ':', '/'`.
+
+Library nicknames may not contain `<SPACE>, ':'`.
+
+Existing symbol names with these characters must be renamed by manually editing the
+relevant schematic and library files.
 
 == Symbol Cache Library Availability
 

--------------2.17.0--