Re: gEDA-user: PCB file syntax

[Josef Wolf <jw@xxxxxxxxxxxxx>]

On Thu, Oct 21, 2010 at 12:28:45AM -0400, DJ Delorie wrote:
> 
> > Well, there's section 8.9 and there's section 8.10.
> 
> Err, right ;-)
> 
> > Section 8.10 claims to be PCBFlags, that is, (AFAICS) the flags that are
> > located in the top-level "Flags" directive as described in 8.8.10. But
> > both, 8.8.10 and 8.10, talk only about numeric flags, while the directive
> > quoted above contains string flags. Those string flags don't seem to be
> > listed in 8.9 either.
> 
> src/const.h has the PCBFlags documentation, and it's missing names :-P

Well, that was the point I was trying to make ;-)

> > hole      documented for pins+vias,      but has only PIN_TYPES
> PIN_TYPES means PIN_TYPE plus VIA_TYPE.

OK. Then vias can have the "square" flag, too?

> > clearline documented for lines+arcs, but has LINE_TYPE|ARC_TYPE|TEXT_TYPE
> doc bug.

OK

> > fullpoly  documented for polygons,       but has ALL_TYPES
>   { FULLPOLYFLAG, N ("fullpoly"), POLYGON_TYPE},

Oh, I must have confused this with something because code is not in the same
order as documentation.

> > auto      documented for lines+vias,     but has ALL_TYPES
> Shortcut for "everything not already matched"

Maybe this should be better LINE_TYPES|VIA_TYPE then?

> > rubberend documented for lines,          but has LINE_TYPE|ARC_TYPE
> Arcs are a type of line, just curved :-)

Maybe internally, but we are talking about file format. There, Lines and arcs
are different objects with different number and types of attributes.

> > warn      documented for pins+vias+pads, but has only PIN_TYPES|PAD_TYPE
> That's correct.

OK

> > octagon   documented for pins+vias,      but has PIN_TYPES|PAD_TYPE
> Not sure if we support it, but no reason not to parse it.

Well, the documentation should mention the pads, then?

> > usetherm  what does "obsolete" mean? No files with this flag exist?
> We store thermals separately, since we have multiple types and
> per-layer types.

We are talking about the file format, aren't we? I don't see from file syntax
how thermals could be represented there if not with this "obsolete" flag.

> > fullpoly  what's the point of drawing only the biggest part of a polygon?
> Electrical connectivity.

Can you provide an example? Why not define just the biggest part and throw
away everything else? Then connectivity and drawing would be identical. I
still fail to understand.

> > edge2     closer to which edge? Why does this influence orientation?
> It's used for printing the pin names in the pinout window.

The point I tried to make was that the description (in case it is a pad) is
confusing. Assuming, the second point is closer to the edge[1] than the first
one[2], why/how does this influence the orientation of the text?

[1] _which_ edge?
[2] that's a guess, since it is not stated in the description

> > rat       what's the point of storing rat lines in files?
> They're part of the layout?

Huh? How is it useful for rats to be part of the layout in the external file
representation? I understand that netlist/lines/arcs/vias and such things
are part of the layout. But Rats? They can be recalculated at any time (e.g.
at load time) from the netlist and the other objects in the layout.

> > Sorry, I was not about to criticize you. It's just that I got somewhat
> > confused when I tried to understand it.
> 
> My suggestion was innocent - if you want to get involved, this is a
> good place to start.  Documentation is sometimes best written by fresh
> eyes.

I am not going to dive into PCB itself. Instead, I am trying to parse/write
PCB files. For that, an accurate description of the file syntax and its
semantics is very desirable.

Maybe the following patch could be start for improvement?


From 71b4a9c6314b305b3b82b06496a063c0ec4551a0 Mon Sep 17 00:00:00 2001
From: Josef Wolf <jw@xxxxxxxxxxxxx>
Date: Thu, 21 Oct 2010 21:02:45 +0200
Subject: [PATCH] Bring Flags documentation in line with code

---
 src/const.h |   61 ++++++++++++++++++++++++++++++-----------------------------
 1 files changed, 31 insertions(+), 30 deletions(-)

diff --git a/src/const.h b/src/const.h
index 676a6f0..103b0ac 100644
--- a/src/const.h
+++ b/src/const.h
@@ -121,8 +121,8 @@ without a copper annulus.
 If set for a line, indicates that this line is a rat line instead of a
 copper trace.
 @item 0x0010 pininpoly
-For pins and pads, this flag is used internally to indicate that the
-pin or pad overlaps a polygon on some layer.
+For pins, pads and vias, this flag is used internally to indicate that the
+pin/pad/via overlaps a polygon on some layer.
 @item 0x0010 clearpoly
 For polygons, this flag means that pins and vias will normally clear
 these polygons (thus, thermals are required for electrical
@@ -133,10 +133,11 @@ For elements, when set the name of the element is hidden.
 @item 0x0020 showname
 For elements, when set the names of pins are shown.
 @item 0x0020 clearline
-For lines and arcs, the line/arc will clear polygons instead of
+For lines, arcs and texts, the line/arc/text will clear polygons instead of
 connecting to them.
 @item 0x0020 fullpoly
-For polygons, the full polygon is drawn (i.e. all parts instead of only the biggest one).
+For polygons, the full polygon is drawn (i.e. all parts instead of only the
+biggest one).
 @item 0x0040 selected
 Set when the object is selected.
 @item 0x0080 onsolder
@@ -145,9 +146,9 @@ For elements and pads, indicates that they are on the solder side.
 For lines and vias, indicates that these were created by the
 autorouter.
 @item 0x0100 square
-For pins and pads, indicates a square (vs round) pin/pad.
+For pins, pads and vias, indicates a square (vs round) pin/pad/via.
 @item 0x0200 rubberend
-For lines, used internally for rubber band moves.
+For lines and arcs, used internally for rubber band moves.
 @item 0x0200 warn
 For pins, vias, and pads, set to indicate a warning.
 @item 0x0400 usetherm
@@ -156,7 +157,7 @@ fingers.
 @item 0x0400
 Obsolete, old files used this to indicate lines drawn on silk.
 @item 0x0800 octagon
-Draw pins and vias as octagons.
+Draw pins, vias and pads as octagons.
 @item 0x1000 drc
 Set for objects that fail DRC.
 @item 0x2000 lock
@@ -183,7 +184,7 @@ pad.  Primarily used for pads used as fiducials.
 					   support fiducials */
 #define RATFLAG                 0x0010	/* indicates line is a rat line */
 #define PININPOLYFLAG           0x0010	/* pin found inside poly - same as */
-						/* rat line since not used on lines */
+					/* rat line since not used on lines */
 #define CLEARPOLYFLAG           0x0010	/* pins/vias clear these polygons */
 #define HIDENAMEFLAG		0x0010	/* hide the element name */
 #define	DISPLAYNAMEFLAG		0x0020	/* display the names of pins/pads */
@@ -214,52 +215,52 @@ pad.  Primarily used for pads used as fiducials.
 @node PCBFlags
 @section PCBFlags
 @table @code
-@item 0x00001
+@item 0x00001 shownumber
 Pinout displays pin numbers instead of pin names.
-@item 0x00002
+@item 0x00002 localref
 Use local reference for moves, by setting the mark at the beginning of
 each move.
-@item 0x00004
+@item 0x00004 checkplanes
 When set, only polygons and their clearances are drawn, to see if
 polygons have isolated regions.
-@item 0x00008
+@item 0x00008 showdrc
 Display DRC region on crosshair.
-@item 0x00010
+@item 0x00010 rubberband
 Do all move, mirror, rotate with rubberband connections.
-@item 0x00020
+@item 0x00020 description
 Display descriptions of elements, instead of refdes.
-@item 0x00040
+@item 0x00040 nameonpcb
 Display names of elements, instead of refdes.
-@item 0x00080
+@item 0x00080 autodrc
 Auto-DRC flag.  When set, PCB doesn't let you place copper that
 violates DRC.
-@item 0x00100
+@item 0x00100 alldirection
 Enable 'all-direction' lines.
-@item 0x00200
+@item 0x00200 swapstartdir
 Switch starting angle after each click.
-@item 0x00400
+@item 0x00400 uniquename
 Force unique names on board.
-@item 0x00800
+@item 0x00800 clearnew
 New lines/arc clear polygons.
-@item 0x01000
+@item 0x01000 snappin
 Crosshair snaps to pins and pads.
-@item 0x02000
+@item 0x02000 showmask
 Show the solder mask layer.
-@item 0x04000
+@item 0x04000 thindraw
 Draw with thin lines.
-@item 0x08000
+@item 0x08000 orthomove
 Move items orthogonally.
-@item 0x10000
+@item 0x10000 liveroute
 Draw autoroute paths real-time.
-@item 0x20000
+@item 0x20000 thindrawpoly
 New polygons are full ones.
-@item 0x40000
+@item 0x40000 locknames
 Names are locked, the mouse cannot select them.
-@item 0x80000
+@item 0x80000 onlynames
 Everything but names are locked, the mouse cannot select anything else.
-@item 0x100000
+@item 0x100000 newfullpoly
 New polygons are full polygons.
-@item 0x200000
+@item 0x200000 hidenames
 When set, element names are not drawn.
 @end table
 %end-doc */
-- 
1.6.4.2



_______________________________________________
geda-user mailing list
geda-user@xxxxxxxxxxxxxx
http://www.seul.org/cgi-bin/mailman/listinfo/geda-user