## export_boxsym

Makes a map of the sheet level terminals of a given hierarchic child sheet and exports a boxsym (in the format of boxsym-rnd) that represents a the child sheet as a symbol usable in a parent sheet. Terminals of the symbol match the terminals of the child sheet.

### Attribute usage

The following attributes of sheet level terminal objects are interpreted by the plugin:

attr key | mandatory | description
--- | --- | ---
name | yes | name of the terminal in the resulting symbol
boxsym/loc | no | specify which side of the boxsym the terminal should go: left, right, top or bottom
boxsym/grp | no | arbitrary string for grouping terminals in the resulting symbol
boxsym/num | no | override automatically generated pin number
boxsym/prio | no | integer priority value for sorting terminals

### Terminal sorting and location

Each terminal is put into one of 4 lists depending on which side of the boxsym the terminal would end up on (left, right, top or bottom). If the input terminal has a boxsym/loc attribute, that specifies the side, otherwise the plugin picks the side the input sheet terminal is closest to on the input sheet:

- if the terminal is in the top 10% of the sheet, it goes to the top side of the symbol
- else if the terminal is in the bottom 10% of the sheet, it goes to the bottom side of the symbol
- else if the left extent of the terminal is in the left 50% of the sheet, it goes to the left side of the symbol
- else the terminal goes to the right side.

Once all input terminals are collected into the corresponding per side list, the lists are each sorted. The sorting algorithm uses multiple attributes and properties of input terminals:

- first terminals are sorted into groups by their boxsym/grp attribute; terminals without this attribute are put into a single "empty group name" section
- then the groups are each sorted by priority in ascending order; if boxsym/prio is not specified, the original geometric ordering of input terminals (along the given side) is considered
- when two terminals are in the same group with the same priority value, they are sorted by terminal name

The by-grp and by-name sorting is done as normal alphanumeric sorting.

In-group priority sorting: when boxsym/loc is not specified, the normal priority value of a terminal is assigned from 0..1000 depending on the position of the input terminal along the given edge (e.g. for a top side terminal the leftmost x coordinate of the input terminal determines prio). This priority is overridden by the optional user supplied boxsym/prio value, which is not restricted to the 0..1000 range.

When boxsym/loc is specified the default priority is set to 500, regardless of any coordinates of the input terminal. In other words, without boxsym/loc the plugin extracts side and ordering info from input terminal coordinates but with boxsym/loc set input geometry is ignored in all regards.

Note: the actual numeric values are used only for sorting, they are not directly proportional to the final coordinates of the terminals within the symbol, they only affect the order of terminals.

Sorted terminal pinnum is assigned automatically and sequentially per side, from 100, 200, 300 and 400 respectively, unless the pin number is overridden by boxsym/num, which is an arbitrary string, does not need to be a number. When boxsym/num is specified for a terminal, it does not affect the numbering sequence of other terminals; that is if originally a side had terminal pinnums 100, 101, 102 and 103 and the input terminal corresponding to 101 gets a boxsym/num=8, the symbol will have pin numbers 100, 8, 102, 103 on that side.

How to use this in practice:

- decide whether you want to explicitly specify symbol terminal locations or want to leave for sch-rnd to figure (implicit location)
- with the implicit location method:
  - arrange your terminals on the child sheet so they are always close to one of the sheet edges
  - for left and right side, do not use the top and bottom 10% of the sheet for placing terminals (or in general: avoid placing terminals in the 10% corner of the sheet)
  - if you zoom out the terminals on the sheet should generally have the same arrangement the dinal symbol will have
  - this sometimes means a sheet terminal is where the symbol will have it (e.g. "second terminal from the top on left side"), not where it is used within the child sheet (e.g. "in the middle of the sheet"); in this case use sheet local netnames (or wires) to make the connection
- with the explicit location methid:
  - place sheet terminals within the child sheet wherever the circuity use them
  - always set boxsym/loc on the sheet terminal to speficfy which side of the symbol the terminal should go
  - this will make sch-rnd not trying to look at sheet terminal position for ordering so always set boxsym/prio on the sheet terminal to speficfy the order of terminals in the generated symbol
  - if there are semantical/functional grouping of terminals, also set the boxsym/grp, group name should be an arbitrary name related to the functionality of the group of terminalks; in this case prio value sorts terminals within groups only

### "Singe click" operation

When the export plugin is invoked from the GUI export dialog (e.g. using the {f e} hotkey), it offers a "Generate symbol!" button that:

1. runs the export (not overwriting outfile but using a randomly chosen temporary file that gets automatically removed)
2. executes boxsym-rnd in the background on the resulting file
3. loads the output symbol generated by boxsym-rnd into the current paste buffer
4. activates the paste buffer tool

This should be done while the hierarchic child sheet is active; the new symbol should be placed on the hierarchic parent sheet.

Note: placing the symbol on the child sheet will cause a compilation error as it will result in infinite recursion of the sheet having itself as a child sheet. The recursion is eventually terminated by the compiler with real long component paths reported in the message log.

### Omit and DNP

The plugin ignores display/omit or display/dnp.