Re: gEDA-user: file format documentation section of manual

["Joel N. Weber II" <jwgeda@xxxxxxxxxxxxx>]

I do think that the documentation would be best off not remaining in
TeXinfo; the lack of support for any sort of graphics in info makes it
pretty pessimal for documenting pcb.  (Contrast that to say, gcc or
coreutils, where there really is very little if anything that would
particularily benefit from any sort of graphics.)

It would be nice if the documentation were to end up in some format
that makes both nice pdfs and nice HTML-with-inline-images, but I'm
not entirely convinced that such a format exists.  TeX (not TeXinfo)
can certainly be used with images if that's desired, and TeX probably
produces nicer looking pdfs if used correctly than openoffice.

I'm under the impression that one can get better diffs out of TeX
source files than out of .sxi files.  It would be ironic for there to
be a document talking about the advantages of ASCII file formats where
that document's source is not stored in such a format.

What I've seen of the organization of the land patterns document did
not immediately convince me that obliterating the existing pcb
documentation and replacing it with something written by the author of
the land patterns document would necessarily be a massive improvement.
I think an incremental approach to improving the documentation would
be better.

The land patterns document tells me near the beginning that if I am
unfamiliar with PCB design, that I should take the time to familiarize
myself with that topic.  If I had no familiarity with PCB layout, I
kind of doubt that www.geda.seul.org and pcb.sf.net are going to tell
me exactly what the author had in mind, and I'm not sure what other
resources I would look at.

Pages 2-6 of the land patterns document seem to be written in a way
that TeXinfo could cope perfectly well with.  I was particularily
disappointed that page 4 didn't show me what that element looks like
graphically, in addition to showing the text that goes into the .pcb
file.

Page 5 of the land patterns tells me to see the glossary on page 23 to
understand what solder mask is.  Why not explain these terms near the
beginning of the document in an introduction to surface mount parts,
so that I don't have to flip through things in a non-linear order?
And in the units section, if you don't like prose, why not show two
examples of the same thing, one with the brackets and the two extra
trailing zeros, and the other with the parenthesis?  You could make
the point with something like this:

        Pad(38 -67 38 -75 28 30 58 "B" "1" 0x00000100)
        Pad[3800 -6700 3800 -7500 2800 3000 5800 "B" "1" 0x00000100)

(I'm not entirely certain that I converted the first line to the
second one correctly to maintain equivalence.)