File format documentation out-of-date

[whitis]

The documentation for Element Files (and probably
layout files as well) is outdated and does not
correctly list the fields.

Element[flags description layoutname(REFDES) value x y
text_x text_y textdirection textscale textflags]

Pin[x y thickness clearance mask drillinghole name
pinnumber flags]

Pad[x1 y1 x2 y2 thickness clearance mask name pinnumber
flags]
   flags |= 0x0100 for rectangular pad
   thickness is added to the length as well as the
length of
   a line. If a pad is wider than it is long, width
and length
   must be swapped and coordinates recalculated.
   Square pads may not be possible at all as they require
   a zero length line.

ElementLine[x1 y1 x2 y2 thickness]

ElementArc[x y width height angle delta thickness]

Mark() is obsolete.

The meaning of clearance and mask needs to be explained
adequately. Is it a radius, diameter, or a delta?
Mask I assume applies to soldermask. What does
clearance apply to? polygons? all other copper?
silkscreen? How does it interact with DRC settings?

[danmc (danmc)]

you are correct, the manual is out of date. I haven't
figured out what the "right" answer (for some reasonable
def. of "right") here is. If you take a look at
src/parse_y.y you'll see the full story, but using a yacc
program as a substitute for a manual is obviously lacking.
The tough thing is that there have been several versions of
PCB's file format and the current pcb program can read all
the old versions. Also various footprints in the library
have been created in various versions.

So I guess I'm open to suggestions on what the most useful
thing would be to have in the manual.

mask is soldermask, clearance is how much to clear when the
pad/pin is enclosed by a plane. I think they are both
diameters, but I'd have to probably do an experiment to say
that with even moderate confidence.

[whitis (whitis-users-sf)]

The answers to the questions abut mask and clearance don't
begin to cover it. People need to know if they are
radiuses, diameters, and whether they are absolute (measured
from center) or relative (measured from the outside of the
feature). "clearance" polygon clearances are measured from
the outside of the copper feature, but are off by a factor
of two. "mask" soldermask clearances are measured from
hole center and
are a diameter (for round pins, edge length for square
pins). So all clearances are off by a factor of two and
soldermask clearances are off by the pin/pad thickness.
Pad soldermasks are even more confusing because the shape is
almost never round (many pins aren't round either).
So, not a single clearance parameter (polygon or mask) seems
to actually be expressed as a true clearance (the distance
between two
copper features).

Here are exceprts from my fix_soldermask program and show how
to convert from true clearance to the non-standard forms
used by xpcb.
All true clearances are in 0.01 mil units measured from the
outside edge
of a pad to the inside edge of the polygon or soldermask.

pin_p->mask = pin_p->thickness + new_mask_clearance * 2;
pin_p->clearance = min_pin_clearance *2;
pin_p->drillinghole = new_hole_diameter;
via_p->mask = via_p->thickness + new_mask_clearance * 2;
via_p->clearance = min_via_clearance *2;
pad_p->mask = pad_p->thickness + new_mask_clearance * 2;
pad_p->clearance = min_pad_clearance * 2;
line_p->clearance = min_line_clearance * 2;

The documentation should at least describe the latest file
format and mention there are older, incompatable, formats.
When the file format is changed, the descriptions could be
archived. It is important to retain
old file format documentation to future proof data.

The existing mish mash of formats that need a yacc/lex
parser is a nightmare. The program should have been
written with an extensible
file format. A properly designed file format would:
   - be readable by all future versions of the software (or
other programs
     that read the format such as utilities and other CAD
software)..
   - be readable by older versions of the software (or other
programs)
     except that newer information will be ignored.

This could be accomplished by:
   - including a resolution parameter. The older format
could have been
     handled by using a default value if resolution was not
specified.
    Switching to square brackets instead of parenthesis was
a very bad
    way to handle this. This is then as simple as adding:
          x *= file_scale;
          y *= file_scale;
          drillinghole *= file_scale;
          etc.
     to the existing parser. People could even look at the
new format
     files with the old program, the board would just have
been magnified
     100x.
   - preferably using an XML file format or at least a
format with named fields.
   - never deleting or moving positional fields
   - add new poisitional fields only to the end of the list
and define default
     values.
   - if not using a sensible format (XML or one with named
parameters), include in the file header lines that name the
positional fields for each record type:
    - if n...

[Bert Timmerman (bert-timmerman)]

An elaboration for square brackets in the file format lives in topic branch "LP699012".

To be continued.

Kind regards,

Bert Timmerman.

[Bert Timmerman (bert-timmerman)]

More commits added to this branch, please review.

Kind regards,

Bert Timmerman.

[Bert Timmerman (bert-timmerman)]

Added documentation for the GTK action Benchmark().

[Bert Timmerman (bert-timmerman)]

Added documentation for the GTK action Busy().

Kind regards,

Bert Timmerman.

[Bert Timmerman (bert-timmerman)]

Added documentation for the GTK action Export().

Kind regards,

Bert Timmerman.

[Bert Timmerman (bert-timmerman)]

Added documentation for the GTK action Load().

Kind regards,

Bert Timmerman.

[Bert Timmerman (bert-timmerman)]

Hi,

I added a start for the Toporouter chapter in the manual and pushed that to this topic branch.

Some behaviour of the toporouter still needs to be analysed to conclude documentation on this chapter.

Oh, and an example with graphics is needed ;-)

Kind regards,

Bert Timmerman.

BTW: I hope to merge this additions to master soonish.

[Bert Timmerman (bert-timmerman)]

Hi,

Merged into master.

I consider the User Manual up to date (enough) and close the bug report.

The User Manual still can use some improvements and additions, which are beyond the scope of this report

If anyone has (another) issue with a part of the manual please open a new bug report.

Kind regards,

Bert Timmeman.