Skip to content
This repository has been archived by the owner on Oct 26, 2021. It is now read-only.

Symbol field and metadata handling in 5.1 #446

Closed
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions content/klc/S6.2.adoc
Original file line number Diff line number Diff line change
@@ -1,9 +1,27 @@
+++
brief = "Component fields must be filled appropriately"
brief = "Symbol and alias fields and metadata filled out as required"
+++

. *Reference* field is selected appropriately for the symbol and is _visible_
. *Value* field contains the name of the symbol and is _visible_
. *Footprint* field contains footprint link for atomic parts, and is empty for generic parts. It must be _invisible_
. *Datasheet* field is left empty, and is _invisible_
. The symbol contains no other custom fields
. *Footprint* field contains footprint link for fully specified symbols and must be _invisible_
.. The footprint field must be empty for generic symbols
. *Datasheet* entry [1] is filled out, and is _invisible_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This style of using a numbered reference in brackets is not used elsewhere in KLC that I can find. I see a a separate section below without any linking or sub-bullets. Do you want to introduce this new style?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a footnote for adding additional information. We do not have a footnote anywhere else in the KLC (it was not necessary to clarify things like that in other rules. As this is really one of the few places where we need to explain strange KiCad behaviour)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not clear to me why this needs to be done this way instead of just being underneath the Datasheet section. But OK.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wanted to keep this rule short so that users read it. What is below basically gives additional clarification for users who are still interested.

I learned with bad experiences that users turn their brain off after a few sentences so the most important info should be kept short. Adding additional stuff for the few users that are interested is still worth it. Especially if we ever get a discussion in a pull request because then we can point to this additional information.

. The symbol contains no other custom fields

Additional documentation is provided via two other fields:
[start=6]
. **Description** field contains comma-separated device information
.. For symbols with a default footprint, the simplified footprint name should be appended to the description e.g. `SOIC-8`
.. Part name should not be duplicated in the description field
. **Keywords** field contains space-separated keyword values. These values are used to assist in part searching and should not include filler words

{{< klcimg src="symbol_metadata" title="Symbol metadata example" >}}

**Aliases** define their own values for the datasheet link, description and keyword entries.

{{< klcimg src="alias_metadata" title="Alias metadata example" >}}

---

_[1]: KiCad 5.x and earlier have two places to store the datasheet link. It can be in the `.lib` file once per symbol or in the `.dcm` file allowing different datasheets per alias. Having different datasheets for aliases only works if the `.lib` entry is left empty. The datasheet entry in the main symbol metadata view is linked to the dcm entry since version 5.1.x._
13 changes: 0 additions & 13 deletions content/klc/S6.3.adoc

This file was deleted.

2 changes: 1 addition & 1 deletion content/libraries/klc.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ aliases = [ "/klc/" ]
toc::[]


**link:/libraries/klc/history/[Revision: 3.0.24]**
**link:/libraries/klc/history/[Revision: 3.0.25]**

---

Expand Down
4 changes: 4 additions & 0 deletions content/libraries/klc_history.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,10 @@ url = "/libraries/klc/history/"
+++

---
== 3.0.25 - 2020-01-13
* Update section about symbol documentation to KiCad 5.1 GUI (combined S6.2 and S6.3)


== 3.0.24 - 2019-11-16
* Clarify rule for parts with toleranced dimensions
* Fab comes from the nominal component dimensions (F5.2)
Expand Down
Binary file added static/img/klc/alias_metadata.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/klc/symbol_metadata.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.