README
1 README for Document Writers 2 3 Adding files: 4 ------------- 5 The submakefile, docs.xml and index.tmpl must be updated to add a file to the documents. 6 7 docs.xml is used to create the "previous" and "next" buttons at the top of each individual html document. 8 it should generally match the order of the index.tmpl 9 10 Notes on LinuxCNC documentation: 11 ---------------------------- 12 The main LinuxCNC makefile can optionally build the documentation and 13 other files in this directory tree. Use --enable-build-documentation when 14 invoking src/configure, and run make from src 15 16 Notes about drawings: 17 --------------------- 18 Many of the documents include drawings. Most of them were originally 19 created using EasyCad, a non-free Windows app, then exported to .eps files 20 and included in the the docs. The original 'source' files (EasyCad .FC7 21 format) were not usable on a free system. To fix this problem, all of 22 the source files have been converted to .dxf files, and added to git. 23 The .dxf files can be edited with multiple CAD packages, and serve as the 24 'source' files for future changes to the drawings. They can be converted 25 from .dxf to postscript (not .eps) using Qcad, which is available as an 26 ubuntu package (and I believe also available for debian). 27 28 Unfortunately, EasyCad (and AutoCad) support a number of entities 29 that Qcad does not import properly. Including some that were used 30 in the LinuxCNC drawings: filled circles, filled arrowheads, non-zero 31 width lines, and dashed lines. Qcad renders filled circles as 32 hollow, it renders all lines the same width, and it renders dashed 33 lines as solid, unless you tell it to do otherwise. All of these 34 things make the drawings less attractive, but are somewhat 35 acceptable. However, Qcad doesn't import filled arrowheads at all, 36 which seriously hurts the drawings. So EasyCad was used to convert 37 the arrowheads to hollow before exporting them. Hollow arrowheads 38 don't look as nice as solid ones, but at least they are visible. 39 40 Once exported, the arrowheads lose their relationship with the line they 41 are on, and and need to be moved and/or rotated manually if the line is 42 moved. I believe that even if they were imported back into EasyCad, the 43 line/arrow connection would remain broken. New lines with 44 arrowheads can be created in Qcad with the 'leader' dimension tool. 45 46 Because the original EPS files with filled lines and circles, wide lines, 47 and dashed lines look so much nicer, they will remain in git and should 48 probably be used for the documents, however if they become inaccurate 49 because of changes in the software, we will have to edit the DXF files, 50 generate postscript, and use the less pretty but factually corrrect 51 images. 52 53 Since Qcad itself is a GUI application, the dxf to postscript conversion 54 involves going clicky clicky, and can't be automated and made part of the 55 makefile. Also, not everyone will have Qcad installed on their system. 56 Therefore, we will store both the DXF files and the resulting postscript 57 files in git, and the normal documentation build process will use the 58 postscript files only. If/when the dxf files are edited, they will need 59 to be converted to postscript manually. The conversion procedure is as 60 follows: 61 62 start qcad 63 File->Open-> choose dxf file 64 drawing appears in window 65 Edit->CurrentDrawingPreferences->Paper 66 set paper size to "letter", set orientation to "landscape" or "portrait" 67 depending on the aspect ratio of the drawing 68 File->PrintPreview 69 click the "fit to page" button on the toolbar (last button on the right at 70 least on version 2.0.4.0 of qcad) 71 File->Print 72 select "print to file" 73 set the path to point to the same directory as the source .dxf file 74 set the name to be the same as the source file, but .ps instead of .dxf 75 click OK 76 77 The makers of Qcad also have a GPL'ed format converter called vec2web, 78 which can do dxf to postscript conversion from the command line. It 79 is not available as a precompiled package, but is available in source 80 form from http://www.ribbonsoft.com/vec2web.html 81 82 vec2web depends on qt3 development packages for compilation, so it should 83 not be a dependency for building the LinuxCNC docs. But if configure can 84 detect it, it would be nice to automate conversion from dxf to ps for those 85 systems where vec2web is installed. 86 87 To build vec2web, I had to apt-get install qt3-dev-tools 88 The vec2web tarball contains a build script, but before you run it you 89 must set $QTDIR to point at your QT3 installation - in my case it was 90 export QTDIR=/usr/share/qt3 91 Then run the build script: 92 ./build_vec2web.sh 93 There is no install step, the executable gets dumped in the build directory. 94 There is also no man page, but running it with no args prints the following 95 usage instructions: 96 97 Usage: vec2web <input file> <output file> [options] 98 Where options are: 99 -x # maximum x size for the output bitmap in pixel 100 -y # maximum y size for the output bitmap in pixel 101 -b black/white instead of using colors 102 -o [l|p] orientation for PS output (landscape or portrait) 103 -s .. page size for PS output (A4, A5) 104 105 e.g. vec2web drawing.dxf drawing.png 106 converts drawing.dxf to a portable network graphic 107 108 My initial attempts to use vec2web resulted in the graphical parts of the 109 drawing being converted, but all text was lost. I don't know if vec2web is 110 worth spending much more time on, however, it _is_ GPL, and it includes a 111 library for reading DXF files which might be a worthwhile thing to the 112 Linux CNC community. 113 114 Drawings from QCad 115 ------------------- 116 Save as .dxf to same directory as the image 117 Set line thickness to 0.50mm 118 Export image as 480 x 480 Resolution Auto .png 119 120 121 How to add a new translation language 122 ------------------------------------- 123 124 Add the asciidoc source files that will contain your new translation. 125 Usually that means copying the language files for one of the existing 126 languages, probably English since that's usually the most up to date. 127 128 Add the new files to the proper place in docs/src/Submakefile, to ensure 129 they'll get built. 130 131 Edit debian/control.in to add the new linuxcnc-doc-$NEWLANG package. 132 Add the new doc package to the or-list of the Recommends line of the 133 linuxcnc/linuxcnc-sim package. 134 135 Add the new language to the DOCS_PACKAGES variable in debian/configure. 136 If there is a texlive-lang-$NEWLANGUAGE package for your new language, 137 add it to all the appropriate EXTRA_BUILD lines in debian/configure. 138 139 Add the 'linuxcnc-doc-$NEWLANG.files.in' file for the new package, probably 140 by copying and editing "debian/linuxcnc-doc-en.files.in". 141 142 Test build the packages and verify! 143