Yesterday I finally started with working on a complete overhaul of the “Getting started in KiCad” document.
So far I managed to:
Create gitlab account.
Struggling a bit with git: Cloned documentation repositity.
Reading some stuff about Ascii doc…
Limit the build of the documentation to only the “Getting started…” and only in English. (Buils now in 20s instead of 20 minutes on my slow pc).
Changed a few lines of text and images to test the build system.
So now I finally seem to have a workable setup to do some serious work on this document. (I stated my intention to do this back in 2019-04.)
I noticed that the cheatsheet has become a part of the official documentation:
kicad-doc/src/cheatsheet/kicad-cheatsheet.svg
A link to this cheatsheet is a usefull addition to the "Getting started in … " guide but to my horror I could no easy accessable way for beginners to access this document. For example it does not have an entry in: https://docs.kicad.org/
I could try to add it as an addendum to the “Getting started…” guide, but it think it’s better if it remains a separate single page document that is easily printable.
On my linux box a lot of documentation is installed in:
/usr/share/doc/kicad/help
but the cheatsheet is not among them.
I’m having some consentration problems (have so for years) and am trying to put my blinds on and focus on the “Getting started …” guide.
Can someone be so kind to make the cheatsheet better accessible and post a link so I can add that link to the “Getting started …” guide?
But… they are based on KiCad 2 years ago, and a lot has changed. First thing I noticed right away is workflow change, the cheatsheet indicates using the netlist file. I haven’t looked closely enough to spot any other differences.
Don’t get me wrong. I’m not suggesting that you update the cheatsheet, nor am I volunteering. Just pointing out that it should be added to the list for updates or abandoned.
A link to (or inclusion of) the cheatsheet in the “Getting started …” guide would be nice, but I will not put a link to gitlab in “Getting started …”.
If the cheatsheet was accesible via: https://docs.kicad.org/ I would already be happy for now.
(Euhm, the cheatsheet mentions CvPcb, but not the Edit Symbol Fields
spreadsheet. Maybe it’s better to skip the whole cheatsheet untill that is updated. I’m trying really hard to not get side tracked into that document right now).
Also: Cheatsheet is .svg, and I just started working with asciidoc.
Maybe I’ll do .svg when InkScape reaches V1.0.
Just curious: what’s wrong with a direct link to gitlab? You could be able to specify a link to the raw file directly, and if you use a URL shortener, then it might even be suitable for a printed sheet.
Gitlab is a site for sofware developers. It is not a place to point beginners to.
I also do not like those shortened URL’s. There is no guarantee they will still work next year or next week.
Even worse: In my current browser the link does not even work. Instead of rendering the .svg, it displays the text in my browser.
Stuff like that looks “unprofessional” and scares beginners away.
I try to keep to keep things simple and coherent. There is a websited dedicated to KiCad, and on that website there is a section about documentation for KiCad.
That is also the most logical place where beginners with KiCad will probably look for information.
If the Cheatsheet is good enough to be worthy of a place in the official repository on gitlab, it should also have a place on https://docs.kicad.org/
Fair enough. The svg displays properly in my browser (svg mobile), but if you want to distribute another type of file in the KiCAD docs, do you know how the documentation generator would compile it? Or perhaps the server needs to feed a different header to your browser, not sure.
The documentation generator seems to be based here. Can that be modified to include the svg files properly?
The Doxyfile only references SVG in reference to directory listings and graphvis, but it does include the following comment:
# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
# enable generation of interactive SVG images that allow zooming and panning.
#
# Note that this requires a modern browser other than Internet Explorer. Tested
# and working are Firefox, Chrome, Safari, and Opera.
# Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make
# the SVG files visible. Older versions of IE do not have SVG support.
# The default value is: NO.
# This tag requires that the tag HAVE_DOT is set to YES.
It seems to me most beginners would have a compatible modern browser.
Here is some older information about how to include images in Doxygen, but it seems to imply that SVG is a usable output of Doxygen.
Not sure where to go from here, maybe someone else will chime in.
My complaint is with printing the cheatsheet. My laser printer is set up with U.S.Letter-sized paper, which is 17.6 mm shorter and 5.9 mm wider than the default A4-sized paper.
I downloaded the kicad-cheatsheet.png file and opened it with Inkscape. I reset the page size to
215.9 mm wide by 279.4 mm tall. Then I exported it to (default filename) bitmap.png. Unfortunately, when I opened this file with okular, its top was cut off, right through the KiCad cheatsheet logo.
I am not experienced enough with Inkscape to know if it has the ability to transform the A4-sized rectangular image to the USLetter-sized rectangular image. Does anybody know? Or do I need some other linux application program to do this resizing?
You could try to print the file directly (with Inkscape for example) and select the proper paper size (Letter in your case I believe) then let the printer software make the resize for you (using the option of your printer: autoscale, fit to page, auto resize, etc.)
You might be able to reduce the image overall. I’ve always thought that international facing documents should be created assuming 210mm width (A4) and 279mm height (from US-Letter). If printing margins are included, then it could be printed world wide. If 12mm margins all around are included, we end up with 186mm x 255mm printable area.
@der.ule, I tried your technique. It worked, but not perfectly.
I reopened kicad_cheatsheet.png in Inkscape and did a File…Save As…kicad_cheatsheet555.pdf, selecting the default PDF 1.5 format.
Then I printed the PDF file from okular. It doesn’t cut off the top KiCad logo. That’s good. However, it cuts off Anthony Gautier’s byline at the bottom. Not perfect, but usable, and much better than the ways I tried.
I did not expect either program to scale the image from A4 to USLetter. Inkscape writes to .svg, which is a scaled vector graphics type file. I think PDF files are bitmap graphics file (please correct me if I am wrong about this.) Maybe some other linux application program can scale a .png file or a .svg file? There may be another work-around, but I am not yet motivated to search for the perfect technique.
There might even be an option inside Inkscape 0.92 that I don’t know about to do this. I am a novice with this program. The work-around @der.ule suggested is good enough for now.
I just did a couple of tests and this is how it worked for me:
Front inkscape print to pdf file on the original A4 size, from the pdf file print to pdf file but now selecting size Letter and letting the printer driver to “resize to margins”.
Greg, I tried your suggestion by exporting the pdf file from Inkscape after resizing it to 210 mm wide by 279 mm high. (Inkscape saved it to kicad-cheatsheet.higreg.pdf.png) When I opened it in Inkscape, the top KiCad cheatsheet logo was cut off.
@der.ule,
I printed your test_a4.pdf in okular. After remembering to change okular’s default paper size from A4 to USLetter, it printed perfectly.
Thank you for providing a solution. You are a big help.
Unfortunately, your second file did not print perfectly.
Where is this .png file? I just know about the .svg files. (Or did you type .png in error…)
.svg files = primarily vector graphics files (I think you can embed bitmaps, but they are primarily used for vector graphics). Except for embedded bitmaps, you can zoom into these files and never see jaggies until you hit the mathematical limit of your system/software. And svg actually stands for “Scalable Vector Graphics”.
.pdf files = Page layout container format. It can contain vector graphics in a subset of PostScript, it can contain bitmaps, and it can contain font data for the embedded text. When you scan paper to pdf in your all-in-one printer you get page sized bitmaps inside the pdf container. If you save out of Word, LibreOffice, Inkscape, KiCad, etc (IMHO properly) you should have primarily vector format (may contain vector format files). I’ve come across the occasional pdf virtual print driver that rasterizes and saves as page-sized bitmaps in a pdf container.
.png files = Always a bitmap file. Zoom in enough and you see jaggies, microscopic detail below the saved resolution is non-existant.
